@thravic/react-native 0.1.0 → 0.2.0

package/README.md

@@ -83,6 +83,25 @@ Thravic.track('purchase', { amount: 49, currency: 'USD' });
 Thravic.identify('user-42');
 ```
 
+## A/B tests
+
+Create a test under Experiments in the dashboard (Pro plan), start it, then ask for the user's version where the screen changes:
+
+```tsx
+import { Thravic, useVariant } from '@thravic/react-native';
+
+function Paywall() {
+  const version = useVariant('new-paywall'); // undefined while loading
+  if (version === undefined) return null;
+  return version === 'b' ? <NewPaywall /> : <OldPaywall />;
+}
+
+// when the user reaches the test's goal
+Thravic.track('signup');
+```
+
+Outside a component, `await Thravic.variant('new-paywall')` gives the same answer. You get a version id from the dashboard, or `null` for the original: the user isn't in the test, the test isn't running, the user opted out, or the tests couldn't load within 3 seconds. A user always gets the same version, on the app and on your website. The first answer in each session records that the user saw the test, and the dashboard counts the goals they reach after it.
+
 ## Privacy
 
 ```ts

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { Environment, NavigationRefLike, ThravicOptions } from './types';
+import type { Environment, Experiment, NavigationRefLike, ThravicOptions } from './types';
 export declare const VISITOR_KEY = "_tf_vid";
 export declare const QUEUE_KEY = "_tf_queue";
 export declare const OPT_OUT_KEY = "_tf_optout";
@@ -7,8 +7,18 @@ export declare const DEFAULT_API_URL = "https://api.thravic.com";
 export declare const MAX_BATCH = 50;
 /** Queued events kept while offline; the oldest go first. */
 export declare const MAX_QUEUE = 1000;
+/** How long `variant` waits for the running tests before answering null. */
+export declare const TESTS_WAIT_MS = 3000;
 /** A v4-shaped id, like the web tracker's. Not cryptographic: ids only need to be unique. */
 export declare function generateId(): string;
+/** FNV-1a, 32-bit, as a number in [0, 1). The web tracker's hash, so both split alike. */
+export declare function unitHash(text: string): number;
+/**
+ * The version of `test` for `visitorId`, or null when they are outside its traffic
+ * share. Worked out from a hash, so the same user always gets the same version,
+ * exactly as the web tracker would give it.
+ */
+export declare function assignVariant(visitorId: string, test: Experiment): string | null;
 /**
  * The SDK. Screen views are sent as `pageview` events on `app://<bundleId>/<Screen>`
  * URLs, so the dashboard's pages, paths and funnels work for apps as they do for
@@ -36,6 +46,10 @@ export declare class ThravicClient {
     private persistScheduled;
     private timer;
     private unsubscribeAppState;
+    /** This session's running tests, loaded the first time `variant` is asked. */
+    private tests;
+    /** Tests whose `experiment_view` this session has already sent. */
+    private exposed;
     constructor(env: Environment);
     /** Start tracking. Call once, when the app starts; later calls are ignored. */
     init(trackingId: string, options?: ThravicOptions): Promise<void>;
