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

package/lib/typescript/utils/snippet-helper.d.ts

@@ -0,0 +1,16 @@
+import { InstanceProxy, QueueProxy } from '@amplitude/analytics-types';
+/**
+ * Applies the proxied functions on the proxied amplitude snippet to an instance of the real object.
+ * @ignore
+ */
+export declare const runQueuedFunctions: (instance: object, queue: QueueProxy) => void;
+/**
+ * Applies the proxied functions on the proxied object to an instance of the real object.
+ * Used to convert proxied Identify and Revenue objects.
+ */
+export declare const convertProxyObjectToRealObject: <T>(instance: T, queue: QueueProxy) => T;
+/**
+ * Check if the param is snippet proxy
+ */
+export declare const isInstanceProxy: (instance: unknown) => instance is InstanceProxy;
+//# sourceMappingURL=snippet-helper.d.ts.map

package/lib/typescript/utils/snippet-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippet-helper.d.ts","sourceRoot":"","sources":["../../../src/utils/snippet-helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,aAAa,EAAE,UAAU,EAAU,MAAM,4BAA4B,CAAC;AAEhG;;;GAGG;AACH,eAAO,MAAM,kBAAkB,aAAc,MAAM,4BAElD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,8BAA8B,0CAY1C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,aAAc,OAAO,8BAGhD,CAAC"}

package/lib/typescript/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.0.1-dev.0";
+//# sourceMappingURL=version.d.ts.map

package/lib/typescript/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@amplitude/analytics-react-native",
+  "version": "0.0.1-dev.0",
+  "description": "Official React Native SDK",
+  "keywords": [
+    "analytics",
+    "amplitude",
+    "react-native",
+    "ios",
+    "android"
+  ],
+  "author": "Amplitude Inc",
+  "homepage": "https://github.com/amplitude/Amplitude-TypeScript",
+  "license": "MIT",
+  "main": "lib/commonjs/index",
+  "module": "lib/module/index",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "src/index",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amplitude/Amplitude-TypeScript.git"
+  },
+  "scripts": {
+    "build": "yarn version-file && bob build",
+    "fix": "yarn fix:eslint & yarn fix:prettier",
+    "fix:eslint": "eslint '{src,test}/**/*.ts' --fix",
+    "fix:prettier": "prettier --write \"{src,test}/**/*.ts\"",
+    "lint": "yarn lint:eslint & yarn lint:prettier",
+    "lint:eslint": "eslint '{src,test}/**/*.ts'",
+    "lint:prettier": "prettier --check \"{src,test}/**/*.ts\"",
+    "test": "yarn test:web && yarn test:mobile",
+    "test:web": "jest --setupFiles './test/mock/setup-web.ts'",
+    "test:mobile": "jest --setupFiles './test/mock/setup-mobile.ts'",
+    "typecheck": "tsc -p ./tsconfig.json",
+    "version": "yarn build",
+    "version-file": "node -p \"'export const VERSION = \\'' + require('./package.json').version + '\\';'\" > src/version.ts",
+    "typescript": "tsc --noEmit",
+    "prepare": "yarn version-file && bob build",
+    "example": "yarn --cwd example",
+    "pods": "cd example && pod-install --quiet"
+  },
+  "source": "src/index",
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "amplitude-react-native.podspec",
+    "!lib/typescript/example",
+    "!android/build",
+    "!ios/build",
+    "!**/test"
+  ],
+  "bugs": {
+    "url": "https://github.com/amplitude/Amplitude-TypeScript/issues"
+  },
+  "dependencies": {
+    "@amplitude/analytics-connector": "1.4.4",
+    "@amplitude/analytics-core": "^0.5.0",
+    "@amplitude/analytics-types": "^0.4.0",
+    "@amplitude/ua-parser-js": "^0.7.31",
+    "tslib": "^2.3.1",
+    "@react-native-async-storage/async-storage": "^1.17.7"
+  },
+  "devDependencies": {
+    "@types/react": "^16.9.19",
+    "@types/react-native": "0.62.13",
+    "react": "16.13.1",
+    "react-native": "0.63.4",
+    "react-native-builder-bob": "^0.17.1"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  }
+}

package/src/attribution/campaign-parser.ts

