react-native-nitro-amplitude 0.1.0

package/src/analytics/config.ts

@@ -0,0 +1,373 @@
+import {
+  Config,
+  MemoryStorage,
+  UUID,
+  ReactNativeConfig as IReactNativeConfig,
+  ReactNativeTrackingOptions,
+  Event,
+  ReactNativeOptions,
+  Storage,
+  UserSession,
+  CookieStorage,
+  getCookieName,
+  getQueryParams,
+  FetchTransport,
+} from "@amplitude/analytics-core";
+
+import { LocalStorage } from "./storage/local-storage";
+import RemnantDataMigration from "./migration/remnant-data-migration";
+import { NitroAnalyticsStorage } from "../native/storage";
+import { nitroTransport } from "./nitro-transport";
+
+export const getDefaultConfig = () => {
+  const cookieStorage = new MemoryStorage<UserSession>();
+  const trackingOptions: Required<ReactNativeTrackingOptions> = {
+    adid: true,
+    carrier: true,
+    deviceManufacturer: true,
+    deviceModel: true,
+    ipAddress: true,
+    language: true,
+    osName: true,
+    osVersion: true,
+    platform: true,
+    appSetId: true,
+    idfv: true,
+    country: false, // NOTE: tracking country information would disable server-side IP address lookup to fill other information like region, city, dma, etc.
+  };
+  return {
+    cookieExpiration: 365,
+    cookieSameSite: "Lax",
+    cookieSecure: false,
+    cookieStorage,
+    cookieUpgrade: true,
+    disableCookies: true,
+    domain: "",
+    sessionTimeout: 5 * 60 * 1000,
+    storageProvider: new NitroAnalyticsStorage<Event[]>("analytics-events"),
+    trackingSessionEvents: false,
+    trackingOptions,
+    transportProvider: nitroTransport,
+  };
+};
+
+export class ReactNativeConfig extends Config implements IReactNativeConfig {
+  appVersion?: string;
+  cookieExpiration: number;
+  cookieSameSite: string;
+  cookieSecure: boolean;
+  cookieStorage: Storage<UserSession>;
+  cookieUpgrade: boolean;
+  disableCookies: boolean;
+  domain: string;
+  partnerId?: string;
+  sessionTimeout: number;
+  trackingSessionEvents: boolean;
+  trackingOptions: ReactNativeTrackingOptions;
+
+  // NOTE: These protected properties cache user session values in the configured session storage
+  protected _deviceId?: string;
+  protected _lastEventId?: number;
+  protected _lastEventTime?: number;
+  protected _optOut = false;
+  protected _sessionId?: number;
+  protected _userId?: string;
+
+  constructor(apiKey: string, options?: ReactNativeOptions) {
+    const defaultConfig = getDefaultConfig();
+    super({
+      flushIntervalMillis: 1000,
+      flushMaxRetries: 5,
+      flushQueueSize: 30,
+      transportProvider: defaultConfig.transportProvider,
+      ...options,
+      apiKey,
+    });
+
+    // NOTE: Define `cookieStorage` first to persist user session
+    // user session properties expect `cookieStorage` to be defined
+    this.cookieStorage = options?.cookieStorage ?? defaultConfig.cookieStorage;
+    this.deviceId = options?.deviceId;
+    this.lastEventTime = options?.lastEventTime;
+    this.optOut = Boolean(options?.optOut);
+    this.sessionId = options?.sessionId;
+    this.userId = options?.userId;
+
+    this.appVersion = options?.appVersion;
+    this.cookieExpiration =
+      options?.cookieExpiration ?? defaultConfig.cookieExpiration;
+    this.cookieSameSite =
+      options?.cookieSameSite ?? defaultConfig.cookieSameSite;
+    this.cookieSecure = options?.cookieSecure ?? defaultConfig.cookieSecure;
+    this.cookieUpgrade = options?.cookieUpgrade ?? defaultConfig.cookieUpgrade;
+    this.disableCookies =
+      options?.disableCookies ?? defaultConfig.disableCookies;
+    this.domain = options?.domain ?? defaultConfig.domain;
+    this.partnerId = options?.partnerId;
+    this.sessionTimeout =
+      options?.sessionTimeout ?? defaultConfig.sessionTimeout;
+    this.trackingOptions =
+      options?.trackingOptions ?? defaultConfig.trackingOptions;
+    this.trackingSessionEvents =
+      options?.trackingSessionEvents ?? defaultConfig.trackingSessionEvents;
+  }
+
+  get deviceId() {
+    return this._deviceId;
+  }
+
+  set deviceId(deviceId: string | undefined) {
+    if (this._deviceId !== deviceId) {
+      this._deviceId = deviceId;
+      this.updateStorage();
+    }
+  }
+
+  get userId() {
+    return this._userId;
+  }
+
+  set userId(userId: string | undefined) {
+    if (this._userId !== userId) {
+      this._userId = userId;
+      this.updateStorage();
+    }
+  }
+
+  get sessionId() {
+    return this._sessionId;
+  }
+
+  set sessionId(sessionId: number | undefined) {
+    if (this._sessionId !== sessionId) {
+      this._sessionId = sessionId;
+      this.updateStorage();
+    }
+  }
+
+  get optOut() {
+    return this._optOut;
+  }
+
+  set optOut(optOut: boolean) {
+    if (this._optOut !== optOut) {
+      this._optOut = optOut;
+      this.updateStorage();
+    }
+  }
+
+  get lastEventTime() {
+    return this._lastEventTime;
+  }
+
+  set lastEventTime(lastEventTime: number | undefined) {
+    if (this._lastEventTime !== lastEventTime) {
+      this._lastEventTime = lastEventTime;
+      this.updateStorage();
+    }
+  }
+
+  get lastEventId() {
+    return this._lastEventId;
+  }
+
+  set lastEventId(lastEventId: number | undefined) {
+    if (this._lastEventId !== lastEventId) {
+      this._lastEventId = lastEventId;
+      this.updateStorage();
+    }
+  }
+
+  private updateStorage() {
+    const cache = {
+      deviceId: this._deviceId,
+      userId: this._userId,
+      sessionId: this._sessionId,
+      optOut: this._optOut,
+      lastEventTime: this._lastEventTime,
+      lastEventId: this._lastEventId,
+    };
+    try {
+      void this.cookieStorage
+        ?.set(getCookieName(this.apiKey), cache)
+        .catch((error) => {
+          this.loggerProvider?.error(
+            `Failed to persist user session: ${String(error)}`,
+          );
+        });
+    } catch (error) {
+      this.loggerProvider?.error(
+        `Failed to persist user session: ${String(error)}`,
+      );
+    }
+  }
+}
+
+export const useReactNativeConfig = async (
+  apiKey: string,
+  options?: ReactNativeOptions,
+): Promise<IReactNativeConfig> => {
+  const defaultConfig = getDefaultConfig();
+
+  // create cookie storage
+  const disableCookies =
+    options?.disableCookies ?? defaultConfig.disableCookies;
+  const domain = disableCookies
+    ? ""
+    : (options?.domain ?? (await getTopLevelDomain()));
+  const cookieStorage = await createCookieStorage<UserSession>({
+    ...options,
+    disableCookies,
+    domain,
+  });
+  const previousCookies = await cookieStorage.get(getCookieName(apiKey));
+  const queryParams = getQueryParams();
+
+  // reconcile user session
+  let deviceId =
+    options?.deviceId ?? queryParams.deviceId ?? previousCookies?.deviceId;
+  let lastEventTime = options?.lastEventTime ?? previousCookies?.lastEventTime;
+  const optOut = options?.optOut ?? Boolean(previousCookies?.optOut);
+  let sessionId = options?.sessionId ?? previousCookies?.sessionId;
+  let userId = options?.userId ?? previousCookies?.userId;
+  let lastEventId = previousCookies?.lastEventId;
+
+  const storageProvider =
+    options?.storageProvider ?? (await createEventsStorage(options));
+
+  if (options?.migrateLegacyData !== false) {
+    const legacySessionData = await new RemnantDataMigration(
+      apiKey,
+      options?.instanceName,
+      storageProvider,
+      previousCookies?.lastEventTime === undefined,
+      options?.loggerProvider,
+    ).execute();
+    deviceId = deviceId ?? legacySessionData.deviceId;
+    userId = userId ?? legacySessionData.userId;
+    sessionId = sessionId ?? legacySessionData.sessionId;
+    lastEventTime = lastEventTime ?? legacySessionData.lastEventTime;
+    lastEventId = lastEventId ?? legacySessionData.lastEventId;
+  }
+
+  const config = new ReactNativeConfig(apiKey, {
+    ...options,
+    cookieStorage,
+    deviceId: deviceId ?? UUID(),
+    domain,
+    lastEventTime,
+    optOut,
+    sessionId,
+    storageProvider,
+    trackingOptions: {
+      ...defaultConfig.trackingOptions,
+      ...options?.trackingOptions,
+    },
+    transportProvider: options?.transportProvider ?? new FetchTransport(),
+    userId,
+  });
+
+  config.lastEventId = lastEventId;
+
+  config.loggerProvider?.log(
+    `Init: storage=${cookieStorage.constructor.name} restoredSessionId = ${
+      previousCookies?.sessionId ?? "undefined"
+    }, optionsSessionId = ${options?.sessionId ?? "undefined"}`,
+  );
+
+  return config;
+};
+
+export const createCookieStorage = async <T>(
+  overrides?: ReactNativeOptions,
+  baseConfig = getDefaultConfig(),
+): Promise<Storage<T>> => {
+  const options = { ...baseConfig, ...overrides };
+  const cookieStorage = overrides?.cookieStorage as Storage<T>;
+  if (!cookieStorage || !(await cookieStorage.isEnabled())) {
+    return createFlexibleStorage<T>(options);
+  }
+  return cookieStorage;
+};
+
+const createFlexibleStorage = async <T>(
+  options: ReactNativeOptions,
+): Promise<Storage<T>> => {
+  let storage: Storage<T>;
+  if (options.disableCookies) {
+    storage = new LocalStorage();
+    if (!(await storage.isEnabled())) {
+      storage = new MemoryStorage();
+    }
+    return storage;
+  }
+
+  storage = new CookieStorage({
+    domain: options.domain,
+    expirationDays: options.cookieExpiration,
+    sameSite: options.cookieSameSite,
+    secure: options.cookieSecure,
+  });
+  if (!(await storage.isEnabled())) {
+    storage = new LocalStorage();
+    if (!(await storage.isEnabled())) {
+      storage = new MemoryStorage();
+    }
+  }
+  return storage;
+};
+
+export const createEventsStorage = async (
+  overrides?: ReactNativeOptions,
+): Promise<Storage<Event[]> | undefined> => {
+  const hasStorageProviderProperty =
+    overrides &&
+    Object.prototype.hasOwnProperty.call(overrides, "storageProvider");
+  // If storageProperty is explicitly undefined like `{ storageProperty: undefined }`
+  // then storageProvider is undefined
+  // If storageProvider is implicitly undefined like `{ }`
+  // then storageProvider uses the built-in memory storage
+  // Otherwise storageProvider is overriden
+  if (!hasStorageProviderProperty || overrides.storageProvider) {
+    for (const storage of [
+      overrides?.storageProvider,
+      new LocalStorage<Event[]>(),
+    ]) {
+      if (storage && (await storage.isEnabled())) {
+        return storage;
+      }
+    }
+  }
+  return undefined;
+};
+
+export const getTopLevelDomain = async (url?: string) => {
+  if (
+    !(await new CookieStorage<number>().isEnabled()) ||
+    (!url && (typeof location === "undefined" || !location.hostname))
+  ) {
+    return "";
+  }
+
+  const host = url ?? location.hostname;
+  const parts = host.split(".");
+  const levels = [];
+  const storageKey = "AMP_TLDTEST";
+
+  for (let i = parts.length - 2; i >= 0; --i) {
+    levels.push(parts.slice(i).join("."));
+  }
+  for (let i = 0; i < levels.length; i++) {
+    const domain = levels[i];
+    const options = { domain: "." + domain };
+    const storage = new CookieStorage<number>(options);
+    await storage.set(storageKey, 1);
+    const value = await storage.get(storageKey);
+    if (value) {
+      await storage.remove(storageKey);
+      return "." + domain;
+    }
+  }
+
+  return "";
+};