@@ -45,6 +59,13 @@ export declare class ThravicClient {
     track(event: string, properties?: Record<string, unknown>): void;
     /** Link this device to your own user id. Sent as the web tracker sends it. */
     identify(userId: string, traits?: Record<string, unknown>): void;
+    /**
+     * The version of A/B test `key` to show this user: a version id from the
+     * dashboard, or null for the original (not in the test, the test is not
+     * running, tracking is off, or the tests could not be loaded in time).
+     * The first answer in a session records that the user saw the test.
+     */
+    variant(key: string): Promise<string | null>;
     /** Stop tracking this device, and drop anything not yet sent. Remembered across launches. */
     optOut(): void;
     /** Resume tracking after `optOut`. */
@@ -63,6 +84,8 @@ export declare class ThravicClient {
     private startSession;
     private background;
     private foreground;
+    /** The running tests, or none when they fail to load or take too long. */
+    private loadTests;
     private whenReady;
     private screenUrl;
     private enqueue;

package/dist/client.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ThravicClient = exports.MAX_QUEUE = exports.MAX_BATCH = exports.DEFAULT_API_URL = exports.OPT_OUT_KEY = exports.QUEUE_KEY = exports.VISITOR_KEY = void 0;
+exports.ThravicClient = exports.TESTS_WAIT_MS = exports.MAX_QUEUE = exports.MAX_BATCH = exports.DEFAULT_API_URL = exports.OPT_OUT_KEY = exports.QUEUE_KEY = exports.VISITOR_KEY = void 0;
 exports.generateId = generateId;
+exports.unitHash = unitHash;
+exports.assignVariant = assignVariant;
 exports.VISITOR_KEY = '_tf_vid';
 exports.QUEUE_KEY = '_tf_queue';
 exports.OPT_OUT_KEY = '_tf_optout';
@@ -14,6 +16,8 @@ exports.MAX_QUEUE = 1000;
 const FLUSH_AT = 10;
 const MAX_RETRY_DELAY_MS = 30000;
 const PERSIST_DELAY_MS = 1000;
+/** How long `variant` waits for the running tests before answering null. */
+exports.TESTS_WAIT_MS = 3000;
 const DEFAULTS = {
     apiUrl: exports.DEFAULT_API_URL,
     sessionTimeoutMinutes: 30,
@@ -27,6 +31,36 @@ function generateId() {
         return (c === 'x' ? r : (r & 3) | 8).toString(16);
     });
 }
+/** FNV-1a, 32-bit, as a number in [0, 1). The web tracker's hash, so both split alike. */
+function unitHash(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0) / 4294967296;
+}
+/**
+ * The version of `test` for `visitorId`, or null when they are outside its traffic
+ * share. Worked out from a hash, so the same user always gets the same version,
+ * exactly as the web tracker would give it.
+ */
+function assignVariant(visitorId, test) {
+    if (!test.variants.length)
+        return null;
+    if (unitHash(`${visitorId}:${test.id}:traffic`) >= test.traffic / 100)
+        return null;
+    const weights = test.variants.map((v) => Math.max(v.weight, 0));
+    const total = weights.reduce((sum, w) => sum + w, 0);
+    const pick = unitHash(`${visitorId}:${test.id}:variant`);
+    let edge = 0;
+    for (let i = 0; i < test.variants.length; i++) {
+        edge += total > 0 ? weights[i] / total : 1 / test.variants.length;
+        if (pick < edge)
+            return test.variants[i].id;
+    }
+    return test.variants[test.variants.length - 1].id;
+}
 /**
  * The SDK. Screen views are sent as `pageview` events on `app://<bundleId>/<Screen>`
  * URLs, so the dashboard's pages, paths and funnels work for apps as they do for
@@ -54,6 +88,10 @@ class ThravicClient {
         this.persistScheduled = false;
         this.timer = null;
         this.unsubscribeAppState = null;
+        /** This session's running tests, loaded the first time `variant` is asked. */
+        this.tests = null;
+        /** Tests whose `experiment_view` this session has already sent. */
+        this.exposed = new Set();
         this.env = env;
     }
     /** Start tracking. Call once, when the app starts; later calls are ignored. */
@@ -118,6 +156,36 @@ class ThravicClient {
             this.enqueue('custom', { ...traits, event: 'identify', userId: String(userId) });
         });
     }