@@ -0,0 +1,78 @@
+import { UTMCookie } from '../storage/utm-cookie';
+import { getQueryParams } from '../utils/query-params';
+import {
+  UTM_CAMPAIGN,
+  UTM_CONTENT,
+  UTM_MEDIUM,
+  UTM_SOURCE,
+  UTM_TERM,
+  UTMZ_SOURCE,
+  UTMZ_MEDIUM,
+  UTMZ_CAMPAIGN,
+  UTMZ_TERM,
+  UTMZ_CONTENT,
+  GCLID,
+  FBCLID,
+  BASE_CAMPAIGN,
+} from './constants';
+import {
+  Campaign,
+  CampaignParser as ICampaignParser,
+  ClickIdParameters,
+  ReferrerParameters,
+  UTMParameters,
+} from '@amplitude/analytics-types';
+
+export class CampaignParser implements ICampaignParser {
+  utmCookieStorage = new UTMCookie();
+
+  async parse(): Promise<Campaign> {
+    return {
+      ...BASE_CAMPAIGN,
+      ...(await this.getUtmParam()),
+      ...this.getReferrer(),
+      ...this.getClickIds(),
+    } as Campaign;
+  }
+
+  async getUtmParam(): Promise<UTMParameters> {
+    const params = getQueryParams();
+    const cookies = ((await this.utmCookieStorage.isEnabled()) && (await this.utmCookieStorage.get('__utmz'))) || {};
+
+    const utmSource = params[UTM_SOURCE] || cookies[UTMZ_SOURCE];
+    const utmMedium = params[UTM_MEDIUM] || cookies[UTMZ_MEDIUM];
+    const utmCampaign = params[UTM_CAMPAIGN] || cookies[UTMZ_CAMPAIGN];
+    const utmTerm = params[UTM_TERM] || cookies[UTMZ_TERM];
+    const utmContent = params[UTM_CONTENT] || cookies[UTMZ_CONTENT];
+
+    return {
+      utm_source: utmSource,
+      utm_medium: utmMedium,
+      utm_campaign: utmCampaign,
+      utm_term: utmTerm,
+      utm_content: utmContent,
+    };
+  }
+
+  getReferrer(): ReferrerParameters {
+    const data: ReferrerParameters = {
+      referrer: undefined,
+      referring_domain: undefined,
+    };
+    try {
+      data.referrer = document.referrer || undefined;
+      data.referring_domain = data.referrer?.split('/')[2] ?? undefined;
+    } catch {
+      // nothing to track
+    }
+    return data;
+  }
+
+  getClickIds(): ClickIdParameters {
+    const params = getQueryParams();
+    return {
+      [GCLID]: params[GCLID],
+      [FBCLID]: params[FBCLID],
+    };
+  }
+}

package/src/attribution/campaign-tracker.ts

