@amplitude/analytics-react-native 0.0.1-dev.0

package/src/plugins/context.ts

@@ -0,0 +1,106 @@
+import { BeforePlugin, ReactNativeConfig, Event, PluginType } from '@amplitude/analytics-types';
+import UAParser from '@amplitude/ua-parser-js';
+import { UUID } from '@amplitude/analytics-core';
+import { getLanguage } from '../utils/language';
+import { VERSION } from '../version';
+import { NativeModules } from 'react-native';
+
+const BROWSER_PLATFORM = 'Web';
+const IP_ADDRESS = '$remote';
+
+type NativeContext = {
+  version: string;
+  platform: string;
+  language: string;
+  os_name: string;
+  os_version: string;
+  device_brand: string;
+  device_manufacturer: string;
+  device_model: string;
+  carrier: string;
+};
+
+export interface AmplitudeReactNative {
+  getApplicationContext(): Promise<NativeContext>;
+}
+
+export class Context implements BeforePlugin {
+  name = 'context';
+  type = PluginType.BEFORE as const;
+
+  // this.config is defined in setup() which will always be called first
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  config: ReactNativeConfig;
+  eventId = 0;
+  uaResult: UAParser.IResult;
+  nativeModule: AmplitudeReactNative | undefined = NativeModules.AmplitudeReactNative as
+    | AmplitudeReactNative
+    | undefined;
+  library = `amplitude-ts/${VERSION}`;
+
+  constructor() {
+    let agent: string | undefined;
+    /* istanbul ignore else */
+    if (typeof navigator !== 'undefined') {
+      agent = navigator.userAgent;
+    }
+    this.uaResult = new UAParser(agent).getResult();
+  }
+
+  setup(config: ReactNativeConfig): Promise<undefined> {
+    this.config = config;
+    return Promise.resolve(undefined);
+  }
+
+  async execute(context: Event): Promise<Event> {
+    /**
+     * Manages user session triggered by new events
+     */
+    if (!this.isSessionValid()) {
+      // Creates new session
+      this.config.sessionId = Date.now();
+    } // else use previously creates session
+    // Updates last event time to extend time-based session
+    this.config.lastEventTime = Date.now();
+    const time = new Date().getTime();
+    const nativeContext = await this.nativeModule?.getApplicationContext();
+    const appVersion = nativeContext?.version || this.config.appVersion;
+    const platform = nativeContext?.platform || BROWSER_PLATFORM;
+    const osName = nativeContext?.os_name || this.uaResult.browser.name;
+    const osVersion = nativeContext?.os_version || this.uaResult.browser.version;
+    const deviceVendor = nativeContext?.device_manufacturer || this.uaResult.device.vendor;
+    const deviceModel = nativeContext?.device_model || this.uaResult.device.model || this.uaResult.os.name;
+    const language = nativeContext?.language || getLanguage();
+    const carrier = nativeContext?.carrier;
+
+    const event: Event = {
+      user_id: this.config.userId,
+      device_id: this.config.deviceId,
+      session_id: this.config.sessionId,
+      time,
+      ...(this.config.appVersion && { app_version: appVersion }),
+      ...(this.config.trackingOptions.platform && { platform: platform }),
+      ...(this.config.trackingOptions.osName && { os_name: osName }),
+      ...(this.config.trackingOptions.osVersion && { os_version: osVersion }),
+      ...(this.config.trackingOptions.deviceManufacturer && { device_manufacturer: deviceVendor }),
+      ...(this.config.trackingOptions.deviceModel && { device_model: deviceModel }),
+      ...(this.config.trackingOptions.language && { language: language }),
+      ...(this.config.trackingOptions.carrier && { carrier: carrier }),
+      ...(this.config.trackingOptions.ipAddress && { ip: IP_ADDRESS }),
+      insert_id: UUID(),
+      partner_id: this.config.partnerId,
+      plan: this.config.plan,
+      ...context,
+      event_id: this.eventId++,
+      library: this.library,
+    };
+    return event;
+  }
+
+  isSessionValid() {
+    const lastEventTime = this.config.lastEventTime || Date.now();
+    const timeSinceLastEvent = Date.now() - lastEventTime;
+    return timeSinceLastEvent < this.config.sessionTimeout;
+  }
+}