+    /**
+     * The version of A/B test `key` to show this user: a version id from the
+     * dashboard, or null for the original (not in the test, the test is not
+     * running, tracking is off, or the tests could not be loaded in time).
+     * The first answer in a session records that the user saw the test.
+     */
+    variant(key) {
+        return new Promise((resolve) => {
+            if (!this.initialized) {
+                this.env.log('[Thravic] Call Thravic.init before asking for a variant.');
+                resolve(null);
+                return;
+            }
+            this.whenReady(() => {
+                if (this.optedOut) {
+                    resolve(null);
+                    return;
+                }
+                void this.loadTests().then((tests) => {
+                    const test = tests.find((t) => t.key === key);
+                    const id = test ? assignVariant(this.visitorId, test) : null;
+                    if (test && id && !this.exposed.has(test.id)) {
+                        this.exposed.add(test.id);
+                        this.enqueue('custom', { event: 'experiment_view', experiment: test.id, variant: id });
+                    }
+                    resolve(id);
+                });
+            });
+        });
+    }
     /** Stop tracking this device, and drop anything not yet sent. Remembered across launches. */
     optOut() {
         this.optedOut = true;
@@ -202,6 +270,9 @@ class ThravicClient {
         this.sessionId = generateId();
         this.sessionStart = this.env.now();
         this.backgroundAt = null;
+        // A new session picks up tests started or ended since the last one.
+        this.tests = null;
+        this.exposed.clear();
         this.enqueue('custom', { event: 'app_open' });
     }
     background() {
@@ -226,6 +297,31 @@ class ThravicClient {
         if (this.currentScreen)
             this.enqueue('pageview');
     }
+    // ── A/B tests ────────────────────────────────────────────────────────────
+    /** The running tests, or none when they fail to load or take too long. */
+    loadTests() {
+        if (!this.tests) {
+            this.tests = new Promise((resolve) => {
+                let done = false;
+                const settle = (list) => {
+                    if (done)
+                        return;
+                    done = true;
+                    resolve(parseTests(list));
+                };
+                this.env.setTimeout(() => settle([]), exports.TESTS_WAIT_MS);
+                this.env
+                    .fetch(`${this.options.apiUrl}/api/collect/${encodeURIComponent(this.trackingId)}/config`)
+                    .then((response) => (response.ok ? response.json() : null))
+                    .then((config) => settle(config?.experiments))
+                    .catch((err) => {
+                    this.debug('tests could not be loaded', err);
+                    settle([]);
+                });
+            });
+        }
+        return this.tests;
+    }
     // ── Queue ────────────────────────────────────────────────────────────────
     whenReady(call) {
         if (this.ready)
@@ -313,6 +409,15 @@ function parseQueue(raw) {
         return [];
     }
 }
+function parseTests(list) {
+    if (!Array.isArray(list))
+        return [];
+    return list.filter((t) => !!t &&
+        typeof t.id === 'string' &&
+        typeof t.key === 'string' &&
+        typeof t.traffic === 'number' &&
+        Array.isArray(t.variants));
+}
 function stripUndefined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined && v !== null && v !== ''));
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ThravicClient } from './client';
-export { ThravicClient } from './client';
-export type { CollectEvent, DeviceInfo, Environment, NavigationRefLike, Storage, ThravicOptions, } from './types';
+export { ThravicClient, assignVariant } from './client';
+export type { CollectEvent, DeviceInfo, Environment, Experiment, NavigationRefLike, Storage, ThravicOptions, } from './types';
 /**
  * Thravic for React Native.
  *
@@ -10,7 +10,19 @@ export type { CollectEvent, DeviceInfo, Environment, NavigationRefLike, Storage,
  * Thravic.init('TF-1A2B3C4D', { appVersion: '1.4.0', bundleId: 'com.acme.shop' });
  * Thravic.trackNavigation(navigationRef);     // screen views, automatically
  * Thravic.track('purchase', { amount: 49 });  // your own events
+ * const version = await Thravic.variant('new-paywall');  // A/B tests
  * ```
  */
 export declare const Thravic: ThravicClient;