@@ -0,0 +1,112 @@
+import { createIdentifyEvent, Identify } from '@amplitude/analytics-core';
+import {
+  Storage,
+  Campaign,
+  CampaignParser as ICampaignParser,
+  CampaignTracker as ICampaignTracker,
+  CampaignTrackFunction,
+  CampaignTrackerOptions,
+  BaseEvent,
+} from '@amplitude/analytics-types';
+import { getCookieName as getStorageKey } from '../utils/cookie-name';
+import { CampaignParser } from './campaign-parser';
+import { BASE_CAMPAIGN, EMPTY_VALUE, MKTG } from './constants';
+
+export class CampaignTracker implements ICampaignTracker {
+  storage: Storage<Campaign>;
+  storageKey: string;
+  parser: ICampaignParser;
+  track: CampaignTrackFunction;
+  onNewCampaign: (campaign: Campaign) => unknown;
+
+  disabled: boolean;
+  trackNewCampaigns: boolean;
+  trackPageViews: boolean;
+  excludeReferrers: string[];
+  initialEmptyValue: string;
+
+  constructor(apiKey: string, options: CampaignTrackerOptions) {
+    this.storage = options.storage;
+    this.storageKey = getStorageKey(apiKey, MKTG);
+    this.parser = new CampaignParser();
+    this.track = options.track;
+    this.onNewCampaign = options.onNewCampaign;
+
+    this.disabled = Boolean(options.disabled);
+    this.trackNewCampaigns = Boolean(options.trackNewCampaigns);
+    this.trackPageViews = options.trackPageViews === undefined || Boolean(options.trackPageViews);
+    this.excludeReferrers = options.excludeReferrers ?? [];
+    if (typeof location !== 'undefined') {
+      this.excludeReferrers.unshift(location.hostname);
+    }
+    this.initialEmptyValue = options.initialEmptyValue ?? EMPTY_VALUE;
+  }
+
+  isNewCampaign(currentCampaign: Campaign, previousCampaign: Campaign) {
+    const isReferrerExcluded = Boolean(
+      currentCampaign.referring_domain && this.excludeReferrers.includes(currentCampaign.referring_domain),
+    );
+    const hasNewUtm =
+      previousCampaign.utm_campaign !== currentCampaign.utm_campaign ||
+      previousCampaign.utm_source !== currentCampaign.utm_source ||
+      previousCampaign.utm_medium !== currentCampaign.utm_medium ||
+      previousCampaign.utm_term !== currentCampaign.utm_term ||
+      previousCampaign.utm_content !== currentCampaign.utm_content;
+    const hasNewReferrer = previousCampaign.referring_domain !== currentCampaign.referring_domain;
+
+    return !isReferrerExcluded && (hasNewUtm || hasNewReferrer);
+  }
+
+  async saveCampaignToStorage(campaign: Campaign): Promise<void> {
+    await this.storage.set(this.storageKey, campaign);
+  }
+
+  async getCampaignFromStorage(): Promise<Campaign> {
+    return (await this.storage.get(this.storageKey)) || { ...BASE_CAMPAIGN };
+  }
+
+  createCampaignEvent(campaign: Campaign) {
+    const campaignParameters: Campaign = {
+      // This object definition allows undefined keys to be iterated on
+      // in .reduce() to build indentify object
+      ...BASE_CAMPAIGN,
+      ...campaign,
+    };
+    const identifyEvent = Object.entries(campaignParameters).reduce((identify, [key, value]) => {
+      identify.setOnce(`initial_${key}`, value || this.initialEmptyValue);
+      if (value) {
+        return identify.set(key, value);
+      }
+      return identify.unset(key);
+    }, new Identify());
+
+    const pageViewEvent: BaseEvent = {
+      event_type: 'Page View',
+      event_properties: {
+        page_title: /* istanbul ignore next */ (typeof document !== 'undefined' && document.title) || '',
+        page_location: /* istanbul ignore next */ (typeof location !== 'undefined' && location.href) || '',
+        page_path: /* istanbul ignore next */ (typeof location !== 'undefined' && location.pathname) || '',
+      },
+    };
+    return {
+      ...createIdentifyEvent(identifyEvent),
+      ...(this.trackPageViews && pageViewEvent),
+    };
+  }
+
+  async send(isNewSession: boolean) {
+    if (this.disabled) {
+      return;
+    }
+    const currentCampaign = await this.parser.parse();
+    const previousCampaign = await this.getCampaignFromStorage();
+    if (!isNewSession) {
+      if (!this.trackNewCampaigns || !this.isNewCampaign(currentCampaign, previousCampaign)) {
+        return;
+      }
+      this.onNewCampaign(currentCampaign);
+    }
+    await this.track(this.createCampaignEvent(currentCampaign));
+    await this.saveCampaignToStorage(currentCampaign);
+  }
+}

package/src/attribution/constants.ts

@@ -0,0 +1,32 @@
+import { Campaign } from '@amplitude/analytics-types';
+
+export const UTM_SOURCE = 'utm_source';
+export const UTM_MEDIUM = 'utm_medium';
+export const UTM_CAMPAIGN = 'utm_campaign';
+export const UTM_TERM = 'utm_term';
+export const UTM_CONTENT = 'utm_content';
+
+export const UTMZ_SOURCE = 'utmcsr';
+export const UTMZ_MEDIUM = 'utmcmd';
+export const UTMZ_CAMPAIGN = 'utmccn';
+export const UTMZ_TERM = 'utmctr';
+export const UTMZ_CONTENT = 'utmcct';
+
+export const GCLID = 'gclid';
+export const FBCLID = 'fbclid';
+
+export const EMPTY_VALUE = 'EMPTY';
+
+export const BASE_CAMPAIGN: Campaign = {
+  utm_source: undefined,
+  utm_medium: undefined,
+  utm_campaign: undefined,
+  utm_term: undefined,
+  utm_content: undefined,
+  referrer: undefined,
+  referring_domain: undefined,
+  gclid: undefined,
+  fbclid: undefined,
+};
+
+export const MKTG = 'MKTG';

package/src/config.ts