package/src/react-native-client.ts

@@ -0,0 +1,349 @@
+import { AmplitudeCore, Destination, Identify, Revenue, returnWrapper } from '@amplitude/analytics-core';
+import {
+  ReactNativeConfig,
+  Campaign,
+  EventOptions,
+  Identify as IIdentify,
+  Result,
+  Revenue as IRevenue,
+  TransportType,
+  ReactNativeOptions,
+  AdditionalReactNativeOptions,
+  AttributionReactNativeOptions,
+} from '@amplitude/analytics-types';
+import { convertProxyObjectToRealObject, isInstanceProxy } from './utils/snippet-helper';
+import { Context } from './plugins/context';
+import { useReactNativeConfig, createTransport, createDeviceId, createFlexibleStorage } from './config';
+import { parseOldCookies } from './cookie-migration';
+import { CampaignTracker } from './attribution/campaign-tracker';
+
+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(undefined, undefined, 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;
+    }
+
+    // Step 4: Install plugins
+    // Do not track any events before this
+    await this.add(new Context());
+    await this.add(new Destination());
+
+    // Step 5: Track attributions
+    await this.runAttributionStrategy(options?.attribution, isNewSession);
+  }
+
+  async runAttributionStrategy(attributionConfig?: AttributionReactNativeOptions, isNewSession = false) {
+    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;
+  }
+
+  getDeviceId() {
+    return this.config.deviceId;
+  }
+
+  setDeviceId(deviceId: string) {
+    this.config.deviceId = deviceId;
+  }
+
+  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;
+  }
+
+  setTransport(transport: TransportType) {
+    this.config.transportProvider = createTransport(transport);
+  }
+
+  identify(identify: IIdentify, eventOptions?: EventOptions): Promise<Result> {
+    if (isInstanceProxy(identify)) {
+      const queue = identify._q;
+      identify._q = [];
+      identify = convertProxyObjectToRealObject(new Identify(), queue);
+    }
+    return super.identify(identify, eventOptions);
+  }
+
+  groupIdentify(
+    groupType: string,
+    groupName: string | string[],
+    identify: IIdentify,
+    eventOptions?: EventOptions,
+  ): Promise<Result> {
+    if (isInstanceProxy(identify)) {
+      const queue = identify._q;
+      identify._q = [];
+      identify = convertProxyObjectToRealObject(new Identify(), queue);
+    }
+    return super.groupIdentify(groupType, groupName, identify, eventOptions);
+  }
+
+  revenue(revenue: IRevenue, eventOptions?: EventOptions) {
+    if (isInstanceProxy(revenue)) {
+      const queue = revenue._q;
+      revenue._q = [];
+      revenue = convertProxyObjectToRealObject(new Revenue(), queue);
+    }
+    return super.revenue(revenue, eventOptions);
+  }
+}
+
+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);
+
+/**
+ *  Sets the network transport type for events.
+ *
+ * ```typescript
+ * // Use Fetch API
+ * setTransport('fetch');
+ *
+ * // Use XMLHttpRequest API
+ * setTransport('xhr');
+ *
+ * // Use navigator.sendBeacon API
+ * setTransport('beacon');
+ * ```
+ */
+export const setTransport = client.setTransport.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,95 @@
+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> {
+    if (isNative()) {
+      return false;
+    }
+    /* istanbul ignore if */
+    if (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> {
+    const value = await this.getRaw(key);
+    if (!value) {
+      return undefined;
+    }
+    try {
+      // 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}=${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 {
+      //
+    }
+  }
+}