+/**
+ * The version of A/B test `key` to show, for use in a component: `undefined`
+ * while it loads, then a version id or null for the original.
+ *
+ * ```tsx
+ * const version = useVariant('new-paywall');
+ * if (version === undefined) return null;
+ * return version === 'b' ? <NewPaywall /> : <Paywall />;
+ * ```
+ */
+export declare function useVariant(key: string): string | null | undefined;
 export default Thravic;

package/dist/index.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Thravic = exports.ThravicClient = void 0;
+exports.Thravic = exports.assignVariant = exports.ThravicClient = void 0;
+exports.useVariant = useVariant;
+const react_1 = require("react");
 const client_1 = require("./client");
 const react_native_1 = require("./react-native");
 var client_2 = require("./client");
 Object.defineProperty(exports, "ThravicClient", { enumerable: true, get: function () { return client_2.ThravicClient; } });
+Object.defineProperty(exports, "assignVariant", { enumerable: true, get: function () { return client_2.assignVariant; } });
 /**
  * Thravic for React Native.
  *
@@ -14,7 +17,33 @@ Object.defineProperty(exports, "ThravicClient", { enumerable: true, get: functio
  * Thravic.init('TF-1A2B3C4D', { appVersion: '1.4.0', bundleId: 'com.acme.shop' });
  * Thravic.trackNavigation(navigationRef);     // screen views, automatically
  * Thravic.track('purchase', { amount: 49 });  // your own events
+ * const version = await Thravic.variant('new-paywall');  // A/B tests
  * ```
  */
 exports.Thravic = new client_1.ThravicClient(react_native_1.reactNativeEnvironment);
+/**
+ * The version of A/B test `key` to show, for use in a component: `undefined`
+ * while it loads, then a version id or null for the original.
+ *
+ * ```tsx
+ * const version = useVariant('new-paywall');
+ * if (version === undefined) return null;
+ * return version === 'b' ? <NewPaywall /> : <Paywall />;
+ * ```
+ */
+function useVariant(key) {
+    const [version, setVersion] = (0, react_1.useState)(undefined);
+    (0, react_1.useEffect)(() => {
+        let live = true;
+        setVersion(undefined);
+        void exports.Thravic.variant(key).then((id) => {
+            if (live)
+                setVersion(id);
+        });
+        return () => {
+            live = false;
+        };
+    }, [key]);
+    return version;
+}
 exports.default = exports.Thravic;

package/dist/types.d.ts

@@ -33,6 +33,18 @@ export interface CollectEvent {
     utmCampaign?: string;
     data?: Record<string, unknown>;
 }
+/** A running A/B test, as `GET /api/collect/{trackingId}/config` lists it. */
+export interface Experiment {
+    id: string;
+    /** What the app asks for: `Thravic.variant(key)`. */
+    key: string;
+    /** Share of users in the test, 0–100. */
+    traffic: number;
+    variants: Array<{
+        id: string;
+        weight: number;
+    }>;
+}
 /** What the device reports about itself. */
 export interface DeviceInfo {
     os: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thravic/react-native",
-  "version": "0.1.0",
-  "description": "Thravic analytics for React Native and Expo apps: screens, sessions and custom events.",
+  "version": "0.2.0",
+  "description": "Thravic analytics for React Native and Expo apps: screens, sessions, custom events and A/B tests.",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -29,10 +29,12 @@
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": ">=1.17.0",
+    "react": ">=17.0.0",
     "react-native": ">=0.70.0"
   },
   "devDependencies": {
     "@react-native-async-storage/async-storage": "^2.1.0",
+    "@types/react": "^18.3.31",
     "react-native": "^0.76.0",
     "typescript": "^5.6.0",
     "vitest": "^4.0.18"

package/src/client.ts

@@ -1,6 +1,7 @@
 import type {
   CollectEvent,
   Environment,
+  Experiment,
   NavigationRefLike,
   ThravicOptions,
 } from './types';
@@ -18,6 +19,8 @@ export const MAX_QUEUE = 1000;
 const FLUSH_AT = 10;
 const MAX_RETRY_DELAY_MS = 30_000;
 const PERSIST_DELAY_MS = 1_000;
+/** How long `variant` waits for the running tests before answering null. */
+export const TESTS_WAIT_MS = 3_000;
 
 const DEFAULTS = {
   apiUrl: DEFAULT_API_URL,
@@ -36,6 +39,35 @@ export function generateId(): string {
   });
 }
 