package/src/analytics/cookie-migration/index.ts

@@ -0,0 +1,69 @@
+import {
+  UserSession,
+  ReactNativeOptions,
+  getOldCookieName,
+} from "@amplitude/analytics-core";
+import {
+  createCookieStorage,
+  getDefaultConfig,
+  getTopLevelDomain,
+} from "../config";
+
+export const parseOldCookies = async (
+  apiKey: string,
+  options?: ReactNativeOptions,
+): Promise<UserSession> => {
+  const disableCookies =
+    options?.disableCookies ?? getDefaultConfig().disableCookies;
+  const storage = await createCookieStorage<string>({
+    ...options,
+    disableCookies,
+    domain: disableCookies
+      ? ""
+      : (options?.domain ?? (await getTopLevelDomain())),
+  });
+  const oldCookieName = getOldCookieName(apiKey);
+  const cookies = await storage.getRaw(oldCookieName);
+
+  if (!cookies) {
+    return {
+      optOut: false,
+    };
+  }
+
+  if (options?.cookieUpgrade ?? getDefaultConfig().cookieUpgrade) {
+    await storage.remove(oldCookieName);
+  }
+  const [deviceId, userId, optOut, sessionId, lastEventTime] =
+    cookies.split(".");
+  return {
+    deviceId,
+    userId: decode(userId ?? ""),
+    sessionId: parseTime(sessionId),
+    lastEventTime: parseTime(lastEventTime),
+    optOut: parseOptOut(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 (typeof atob !== "function" || typeof escape !== "function" || !value) {
+    return undefined;
+  }
+  try {
+    return decodeURIComponent(escape(atob(value)));
+  } catch {
+    return undefined;
+  }
+};
+
+export const parseOptOut = (value?: string): boolean => {
+  return value === "1" || value === "true";
+};

package/src/analytics/index.ts

@@ -0,0 +1,36 @@
+import client from "./react-native-client";
+
+// Export types to maintain backward compatibility with `analytics-types`.
+// In the next major version, only export customer-facing types to reduce the public API surface.
+import * as Types from "./types";
+export { createInstance } from "./react-native-client";
+export const {
+  add,
+  flush,
+  getDeviceId,
+  getSessionId,
+  getUserId,
+  groupIdentify,
+  identify,
+  init,
+  logEvent,
+  remove,
+  reset,
+  revenue,
+  setDeviceId,
+  setGroup,
+  setOptOut,
+  setSessionId,
+  setUserId,
+  shutdown,
+  track,
+  extendSession,
+} = client;
+
+export { Revenue, Identify } from "@amplitude/analytics-core";
+export {
+  InMemoryStorage,
+  LocalStorage,
+  MemoryStorage,
+} from "./storage/local-storage";
+export { Types };

package/src/analytics/migration/remnant-data-migration.ts

@@ -0,0 +1,206 @@
+import {
+  Event,
+  ILogger,
+  STORAGE_PREFIX,
+  Storage,
+  UserSession,
+} from "@amplitude/analytics-core";
+import {
+  getLegacyEvents,
+  getLegacySessionData,
+  removeLegacyEvent,
+} from "../../native/context";
+
+type LegacyEventKind = "event" | "identify" | "interceptedIdentify";
+
+export default class RemnantDataMigration {
+  eventsStorageKey: string;
+
+  constructor(
+    private readonly apiKey: string,
+    private readonly instanceName: string | undefined,
+    private readonly storage: Storage<Event[]> | undefined,
+    private readonly firstRunSinceUpgrade: boolean,
+    private readonly logger: ILogger | undefined,
+  ) {
+    this.eventsStorageKey = `${STORAGE_PREFIX}_${this.apiKey.substring(0, 10)}`;
+  }
+
+  async execute(): Promise<Omit<UserSession, "optOut">> {
+    if (this.firstRunSinceUpgrade) {
+      await this.moveIdentifies();
+      await this.moveInterceptedIdentifies();
+    }
+    await this.moveEvents();
+
+    return this.callNativeFunction(() =>
+      Promise.resolve(getLegacySessionData(this.instanceName ?? "")),
+    ).then((sessionData) => sessionData ?? {});
+  }
+
+  private async moveEvents() {
+    await this.moveLegacyEvents("event");
+  }
+
+  private async moveIdentifies() {
+    await this.moveLegacyEvents("identify");
+  }
+
+  private async moveInterceptedIdentifies() {
+    await this.moveLegacyEvents("interceptedIdentify");
+  }
+
+  private async callNativeFunction<T>(
+    action: () => Promise<T>,
+  ): Promise<T | undefined> {
+    try {
+      return await action();
+    } catch (e) {
+      this.logger?.error(`can't call native function: ${String(e)}`);
+      return undefined;
+    }
+  }
+
+  private callNativeAction(action: () => void) {
+    try {
+      action();
+    } catch (e) {
+      this.logger?.error(`can't call native function: ${String(e)}`);
+    }
+  }
+
+  private async callStorageFunction<T>(
+    action: () => Promise<T>,
+  ): Promise<{ value: T } | undefined> {
+    try {
+      return { value: await action() };
+    } catch (e) {
+      this.logger?.error(`can't call storage function: ${String(e)}`);
+      return undefined;
+    }
+  }
+
+  private async moveLegacyEvents(eventKind: LegacyEventKind) {
+    const legacyJsonEvents = await this.callNativeFunction(() =>
+      Promise.resolve(getLegacyEvents(this.instanceName ?? "", eventKind)),
+    );
+    if (!this.storage || !legacyJsonEvents || legacyJsonEvents.length === 0) {
+      return;
+    }
+
+    const existingEvents = await this.callStorageFunction<Event[] | undefined>(
+      async () => {
+        return this.storage?.get(this.eventsStorageKey);
+      },
+    );
+    if (!existingEvents) {
+      return;
+    }
+    const events: Event[] = existingEvents.value ?? [];
+    const eventIds: number[] = [];
+
+    legacyJsonEvents.forEach((jsonEvent) => {
+      const event = this.convertLegacyEvent(jsonEvent);
+      if (event) {
+        events.push(event);
+        if (event.event_id !== undefined) {
+          eventIds.push(event.event_id);
+        }
+      }
+    });
+
+    const writeSucceeded = await this.callStorageFunction(async () => {
+      await this.storage?.set(this.eventsStorageKey, events);
+      return true;
+    });
+    if (!writeSucceeded?.value) {
+      return;
+    }
+    eventIds.forEach((eventId) =>
+      this.callNativeAction(() =>
+        removeLegacyEvent(this.instanceName ?? "", eventKind, eventId),
+      ),
+    );
+  }
+
+  private convertLegacyEvent(legacyJsonEvent: string): Event | null {
+    try {
+      const event = JSON.parse(legacyJsonEvent) as Event;
+
+      const { library, timestamp, uuid, api_properties } = event as any;
+      if (library !== undefined) {
+        event.library = `${library.name}/${library.version}`;
+      }
+      if (timestamp !== undefined) {
+        event.time = timestamp;
+      }
+      if (uuid !== undefined) {
+        event.insert_id = uuid;
+      }
+
+      if (api_properties) {
+        const {
+          androidADID,
+          android_app_set_id,
+          ios_idfa,
+          ios_idfv,
+          productId,
+          quantity,
+          price,
+          location,
+        } = api_properties;
+        if (androidADID !== undefined) {
+          event.adid = androidADID;
+        }
+        if (android_app_set_id !== undefined) {
+          event.android_app_set_id = android_app_set_id;
+        }
+        if (ios_idfa !== undefined) {
+          event.idfa = ios_idfa;
+        }
+        if (ios_idfv !== undefined) {
+          event.idfv = ios_idfv;
+        }
+        if (productId !== undefined) {
+          event.productId = productId;
+        }
+        if (quantity !== undefined) {
+          event.quantity = quantity;
+        }
+        if (price !== undefined) {
+          event.price = price;
+        }
+        if (location !== undefined) {
+          const { lat, lng } = location;
+          event.location_lat = lat;
+          event.location_lng = lng;
+        }
+      }
+
+      const {
+        $productId: productId,
+        $quantity: quantity,
+        $price: price,
+        $revenueType: revenueType,
+      } = event as any;
+      if (productId !== undefined) {
+        event.productId = productId;
+      }
+      if (quantity !== undefined) {
+        event.quantity = quantity;
+      }
+      if (price !== undefined) {
+        event.price = price;
+      }
+      if (revenueType !== undefined) {
+        event.revenueType = revenueType;
+      }
+
+      return event;
+    } catch {
+      // skip invalid events
+      return null;
+    }
+  }
+  // eslint-enable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+}

package/src/analytics/nitro-transport.ts

@@ -0,0 +1,35 @@
+import { BaseTransport } from "@amplitude/analytics-core";
+import type { Payload, Response, Transport } from "@amplitude/analytics-core";
+import { nitroHttpClient } from "../native/http";
+
+export class NitroTransport extends BaseTransport implements Transport {
+  private readonly customHeaders: Record<string, string>;
+
+  constructor(customHeaders: Record<string, string> = {}) {
+    super();
+    this.customHeaders = customHeaders;
+  }
+
+  async send(serverUrl: string, payload: Payload): Promise<Response | null> {
+    const response = await nitroHttpClient.request(
+      serverUrl,
+      "POST",
+      {
+        "Content-Type": "application/json",
+        Accept: "*/*",
+        ...this.customHeaders,
+      },
+      JSON.stringify(payload),
+      30000,
+    );
+    try {
+      return this.buildResponse(
+        JSON.parse(response.body) as Record<string, unknown>,
+      );
+    } catch {
+      return this.buildResponse({ code: response.status });
+    }
+  }
+}
+
+export const nitroTransport = new NitroTransport();