@@ -0,0 +1,210 @@
+import {
+  Event,
+  ReactNativeOptions,
+  ReactNativeConfig as IReactNativeConfig,
+  Storage,
+  TrackingOptions,
+  TransportType,
+  UserSession,
+  SessionManager as ISessionManager,
+} from '@amplitude/analytics-types';
+import { Config, MemoryStorage, UUID } from '@amplitude/analytics-core';
+
+import { CookieStorage } from './storage/cookie';
+import { FetchTransport } from './transports/fetch';
+import { LocalStorage } from './storage/local-storage';
+import { getCookieName } from './utils/cookie-name';
+import { getQueryParams } from './utils/query-params';
+import { XHRTransport } from './transports/xhr';
+import { SendBeaconTransport } from './transports/send-beacon';
+import { SessionManager } from './session-manager';
+
+export const getDefaultConfig = () => {
+  const cookieStorage = new MemoryStorage<UserSession>();
+  return {
+    cookieExpiration: 365,
+    cookieSameSite: 'Lax',
+    cookieSecure: false,
+    cookieStorage,
+    disableCookies: false,
+    domain: '',
+    sessionManager: new SessionManager(cookieStorage, ''),
+    sessionTimeout: 30 * 60 * 1000,
+    storageProvider: new MemoryStorage<Event[]>(),
+    trackingOptions: {
+      city: true,
+      country: true,
+      carrier: true,
+      deviceManufacturer: true,
+      deviceModel: true,
+      dma: true,
+      ipAddress: true,
+      language: true,
+      osName: true,
+      osVersion: true,
+      platform: true,
+      region: true,
+      versionName: true,
+    },
+    transportProvider: new FetchTransport(),
+  };
+};
+
+export class ReactNativeConfig extends Config implements IReactNativeConfig {
+  appVersion?: string;
+  cookieExpiration: number;
+  cookieSameSite: string;
+  cookieSecure: boolean;
+  cookieStorage: Storage<UserSession>;
+  disableCookies: boolean;
+  domain: string;
+  partnerId?: string;
+  sessionTimeout: number;
+  trackingOptions: TrackingOptions;
+  sessionManager: ISessionManager;
+
+  constructor(apiKey: string, userId?: string, options?: ReactNativeOptions) {
+    const defaultConfig = getDefaultConfig();
+    super({
+      ...options,
+      apiKey,
+      storageProvider: options?.storageProvider ?? defaultConfig.storageProvider,
+      transportProvider: options?.transportProvider ?? defaultConfig.transportProvider,
+    });
+    this.cookieStorage = options?.cookieStorage ?? defaultConfig.cookieStorage;
+    this.sessionManager = options?.sessionManager ?? defaultConfig.sessionManager;
+    this.sessionTimeout = options?.sessionTimeout ?? defaultConfig.sessionTimeout;
+
+    this.appVersion = options?.appVersion;
+    this.cookieExpiration = options?.cookieExpiration ?? defaultConfig.cookieExpiration;
+    this.cookieSameSite = options?.cookieSameSite ?? defaultConfig.cookieSameSite;
+    this.cookieSecure = options?.cookieSecure ?? defaultConfig.cookieSecure;
+    this.deviceId = options?.deviceId;
+    this.disableCookies = options?.disableCookies ?? defaultConfig.disableCookies;
+    this.domain = options?.domain ?? defaultConfig.domain;
+    this.lastEventTime = this.lastEventTime ?? options?.lastEventTime;
+    this.optOut = Boolean(options?.optOut);
+    this.partnerId = options?.partnerId;
+    this.sessionId = options?.sessionId;
+    this.trackingOptions = options?.trackingOptions ?? defaultConfig.trackingOptions;
+    this.userId = userId;
+  }
+
+  get deviceId() {
+    return this.sessionManager.getDeviceId();
+  }
+
+  set deviceId(deviceId: string | undefined) {
+    this.sessionManager.setDeviceId(deviceId);
+  }
+
+  get userId() {
+    return this.sessionManager.getUserId();
+  }
+
+  set userId(userId: string | undefined) {
+    this.sessionManager.setUserId(userId);
+  }
+
+  get sessionId() {
+    return this.sessionManager.getSessionId();
+  }
+
+  set sessionId(sessionId: number | undefined) {
+    this.sessionManager.setSessionId(sessionId);
+  }
+
+  get optOut() {
+    return this.sessionManager.getOptOut();
+  }
+
+  set optOut(optOut: boolean) {
+    this.sessionManager?.setOptOut(Boolean(optOut));
+  }
+
+  get lastEventTime() {
+    return this.sessionManager.getLastEventTime();
+  }
+
+  set lastEventTime(lastEventTime: number | undefined) {
+    this.sessionManager.setLastEventTime(lastEventTime);
+  }
+}
+
+export const useReactNativeConfig = async (
+  apiKey: string,
+  userId?: string,
+  options?: ReactNativeOptions,
+): Promise<IReactNativeConfig> => {
+  const defaultConfig = getDefaultConfig();
+  const cookieStorage = await createCookieStorage(options);
+  const cookieName = getCookieName(apiKey);
+  const cookies = await cookieStorage.get(cookieName);
+  const queryParams = getQueryParams();
+  const sessionManager = await new SessionManager(cookieStorage, apiKey).load();
+
+  return new ReactNativeConfig(apiKey, userId ?? cookies?.userId, {
+    ...options,
+    cookieStorage,
+    sessionManager,
+    deviceId: createDeviceId(cookies?.deviceId, options?.deviceId, queryParams.deviceId),
+    optOut: options?.optOut ?? Boolean(cookies?.optOut),
+    sessionId: (await cookieStorage.get(cookieName))?.sessionId ?? options?.sessionId,
+    storageProvider: await createEventsStorage(options),
+    trackingOptions: { ...defaultConfig.trackingOptions, ...options?.trackingOptions },
+    transportProvider: options?.transportProvider ?? createTransport(options?.transport),
+  });
+};
+
+export const createCookieStorage = async (
+  overrides?: ReactNativeOptions,
+  baseConfig = getDefaultConfig(),
+): Promise<Storage<UserSession>> => {
+  const options = { ...baseConfig, ...overrides };
+  const cookieStorage = overrides?.cookieStorage;
+  if (!cookieStorage || !(await cookieStorage.isEnabled())) {
+    return createFlexibleStorage<UserSession>(options);
+  }
+  return cookieStorage;
+};
+
+export const createFlexibleStorage = async <T>(options: ReactNativeOptions): Promise<Storage<T>> => {
+  let storage: Storage<T> = new CookieStorage({
+    domain: options.domain,
+    expirationDays: options.cookieExpiration,
+    sameSite: options.cookieSameSite,
+    secure: options.cookieSecure,
+  });
+  if (options.disableCookies || !(await storage.isEnabled())) {
+    storage = new LocalStorage();
+    if (!(await storage.isEnabled())) {
+      storage = new MemoryStorage();
+    }
+  }
+  return storage;
+};
+
+export const createEventsStorage = async (overrides?: ReactNativeOptions): Promise<Storage<Event[]>> => {
+  let eventsStorage = overrides?.storageProvider;
+  if (!eventsStorage || !(await eventsStorage.isEnabled())) {
+    eventsStorage = new LocalStorage();
+    if (!(await eventsStorage.isEnabled())) {
+      eventsStorage = new MemoryStorage();
+    }
+  }
+  return eventsStorage;
+};
+
+export const createDeviceId = (idFromCookies?: string, idFromOptions?: string, idFromQueryParams?: string) => {
+  return idFromOptions || idFromQueryParams || idFromCookies || UUID();
+};
+
+export const createTransport = (transport?: TransportType) => {
+  if (transport === TransportType.XHR) {
+    return new XHRTransport();
+  }
+  if (transport === TransportType.SendBeacon) {
+    return new SendBeaconTransport();
+  }
+  return getDefaultConfig().transportProvider;
+};