+/** FNV-1a, 32-bit, as a number in [0, 1). The web tracker's hash, so both split alike. */
+export function unitHash(text: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0) / 4294967296;
+}
+
+/**
+ * The version of `test` for `visitorId`, or null when they are outside its traffic
+ * share. Worked out from a hash, so the same user always gets the same version,
+ * exactly as the web tracker would give it.
+ */
+export function assignVariant(visitorId: string, test: Experiment): string | null {
+  if (!test.variants.length) return null;
+  if (unitHash(`${visitorId}:${test.id}:traffic`) >= test.traffic / 100) return null;
+  const weights = test.variants.map((v) => Math.max(v.weight, 0));
+  const total = weights.reduce((sum, w) => sum + w, 0);
+  const pick = unitHash(`${visitorId}:${test.id}:variant`);
+  let edge = 0;
+  for (let i = 0; i < test.variants.length; i++) {
+    edge += total > 0 ? weights[i] / total : 1 / test.variants.length;
+    if (pick < edge) return test.variants[i].id;
+  }
+  return test.variants[test.variants.length - 1].id;
+}
+
 /**
  * The SDK. Screen views are sent as `pageview` events on `app://<bundleId>/<Screen>`
  * URLs, so the dashboard's pages, paths and funnels work for apps as they do for
@@ -66,6 +98,11 @@ export class ThravicClient {
   private timer: unknown = null;
   private unsubscribeAppState: (() => void) | null = null;
 
+  /** This session's running tests, loaded the first time `variant` is asked. */
+  private tests: Promise<Experiment[]> | null = null;
+  /** Tests whose `experiment_view` this session has already sent. */
+  private exposed = new Set<string>();
+
   constructor(env: Environment) {
     this.env = env;
   }
@@ -139,6 +176,37 @@ export class ThravicClient {
     });
   }
 
