@amplitude/analytics-react-native 0.0.1-dev.7 → 0.1.0

package/src/cookie-migration/index.ts

@@ -0,0 +1,54 @@
+import { BrowserOptions, Storage, UserSession } from '@amplitude/analytics-types';
+import { getOldCookieName } from '../utils/cookie-name';
+import { LocalStorage } from '../storage/local-storage';
+import { CookieStorage } from '../storage/cookie';
+
+export const parseOldCookies = async (apiKey: string, options?: BrowserOptions): Promise<UserSession> => {
+  let storage: Storage<string> = new CookieStorage<string>();
+  if (!(await storage.isEnabled()) || options?.disableCookies) {
+    storage = new LocalStorage<string>();
+  }
+  if (!(await storage.isEnabled())) {
+    return {
+      optOut: false,
+    };
+  }
+
+  const oldCookieName = getOldCookieName(apiKey);
+  const cookies = await storage.getRaw(oldCookieName);
+
+  if (!cookies) {
+    return {
+      optOut: false,
+    };
+  }
+
+  await storage.remove(oldCookieName);
+  const [deviceId, userId, optOut, sessionId, lastEventTime] = cookies.split('.');
+  return {
+    deviceId,
+    userId: decode(userId),
+    sessionId: parseTime(sessionId),
+    lastEventTime: parseTime(lastEventTime),
+    optOut: Boolean(optOut),
+  };
+};
+
+export const parseTime = (num: string) => {
+  const integer = parseInt(num, 32);
+  if (isNaN(integer)) {
+    return undefined;
+  }
+  return integer;
+};
+
+export const decode = (value?: string): string | undefined => {
+  if (!atob || !escape || !value) {
+    return undefined;
+  }
+  try {
+    return decodeURIComponent(escape(atob(value)));
+  } catch {
+    return undefined;
+  }
+};

package/src/index.ts

@@ -0,0 +1,24 @@
+export {
+  add,
+  flush,
+  getDeviceId,
+  getSessionId,
+  getUserId,
+  groupIdentify,
+  identify,
+  init,
+  logEvent,
+  remove,
+  revenue,
+  setDeviceId,
+  setGroup,
+  setOptOut,
+  setSessionId,
+  setUserId,
+  track,
+} from './react-native-client';
+export { Revenue, Identify } from '@amplitude/analytics-core';
+// Hack - react-native apps have trouble with:
+// export * as Types from '@amplitude/analytics-types
+import * as Types from '@amplitude/analytics-types';
+export { Types };

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;
+  osName: string;
+  osVersion: string;
+  deviceBrand: string;
+  deviceManufacturer: string;
+  deviceModel: 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-react-native-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?.osName || this.uaResult.browser.name;
+    const osVersion = nativeContext?.osVersion || this.uaResult.browser.version;
+    const deviceVendor = nativeContext?.deviceManufacturer || this.uaResult.device.vendor;
+    const deviceModel = nativeContext?.deviceModel || 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/plugins/identity.ts

@@ -0,0 +1,21 @@
+import { BeforePlugin, PluginType, Event, Config } from '@amplitude/analytics-types';
+import { getAnalyticsConnector } from '../utils/analytics-connector';
+
+export class IdentityEventSender implements BeforePlugin {
+  name = 'identity';
+  type = PluginType.BEFORE as const;
+
+  identityStore = getAnalyticsConnector().identityStore;
+
+  async execute(context: Event): Promise<Event> {
+    const userProperties = context.user_properties as Record<string, any>;
+    if (userProperties) {
+      this.identityStore.editIdentity().updateUserProperties(userProperties).commit();
+    }
+    return context;
+  }
+
+  setup(_: Config): Promise<undefined> {
+    return Promise.resolve(undefined);
+  }
+}

package/src/react-native-client.ts

@@ -0,0 +1,332 @@
+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(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;
+    }
+
+    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: 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 });
+  }
+}