@amplitude/analytics-react-native 0.0.1-dev.8 → 0.1.1

package/src/react-native-client.ts

@@ -0,0 +1,339 @@
+import { AmplitudeCore, Destination, returnWrapper } from '@amplitude/analytics-core';
+import {
+  ReactNativeConfig,
+  Campaign,
+  ReactNativeOptions,
+  AdditionalReactNativeOptions,
+  AttributionReactNativeOptions,
+} from '@amplitude/analytics-types';
+import { Context } from './plugins/context';
+import { useReactNativeConfig, createDeviceId, createFlexibleStorage } from './config';
+import { parseOldCookies } from './cookie-migration';
+import { CampaignTracker } from './attribution/campaign-tracker';
+import { isNative } from './utils/platform';
+import { IdentityEventSender } from './plugins/identity';
+import { getAnalyticsConnector } from './utils/analytics-connector';
+
+export class AmplitudeReactNative extends AmplitudeCore<ReactNativeConfig> {
+  async init(apiKey: string, userId?: string, options?: ReactNativeOptions & AdditionalReactNativeOptions) {
+    // Step 1: Read cookies stored by old SDK
+    const oldCookies = await parseOldCookies(apiKey, options);
+
+    // Step 2: Create react native config
+    const reactNativeOptions = await useReactNativeConfig(apiKey, userId || oldCookies.userId, {
+      ...options,
+      deviceId: oldCookies.deviceId ?? options?.deviceId,
+      sessionId: oldCookies.sessionId ?? options?.sessionId,
+      optOut: options?.optOut ?? oldCookies.optOut,
+      lastEventTime: oldCookies.lastEventTime,
+    });
+    await super._init(reactNativeOptions);
+
+    // Step 3: Manage session
+    let isNewSession = false;
+    if (
+      !this.config.sessionId ||
+      (this.config.lastEventTime && Date.now() - this.config.lastEventTime > this.config.sessionTimeout)
+    ) {
+      // Either
+      // 1) No previous session; or
+      // 2) Previous session expired
+      this.config.sessionId = Date.now();
+      isNewSession = true;
+    }
+
+    const connector = getAnalyticsConnector();
+    connector.eventBridge.setEventReceiver((event) => {
+      void this.track(event.eventType, event.eventProperties);
+    });
+    connector.identityStore.setIdentity({
+      userId: this.config.userId,
+      deviceId: this.config.deviceId,
+    });
+
+    // Step 4: Install plugins
+    // Do not track any events before this
+    await this.add(new Context());
+    await this.add(new IdentityEventSender());
+    await this.add(new Destination());
+
+    // Step 5: Set timeline ready for processing events
+    // Send existing events, which might be collected by track before init
+    this.timeline.isReady = true;
+    if (!this.config.optOut) {
+      this.timeline.scheduleApply(0);
+    }
+
+    // Step 6: Track attributions
+    await this.runAttributionStrategy(options?.attribution, isNewSession);
+  }
+
+  async runAttributionStrategy(attributionConfig?: AttributionReactNativeOptions, isNewSession = false) {
+    if (isNative()) {
+      return;
+    }
+    const track = this.track.bind(this);
+    const onNewCampaign = this.setSessionId.bind(this, Date.now());
+
+    const storage = await createFlexibleStorage<Campaign>(this.config);
+    const campaignTracker = new CampaignTracker(this.config.apiKey, {
+      ...attributionConfig,
+      storage,
+      track,
+      onNewCampaign,
+    });
+
+    await campaignTracker.send(isNewSession);
+  }
+
+  getUserId() {
+    return this.config.userId;
+  }
+
+  setUserId(userId: string | undefined) {
+    this.config.userId = userId;
+    getAnalyticsConnector()
+      .identityStore.editIdentity()
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      .setUserId(userId)
+      .commit();
+  }
+
+  getDeviceId() {
+    return this.config.deviceId;
+  }
+
+  setDeviceId(deviceId: string) {
+    this.config.deviceId = deviceId;
+    getAnalyticsConnector()
+      .identityStore.editIdentity()
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      .setDeviceId(deviceId)
+      .commit();
+  }
+
+  regenerateDeviceId() {
+    const deviceId = createDeviceId();
+    this.setDeviceId(deviceId);
+  }
+
+  getSessionId() {
+    return this.config.sessionId;
+  }
+
+  setSessionId(sessionId: number) {
+    this.config.sessionId = sessionId;
+  }
+
+  setOptOut(optOut: boolean) {
+    this.config.optOut = optOut;
+  }
+}
+
+const client = new AmplitudeReactNative();
+
+/**
+ * Initializes the Amplitude SDK with your apiKey, userId and optional configurations.
+ * This method must be called before any other operations.
+ *
+ * ```typescript
+ * await init(API_KEY, USER_ID, options).promise;
+ * ```
+ */
+export const init = returnWrapper(client.init.bind(client));
+
+/**
+ * Adds a new plugin.
+ *
+ * ```typescript
+ * const plugin = {...};
+ * amplitude.add(plugin);
+ * ```
+ */
+export const add = returnWrapper(client.add.bind(client));
+
+/**
+ * Removes a plugin.
+ *
+ * ```typescript
+ * amplitude.remove('myPlugin');
+ * ```
+ */
+export const remove = returnWrapper(client.remove.bind(client));
+
+/**
+ * Tracks user-defined event, with specified type, optional event properties and optional overwrites.
+ *
+ * ```typescript
+ * // event tracking with event type only
+ * track('Page Load');
+ *
+ * // event tracking with event type and additional event properties
+ * track('Page Load', { loadTime: 1000 });
+ *
+ * // event tracking with event type, additional event properties, and overwritten event options
+ * track('Page Load', { loadTime: 1000 }, { sessionId: -1 });
+ *
+ * // alternatively, this tracking method is awaitable
+ * const result = await track('Page Load').promise;
+ * console.log(result.event); // {...}
+ * console.log(result.code); // 200
+ * console.log(result.message); // "Event tracked successfully"
+ * ```
+ */
+export const track = returnWrapper(client.track.bind(client));
+
+/**
+ * Alias for track()
+ */
+export const logEvent = returnWrapper(client.logEvent.bind(client));
+
+/**
+ * Sends an identify event containing user property operations
+ *
+ * ```typescript
+ * const id = new Identify();
+ * id.set('colors', ['rose', 'gold']);
+ * identify(id);
+ *
+ * // alternatively, this tracking method is awaitable
+ * const result = await identify(id).promise;
+ * console.log(result.event); // {...}
+ * console.log(result.code); // 200
+ * console.log(result.message); // "Event tracked successfully"
+ * ```
+ */
+export const identify = returnWrapper(client.identify.bind(client));
+
+/**
+ * Sends a group identify event containing group property operations.
+ *
+ * ```typescript
+ * const id = new Identify();
+ * id.set('skills', ['js', 'ts']);
+ * const groupType = 'org';
+ * const groupName = 'engineering';
+ * groupIdentify(groupType, groupName, id);
+ *
+ * // alternatively, this tracking method is awaitable
+ * const result = await groupIdentify(groupType, groupName, id).promise;
+ * console.log(result.event); // {...}
+ * console.log(result.code); // 200
+ * console.log(result.message); // "Event tracked successfully"
+ * ```
+ */
+export const groupIdentify = returnWrapper(client.groupIdentify.bind(client));
+export const setGroup = returnWrapper(client.setGroup.bind(client));
+
+/**
+ * Sends a revenue event containing revenue property operations.
+ *
+ * ```typescript
+ * const rev = new Revenue();
+ * rev.setRevenue(100);
+ * revenue(rev);
+ *
+ * // alternatively, this tracking method is awaitable
+ * const result = await revenue(rev).promise;
+ * console.log(result.event); // {...}
+ * console.log(result.code); // 200
+ * console.log(result.message); // "Event tracked successfully"
+ * ```
+ */
+export const revenue = returnWrapper(client.revenue.bind(client));
+
+/**
+ * Returns current user ID.
+ *
+ * ```typescript
+ * const userId = getUserId();
+ * ```
+ */
+export const getUserId = client.getUserId.bind(client);
+
+/**
+ * Sets a new user ID.
+ *
+ * ```typescript
+ * setUserId('userId');
+ * ```
+ */
+export const setUserId = client.setUserId.bind(client);
+
+/**
+ * Returns current device ID.
+ *
+ * ```typescript
+ * const deviceId = getDeviceId();
+ * ```
+ */
+export const getDeviceId = client.getDeviceId.bind(client);
+
+/**
+ * Sets a new device ID.
+ * When setting a custom device ID, make sure the value is sufficiently unique.
+ * A uuid is recommended.
+ *
+ * ```typescript
+ * setDeviceId('deviceId');
+ * ```
+ */
+export const setDeviceId = client.setDeviceId.bind(client);
+
+/**
+ * Regenerates a new random deviceId for current user. Note: this is not recommended unless you know what you
+ * are doing. This can be used in conjunction with `setUserId(undefined)` to anonymize users after they log out.
+ * With an `unefined` userId and a completely new deviceId, the current user would appear as a brand new user in dashboard.
+ *
+ * ```typescript
+ * regenerateDeviceId();
+ * ```
+ */
+export const regenerateDeviceId = client.regenerateDeviceId.bind(client);
+
+/**
+ * Returns current session ID.
+ *
+ * ```typescript
+ * const sessionId = getSessionId();
+ * ```
+ */
+export const getSessionId = client.getSessionId.bind(client);
+
+/**
+ * Sets a new session ID.
+ * When settign a custom session ID, make sure the value is in milliseconds since epoch (Unix Timestamp).
+ *
+ * ```typescript
+ * setSessionId(Date.now());
+ * ```
+ */
+export const setSessionId = client.setSessionId.bind(client);
+
+/**
+ * Sets a new optOut config value. This toggles event tracking on/off.
+ *
+ *```typescript
+ * // Stops tracking
+ * setOptOut(true);
+ *
+ * // Starts/resumes tracking
+ * setOptOut(false);
+ * ```
+ */
+export const setOptOut = client.setOptOut.bind(client);
+
+/**
+ * Flush and send all the events which haven't been sent.
+ *
+ *```typescript
+ * // Send all the unsent events
+ * flush();
+ *
+ * // alternatively, this tracking method is awaitable
+ * await flush().promise;
+ * ```
+ */
+export const flush = returnWrapper(client.flush.bind(client));