package/src/constants.ts

@@ -0,0 +1,14 @@
+export const UTM_SOURCE = 'utm_source';
+export const UTM_MEDIUM = 'utm_medium';
+export const UTM_CAMPAIGN = 'utm_campaign';
+export const UTM_TERM = 'utm_term';
+export const UTM_CONTENT = 'utm_content';
+
+export const UTMZ_SOURCE = 'utmcsr';
+export const UTMZ_MEDIUM = 'utmcmd';
+export const UTMZ_CAMPAIGN = 'utmccn';
+export const UTMZ_TERM = 'utmctr';
+export const UTMZ_CONTENT = 'utmcct';
+
+export const GCLID = 'gclid';
+export const FBCLID = 'fbclid';

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,23 @@
+export {
+  add,
+  getDeviceId,
+  getSessionId,
+  getUserId,
+  groupIdentify,
+  identify,
+  init,
+  logEvent,
+  remove,
+  revenue,
+  setDeviceId,
+  setGroup,
+  setOptOut,
+  setSessionId,
+  setTransport,
+  setUserId,
+  track,
+} from './react-native-client';
+export { runQueuedFunctions } from './utils/snippet-helper';
+export { Revenue, Identify } from '@amplitude/analytics-core';
+import * as Types from '@amplitude/analytics-types';
+export { Types };