+  /**
+   * The version of A/B test `key` to show this user: a version id from the
+   * dashboard, or null for the original (not in the test, the test is not
+   * running, tracking is off, or the tests could not be loaded in time).
+   * The first answer in a session records that the user saw the test.
+   */
+  variant(key: string): Promise<string | null> {
+    return new Promise((resolve) => {
+      if (!this.initialized) {
+        this.env.log('[Thravic] Call Thravic.init before asking for a variant.');
+        resolve(null);
+        return;
+      }
+      this.whenReady(() => {
+        if (this.optedOut) {
+          resolve(null);
+          return;
+        }
+        void this.loadTests().then((tests) => {
+          const test = tests.find((t) => t.key === key);
+          const id = test ? assignVariant(this.visitorId, test) : null;
+          if (test && id && !this.exposed.has(test.id)) {
+            this.exposed.add(test.id);
+            this.enqueue('custom', { event: 'experiment_view', experiment: test.id, variant: id });
+          }
+          resolve(id);
+        });
+      });
+    });
+  }
+
   /** Stop tracking this device, and drop anything not yet sent. Remembered across launches. */
   optOut(): void {
     this.optedOut = true;
@@ -226,6 +294,9 @@ export class ThravicClient {
     this.sessionId = generateId();
     this.sessionStart = this.env.now();
     this.backgroundAt = null;
+    // A new session picks up tests started or ended since the last one.
+    this.tests = null;
+    this.exposed.clear();
     this.enqueue('custom', { event: 'app_open' });
   }
 
@@ -250,6 +321,32 @@ export class ThravicClient {
     if (this.currentScreen) this.enqueue('pageview');
   }
 
+  // ── A/B tests ────────────────────────────────────────────────────────────
+
+  /** The running tests, or none when they fail to load or take too long. */
+  private loadTests(): Promise<Experiment[]> {
+    if (!this.tests) {
+      this.tests = new Promise((resolve) => {
+        let done = false;
+        const settle = (list: unknown) => {
+          if (done) return;
+          done = true;
+          resolve(parseTests(list));
+        };
+        this.env.setTimeout(() => settle([]), TESTS_WAIT_MS);
+        this.env
+          .fetch(`${this.options.apiUrl}/api/collect/${encodeURIComponent(this.trackingId)}/config`)
+          .then((response) => (response.ok ? response.json() : null))
+          .then((config) => settle(config?.experiments))
+          .catch((err) => {
+            this.debug('tests could not be loaded', err);
+            settle([]);
+          });
+      });
+    }
+    return this.tests;
+  }
+
   // ── Queue ────────────────────────────────────────────────────────────────
 
   private whenReady(call: () => void): void {
@@ -333,6 +430,18 @@ function parseQueue(raw: string | null): CollectEvent[] {
   }
 }
 
+function parseTests(list: unknown): Experiment[] {
+  if (!Array.isArray(list)) return [];
+  return list.filter(
+    (t): t is Experiment =>
+      !!t &&
+      typeof t.id === 'string' &&
+      typeof t.key === 'string' &&
+      typeof t.traffic === 'number' &&
+      Array.isArray(t.variants),
+  );
+}
+
 function stripUndefined<T extends object>(value: T): Partial<T> {
   return Object.fromEntries(
     Object.entries(value).filter(([, v]) => v !== undefined && v !== null && v !== ''),

package/src/index.ts

@@ -1,11 +1,14 @@
+import { useEffect, useState } from 'react';
+
 import { ThravicClient } from './client';
 import { reactNativeEnvironment } from './react-native';
 
-export { ThravicClient } from './client';
+export { ThravicClient, assignVariant } from './client';
 export type {
   CollectEvent,
   DeviceInfo,
   Environment,
+  Experiment,
   NavigationRefLike,
   Storage,
   ThravicOptions,
@@ -20,8 +23,34 @@ export type {
  * Thravic.init('TF-1A2B3C4D', { appVersion: '1.4.0', bundleId: 'com.acme.shop' });
  * Thravic.trackNavigation(navigationRef);     // screen views, automatically
  * Thravic.track('purchase', { amount: 49 });  // your own events
+ * const version = await Thravic.variant('new-paywall');  // A/B tests
  * ```
  */
 export const Thravic = new ThravicClient(reactNativeEnvironment);
 
+/**
+ * The version of A/B test `key` to show, for use in a component: `undefined`
+ * while it loads, then a version id or null for the original.
+ *
+ * ```tsx
+ * const version = useVariant('new-paywall');
+ * if (version === undefined) return null;
+ * return version === 'b' ? <NewPaywall /> : <Paywall />;
+ * ```
+ */
+export function useVariant(key: string): string | null | undefined {
+  const [version, setVersion] = useState<string | null | undefined>(undefined);
+  useEffect(() => {
+    let live = true;
+    setVersion(undefined);
+    void Thravic.variant(key).then((id) => {
+      if (live) setVersion(id);
+    });
+    return () => {
+      live = false;
+    };
+  }, [key]);
+  return version;
+}
+
 export default Thravic;

package/src/types.ts

@@ -35,6 +35,16 @@ export interface CollectEvent {
   data?: Record<string, unknown>;
 }
 
+/** A running A/B test, as `GET /api/collect/{trackingId}/config` lists it. */
+export interface Experiment {
+  id: string;
+  /** What the app asks for: `Thravic.variant(key)`. */
+  key: string;
+  /** Share of users in the test, 0–100. */
+  traffic: number;
+  variants: Array<{ id: string; weight: number }>;
+}
+
 /** What the device reports about itself. */
 export interface DeviceInfo {
   os: string;