package/src/session-manager.ts

@@ -0,0 +1,81 @@
+import { UserSession, Storage, SessionManager as ISessionManager } from '@amplitude/analytics-types';
+import { getCookieName as getStorageKey } from './utils/cookie-name';
+
+export class SessionManager implements ISessionManager {
+  storageKey: string;
+  cache: UserSession;
+  isSessionCacheValid = true;
+
+  constructor(private storage: Storage<UserSession>, apiKey: string) {
+    this.storageKey = getStorageKey(apiKey);
+    this.cache = { optOut: false };
+  }
+
+  /**
+   * load() must be called immediately after instantation
+   *
+   * ```ts
+   * await new SessionManager(...).load();
+   * ```
+   */
+  async load() {
+    this.cache = (await this.storage.get(this.storageKey)) ?? {
+      optOut: false,
+    };
+    return this;
+  }
+
+  setSession(session: Partial<UserSession>) {
+    this.cache = { ...this.cache, ...session };
+    void this.storage.set(this.storageKey, this.cache);
+  }
+
+  getSessionId() {
+    this.isSessionCacheValid = true;
+    void this.storage.get(this.storageKey).then((userSession) => {
+      // Checks if session id has been set since the last get
+      if (this.isSessionCacheValid) {
+        this.cache.sessionId = userSession?.sessionId;
+      }
+    });
+    return this.cache.sessionId;
+  }
+
+  setSessionId(sessionId: number) {
+    // Flags session id has been set
+    this.isSessionCacheValid = false;
+    this.setSession({ sessionId });
+  }
+
+  getDeviceId(): string | undefined {
+    return this.cache.deviceId;
+  }
+
+  setDeviceId(deviceId: string): void {
+    this.setSession({ deviceId });
+  }
+
+  getUserId(): string | undefined {
+    return this.cache.userId;
+  }
+
+  setUserId(userId: string): void {
+    this.setSession({ userId });
+  }
+
+  getLastEventTime() {
+    return this.cache.lastEventTime;
+  }
+
+  setLastEventTime(lastEventTime: number) {
+    this.setSession({ lastEventTime });
+  }
+
+  getOptOut(): boolean {
+    return this.cache.optOut;
+  }
+
+  setOptOut(optOut: boolean): void {
+    this.setSession({ optOut });
+  }
+}

package/src/storage/cookie.ts

@@ -0,0 +1,97 @@
+import { Storage, CookieStorageOptions } from '@amplitude/analytics-types';
+import { isNative } from '../utils/platform';
+
+export class CookieStorage<T> implements Storage<T> {
+  options: CookieStorageOptions;
+
+  constructor(options?: CookieStorageOptions) {
+    this.options = { ...options };
+  }
+
+  async isEnabled(): Promise<boolean> {
+    /* istanbul ignore if */
+    if (isNative() || typeof window === 'undefined') {
+      return false;
+    }
+
+    const random = String(Date.now());
+    const testStrorage = new CookieStorage<string>();
+    const testKey = 'AMP_TEST';
+    try {
+      await testStrorage.set(testKey, random);
+      const value = await testStrorage.get(testKey);
+      return value === random;
+    } catch {
+      /* istanbul ignore next */
+      return false;
+    } finally {
+      await testStrorage.remove(testKey);
+    }
+  }
+
+  async get(key: string): Promise<T | undefined> {
+    let value = await this.getRaw(key);
+    if (!value) {
+      return undefined;
+    }
+    try {
+      try {
+        value = decodeURIComponent(atob(value));
+      } catch {
+        // value not encoded
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return JSON.parse(value);
+    } catch {
+      /* istanbul ignore next */
+      return undefined;
+    }
+  }
+
+  async getRaw(key: string): Promise<string | undefined> {
+    const cookie = window.document.cookie.split('; ');
+    const match = cookie.find((c) => c.indexOf(key + '=') === 0);
+    if (!match) {
+      return undefined;
+    }
+    return match.substring(key.length + 1);
+  }
+
+  async set(key: string, value: T | null): Promise<void> {
+    try {
+      const expirationDays = this.options.expirationDays ?? 0;
+      const expires = value !== null ? expirationDays : -1;
+      let expireDate: Date | undefined = undefined;
+      if (expires) {
+        const date = new Date();
+        date.setTime(date.getTime() + expires * 24 * 60 * 60 * 1000);
+        expireDate = date;
+      }
+      let str = `${key}=${btoa(encodeURIComponent(JSON.stringify(value)))}`;
+      if (expireDate) {
+        str += `; expires=${expireDate.toUTCString()}`;
+      }
+      str += '; path=/';
+      if (this.options.domain) {
+        str += `; domain=${this.options.domain}`;
+      }
+      if (this.options.secure) {
+        str += '; Secure';
+      }
+      if (this.options.sameSite) {
+        str += `; SameSite=${this.options.sameSite}`;
+      }
+      window.document.cookie = str;
+    } catch {
+      //
+    }
+  }
+
+  async remove(key: string): Promise<void> {
+    await this.set(key, null);
+  }
+
+  async reset(): Promise<void> {
+    return;
+  }
+}

package/src/storage/local-storage.ts

@@ -0,0 +1,67 @@
+import { Storage } from '@amplitude/analytics-types';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+export class LocalStorage<T> implements Storage<T> {
+  async isEnabled(): Promise<boolean> {
+    /* istanbul ignore if */
+    if (typeof window === 'undefined') {
+      return false;
+    }
+
+    const random = String(Date.now());
+    const testStorage = new LocalStorage<string>();
+    const testKey = 'AMP_TEST';
+    try {
+      await testStorage.set(testKey, random);
+      const value = await testStorage.get(testKey);
+      return value === random;
+    } catch {
+      /* istanbul ignore next */
+      return false;
+    } finally {
+      await testStorage.remove(testKey);
+    }
+  }
+
+  async get(key: string): Promise<T | undefined> {
+    try {
+      const value = await this.getRaw(key);
+      if (!value) {
+        return undefined;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return JSON.parse(value);
+    } catch {
+      /* istanbul ignore next */
+      return undefined;
+    }
+  }
+
+  async getRaw(key: string): Promise<string | undefined> {
+    return (await AsyncStorage.getItem(key)) || undefined;
+  }
+
+  async set(key: string, value: T): Promise<void> {
+    try {
+      await AsyncStorage.setItem(key, JSON.stringify(value));
+    } catch {
+      //
+    }
+  }
+
+  async remove(key: string): Promise<void> {
+    try {
+      await AsyncStorage.removeItem(key);
+    } catch {
+      //
+    }
+  }
+
+  async reset(): Promise<void> {
+    try {
+      await AsyncStorage.clear();
+    } catch {
+      //
+    }
+  }
+}

package/src/storage/utm-cookie.ts

@@ -0,0 +1,27 @@
+import { CookieStorage } from './cookie';
+
+export class UTMCookie extends CookieStorage<Record<string, string | undefined>> {
+  async get(key: string): Promise<Record<string, string | undefined> | undefined> {
+    try {
+      const value = await this.getRaw(key);
+      if (!value) {
+        return undefined;
+      }
+      const entries = value.split('.').splice(-1)[0].split('|');
+      return entries.reduce<Record<string, string | undefined>>((acc, curr) => {
+        const [key, value = ''] = curr.split('=', 2);
+        if (!value) {
+          return acc;
+        }
+        acc[key] = decodeURIComponent(value);
+        return acc;
+      }, {});
+    } catch {
+      return undefined;
+    }
+  }
+
+  async set(): Promise<void> {
+    return undefined;
+  }
+}

package/src/transports/fetch.ts

@@ -0,0 +1,23 @@
+import { BaseTransport } from '@amplitude/analytics-core';
+import { Payload, Response, Transport } from '@amplitude/analytics-types';
+
+export class FetchTransport extends BaseTransport implements Transport {
+  async send(serverUrl: string, payload: Payload): Promise<Response | null> {
+    /* istanbul ignore if */
+    if (typeof fetch === 'undefined') {
+      throw new Error('FetchTransport is not supported');
+    }
+    const options: RequestInit = {
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: '*/*',
+      },
+      body: JSON.stringify(payload),
+      method: 'POST',
+    };
+    const response = await fetch(serverUrl, options);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const responsePayload: Record<string, any> = await response.json();
+    return this.buildResponse(responsePayload);
+  }
+}

package/src/typings/browser-snippet.d.ts

@@ -0,0 +1,7 @@
+import { InstanceProxy } from '@amplitude/analytics-types';
+
+declare global {
+  // globalThis only includes `var` declarations
+  // eslint-disable-next-line no-var
+  var amplitude: InstanceProxy & { invoked: boolean };
+}

package/src/typings/ua-parser.d.ts

@@ -0,0 +1,4 @@
+declare module '@amplitude/ua-parser-js' {
+  import UAParser from 'ua-parser-js';
+  export = UAParser;
+}

package/src/utils/analytics-connector.ts

@@ -0,0 +1,5 @@
+import { AnalyticsConnector } from '@amplitude/analytics-connector';
+
+export const getAnalyticsConnector = (): AnalyticsConnector => {
+  return AnalyticsConnector.getInstance('$default_instance');
+};

package/src/utils/cookie-name.ts

@@ -0,0 +1,9 @@
+import { AMPLITUDE_PREFIX } from '@amplitude/analytics-core';
+
+export const getCookieName = (apiKey: string, postKey = '', limit = 10) => {
+  return [AMPLITUDE_PREFIX, postKey, apiKey.substring(0, limit)].filter(Boolean).join('_');
+};
+
+export const getOldCookieName = (apiKey: string) => {
+  return `${AMPLITUDE_PREFIX.toLowerCase()}_${apiKey.substring(0, 6)}`;
+};

package/src/utils/language.ts

@@ -0,0 +1,7 @@
+export const getLanguage = (): string => {
+  if (typeof navigator === 'undefined') return '';
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  const userLanguage = (navigator as any).userLanguage as string | undefined;
+
+  return navigator.languages?.[0] ?? navigator.language ?? userLanguage ?? '';
+};

package/src/utils/platform.ts

@@ -0,0 +1,9 @@
+import { Platform } from 'react-native';
+
+export const isWeb = (): boolean => {
+  return Platform.OS === 'web';
+};
+
+export const isNative = (): boolean => {
+  return !isWeb();
+};