react-native-revnix 1.6.0 → 1.8.0

package/src/blocks/types.ts

@@ -135,13 +135,15 @@ export interface BlockStyle {
  *  one. Ignored outside a package card — a root block is always drawn. */
 export type BlockVisibility = "selected" | "unselected";
 
-export type BlockAction = "close";
+/** `close` dismisses the paywall; `next`/`back` move between onboarding
+ *  screens and only appear inside `screens`. */
+export type BlockAction = "close" | "next" | "back";
 
 export interface TextBlock {
   id: string;
   type: "text";
   text: string;
-  /** Tapping this block dismisses the paywall. See BlockAction. */
+  /** What tapping this block does. See BlockAction. */
   action?: BlockAction;
   style?: BlockStyle;
   /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -159,7 +161,7 @@ export interface ImageBlock {
   shape?: "rect" | "circle";
   fit?: "cover" | "contain";
   placeholder?: string;
-  /** Tapping this block dismisses the paywall. See BlockAction. */
+  /** What tapping this block does. See BlockAction. */
   action?: BlockAction;
   style?: BlockStyle;
   /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -206,8 +208,9 @@ export interface ButtonBlock {
   id: string;
   type: "button";
   label: string;
-  /** `close` turns this button into a dismiss ("Not now") instead of the
-   *  purchase CTA, which is what a button means by default. */
+  /** `close` turns this button into a dismiss ("Not now"), and `next`/`back`
+   *  into onboarding navigation, instead of the purchase CTA, which is what a
+   *  button means by default. */
   action?: BlockAction;
   style?: BlockStyle;
   /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -257,13 +260,58 @@ export interface SpacerBlock {
   visibility?: BlockVisibility;
 }
 
+/** Countdown text. `endsAt` is one deadline for everyone; `duration` counts
+ *  from the moment this paywall view opened. At zero it draws `expiredText`,
+ *  or nothing when that is absent. Tokens in `format`: {d} {hh} {mm} {ss}. */
+export interface TimerBlock {
+  id: string;
+  type: "timer";
+  endsAt?: string;
+  duration?: number;
+  format?: string;
+  expiredText?: string;
+  style?: BlockStyle;
+  selectedStyle?: BlockStyle;
+  visibility?: BlockVisibility;
+}
+
+/** A muted looping clip. React Native has no built-in player, so this SDK
+ *  draws `poster` in its place, sized like an image block. */
+export interface VideoBlock {
+  id: string;
+  type: "video";
+  url: string;
+  poster?: string;
+  fit?: "cover" | "contain";
+  style?: BlockStyle;
+  selectedStyle?: BlockStyle;
+  visibility?: BlockVisibility;
+}
+
+/** The free-trial switch: ON while package `onPackageIndex` is selected, and
+ *  tapping it selects the other one. Hidden when the offering lacks either
+ *  index. */
+export interface ToggleBlock {
+  id: string;
+  type: "toggle";
+  label: string;
+  onPackageIndex: number;
+  offPackageIndex: number;
+  style?: BlockStyle;
+  selectedStyle?: BlockStyle;
+  visibility?: BlockVisibility;
+}
+
 /** The one container block. `layout` picks how children are placed: column /
  *  row are flex lines, `stack` layers them (children position with
- *  style.inset or the edge offsets), and `grid` is an N-column grid. */
+ *  style.inset or the edge offsets), `grid` is an N-column grid, and
+ *  `carousel` pages through its children one swipe at a time. */
 export interface CardBlock {
   id: string;
   type: "card";
-  layout?: "column" | "row" | "stack" | "grid";
+  layout?: "column" | "row" | "stack" | "grid" | "carousel";
+  /** carousel only: seconds per page before it moves on by itself. */
+  autoAdvance?: number;
   /** Renders this container once per package in the attached offering. Its
    *  subtree reads the package through tag variables. */
   repeat?: "packages";
@@ -292,6 +340,9 @@ export type PaywallBlock =
   | LinksBlock
   | LineBlock
   | SpacerBlock
+  | TimerBlock
+  | VideoBlock
+  | ToggleBlock
   | CardBlock;
 
 /** The published document: screen palette plus the block tree. */
@@ -308,6 +359,10 @@ export interface PaywallBlockDoc {
   accentInk: string;
   fontFamily?: string;
   blocks: PaywallBlock[];
+  /** Onboarding: intro screens shown in order before `blocks`, which stays
+   *  the last (purchase) screen. They share the doc's palette, layout and
+   *  locale table. Absent or empty = `blocks` alone. */
+  screens?: PaywallBlock[][];
   /** REV-271: the language the blocks' own copy is written in. Absent = "en".
    *  Never a key in a stored doc's `locales` — the tree IS that language's
    *  version. A localized copy names the language it was localized to. */
@@ -345,8 +400,32 @@ export function hasCloseAction(blocks: PaywallBlock[]): boolean {
       : b.type === "card"
         ? b.repeat === undefined &&
           b.packageIndex === undefined &&
+          b.layout !== "carousel" &&
           hasCloseAction(b.children)
         : (b.type === "text" || b.type === "image" || b.type === "button") &&
           b.action === "close"
   );
 }
+
+export function onboardingScreen(
+  doc: PaywallBlockDoc,
+  index: number
+): { blocks: PaywallBlock[]; dots?: { count: number; active: number } } {
+  const intro = doc.screens?.[index];
+  if (intro === undefined) return { blocks: doc.blocks };
+  return {
+    blocks: intro,
+    dots: { count: doc.screens!.length + 1, active: index },
+  };
+}
+
+export function stepScreen(
+  doc: PaywallBlockDoc,
+  index: number,
+  action: BlockAction | undefined
+): number | undefined {
+  if (index >= (doc.screens?.length ?? 0)) return undefined;
+  if (action === "next") return index + 1;
+  if (action === "back" && index > 0) return index - 1;
+  return undefined;
+}

package/src/client.ts

@@ -45,6 +45,7 @@ import type {
   IdentifyResult,
   IdentifyStrategy,
   IdentityInfo,
+  IntegrityEvidence,
   LastDeepLink,
   MmpAttribution,
   PaywallInteraction,
@@ -67,9 +68,11 @@ const PENDING_PURCHASES_KEY = "revnix.pendingPurchases";
 const PLACEMENTS_CACHE_KEY = "revnix.placements";
 const LAST_ATTRIBUTION_KEY = "revnix.lastAttribution";
 const LAST_PUSH_TOKEN_KEY = "revnix.lastPushToken";
+const LAST_AD_ID_KEY = "revnix.lastAdId";
 const EVENT_QUEUE_KEY = "revnix.eventQueue";
 const PLACEMENTS_INVALIDATED_AT_KEY = "revnix.placementsInvalidatedAt";
 const DEFAULT_TIMEOUT_MS = 10_000;
+const INTEGRITY_TIMEOUT_MS = 10_000;
 const EVENT_QUEUE_CAP = 1000;
 const EVENT_BATCH_SIZE = 100;
 const EVENT_FLUSH_THRESHOLD = 20;
@@ -200,6 +203,21 @@ const jittered = (ms: number) => ms * (0.8 + Math.random() * 0.4);
 // half a minute; long enough that gating five screens costs one request.
 const DEFAULT_ENTITLEMENTS_TTL_MS = 30_000;
 
+const fitsWithin = (value: unknown, max: number): value is string =>
+  typeof value === "string" && value.length > 0 && value.length <= max;
+
+function wellFormedIntegrity(evidence: unknown): IntegrityEvidence | undefined {
+  if (typeof evidence !== "object" || evidence === null) return undefined;
+  const { platform, keyId, attestation, token } = evidence as Record<string, unknown>;
+  if (platform === "ios" && fitsWithin(keyId, 128) && fitsWithin(attestation, 16_384)) {
+    return { platform, keyId, attestation };
+  }
+  if (platform === "android" && fitsWithin(token, 16_384)) {
+    return { platform, token };
+  }
+  return undefined;
+}
+
 export class RevnixClient {
   private readonly apiKey: string;
   private readonly baseUrl: string;
@@ -244,6 +262,11 @@ export class RevnixClient {
   private readonly onImplicitPaywall?: RevnixConfig["onImplicitPaywall"];
   private readonly onDeferredDeepLink?: RevnixConfig["onDeferredDeepLink"];
   private readonly onAttribution?: RevnixConfig["onAttribution"];
+  private readonly deviceIntegrity?: RevnixConfig["deviceIntegrity"];
+  private integrityRequest: {
+    customerId: string;
+    body: Promise<{ integrity?: IntegrityEvidence }>;
+  } | null = null;
   private deferredDeepLinkClaimed = false;
   private landingUrl: string | null = null;
   private lastDeepLinkWrite: Promise<void> = Promise.resolve();
@@ -316,6 +339,7 @@ export class RevnixClient {
     this.onDiagnostic = config.onDiagnostic;
     this.onDeferredDeepLink = config.onDeferredDeepLink;
     this.onAttribution = config.onAttribution;
+    this.deviceIntegrity = config.deviceIntegrity;
     this.readYourWritesDelaysMs =
       config.readYourWritesDelaysMs ?? [250, 500, 1000, 2000];
     this.customerIdPromise = this.loadCustomerId(config.customerId);
@@ -324,6 +348,7 @@ export class RevnixClient {
     void this.retryPendingPurchases().catch((err) =>
       this.diag("retryPendingPurchases", err)
     );
+    if (config.advertisingId) this.reportAdvertisingId(config.advertisingId);
     const store = getStoreAdapter();
     if (store) {
       this.stopStoreObserver = store.observe((tx) =>
@@ -1247,6 +1272,7 @@ export class RevnixClient {
           ...(attribution.campaign ? { campaign: attribution.campaign } : {}),
           ...(attribution.adGroup ? { adGroup: attribution.adGroup } : {}),
           ...(attribution.creative ? { creative: attribution.creative } : {}),
+          ...(await this.integrityFor(customerId)),
         });
         await this.storage.setItem(LAST_ATTRIBUTION_KEY, payload);
       })
@@ -1283,6 +1309,23 @@ export class RevnixClient {
       .catch((err) => this.diag("setPushToken", err));
   }
 
+  private reportAdvertisingId(
+    source: NonNullable<RevnixConfig["advertisingId"]>
+  ): void {
+    void Promise.resolve()
+      .then(source)
+      .then(async (value) => {
+        const id = value || null;
+        const customerId = await this.customerIdPromise;
+        const payload = JSON.stringify({ customerId, id });
+        const last = await this.storage.getItem(LAST_AD_ID_KEY);
+        if (last === payload || (id === null && last === null)) return;
+        await this.setAttributes({ gps_adid: id });
+        await this.storage.setItem(LAST_AD_ID_KEY, payload);
+      })
+      .catch((err) => this.diag("advertisingId", err));
+  }
+
   /** REV-272: the two moments that happen ON a paywall, with the loop guard
    *  applied. `fromPaywallId` travels so the server can refuse to hand back
    *  the very paywall being dismissed — the backstop for a host that reports
@@ -1519,13 +1562,14 @@ export class RevnixClient {
     // one-launch phantoms. Same guard, same reason, as triggerImplicit.
     if (this.ephemeralAnonId) return;
     void this.customerIdPromise
-      .then((customerId) =>
+      .then(async (customerId) =>
         this.request<InstallResponse>("POST", "/v1/installs", {
           customerId,
           occurredAt: Date.now(),
           sdkVersion: SDK_VERSION,
           installReferrer: referrer.slice(0, 1024),
           ...this.installMetadata,
+          ...(await this.integrityFor(customerId)),
         })
       )
       .then((body) => {
@@ -1560,13 +1604,14 @@ export class RevnixClient {
     if (this.disposed || token.trim().length === 0) return Promise.resolve(undefined);
     if (this.ephemeralAnonId) return Promise.resolve(undefined);
     return this.customerIdPromise
-      .then((customerId) =>
+      .then(async (customerId) =>
         this.request<InstallResponse>("POST", "/v1/installs", {
           customerId,
           occurredAt: Date.now(),
           sdkVersion: SDK_VERSION,
           attributionToken: token.slice(0, 2048),
           ...this.installMetadata,
+          ...(await this.integrityFor(customerId)),
         })
       )
       .then((body) => {
@@ -1921,12 +1966,17 @@ export class RevnixClient {
   /** Fire-and-forget install report (REV-093). Never blocks startup and
    *  never throws — the backend absorbs retries idempotently per id. */
   private reportInstall(customerId: string): void {
-    void this.request<InstallResponse>("POST", "/v1/installs", {
-      customerId,
-      occurredAt: Date.now(),
-      sdkVersion: SDK_VERSION,
-      ...this.installMetadata,
-    })
+    const occurredAt = Date.now();
+    void this.integrityFor(customerId)
+      .then((integrity) =>
+        this.request<InstallResponse>("POST", "/v1/installs", {
+          customerId,
+          occurredAt,
+          sdkVersion: SDK_VERSION,
+          ...this.installMetadata,
+          ...integrity,
+        })
+      )
       .then((body) => {
         if (!this.ephemeralAnonId) this.refreshAttribution();
         return this.deliverDeferredDeepLink(body.deferredDeepLink);
@@ -1934,6 +1984,38 @@ export class RevnixClient {
       .catch((err) => this.diag("reportInstall", err));
   }
 
+  private integrityFor(
+    customerId: string
+  ): Promise<{ integrity?: IntegrityEvidence }> {
+    const source = this.deviceIntegrity;
+    if (!source) return Promise.resolve({});
+    if (this.integrityRequest?.customerId !== customerId) {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("device integrity timed out")),
+          INTEGRITY_TIMEOUT_MS
+        );
+      });
+      const body = Promise.race([
+        Promise.resolve().then(() => source(customerId)),
+        timeout,
+      ])
+        .then((evidence) => {
+          const integrity = wellFormedIntegrity(evidence);
+          if (!integrity) throw new Error("device integrity unavailable");
+          return { integrity };
+        })
+        .catch((err: unknown) => {
+          this.diag("deviceIntegrity", err);
+          return {};
+        })
+        .finally(() => clearTimeout(timer));
+      this.integrityRequest = { customerId, body };
+    }
+    return this.integrityRequest.body;
+  }
+
   /** REV-268: assemble and encode the device facts once. Runtime-detected
    *  facts first, the app's `device` over them, then the three the SDK owns.
    *  `installedAt` is the first launch this storage ever saw — written on

package/src/index.ts

@@ -44,6 +44,7 @@ export type {
   IdentifyStrategy,
   IdentityInfo,
   ImplicitResolution,
+  IntegrityEvidence,
   LastDeepLink,
   MmpAttribution,
   MmpProvider,

package/src/store/index.ts

@@ -5,11 +5,14 @@ import {
   type StoreAdapter,
   type StoreTransaction,
 } from "../store.js";
+import type { IntegrityEvidence, RevnixConfig } from "../types.js";
 
 interface NativeRevnixStore {
   purchase(productId: string, customerId: string): Promise<StoreTransaction | null>;
   restore(): Promise<StoreTransaction[]>;
   finish(transactionId: string): Promise<void>;
+  deviceIntegrity?(customerId: string): Promise<IntegrityEvidence | null>;
+  advertisingId?(): Promise<string | null>;
 }
 
 const native: NativeRevnixStore | undefined = NativeModules.RevnixStore;
@@ -41,4 +44,16 @@ export const RevnixStore: StoreAdapter = native
       observe: () => () => {},
     };
 
+/** Pass as `deviceIntegrity` in the Revnix config: App Attest on iOS, Play
+ *  Integrity on Android, via the RevnixStore native module. Resolves null
+ *  where the device or build cannot produce evidence. */
+export const nativeDeviceIntegrity: NonNullable<RevnixConfig["deviceIntegrity"]> = (
+  customerId
+) => native?.deviceIntegrity?.(customerId) ?? Promise.resolve(null);
+
+/** Pass as `advertisingId` in the Revnix config: the Google Advertising ID
+ *  on Android, via the RevnixStore native module. Resolves null on iOS. */
+export const nativeAdvertisingId: NonNullable<RevnixConfig["advertisingId"]> = () =>
+  native?.advertisingId?.() ?? Promise.resolve(null);
+
 if (native) setStoreAdapter(RevnixStore);

package/src/types.ts

@@ -139,8 +139,38 @@ export interface RevnixConfig {
    *  Never throws into your app: an exception from this handler is reported
    *  through `onDiagnostic` and swallowed. */
   onAttribution?: (attribution: RevnixAttribution) => void;
+  /** Opt-in device integrity evidence (Apple App Attest / Google Play
+   *  Integrity) attached to every install report and `setAttribution` call.
+   *  Pair it with the dashboard's "Require device integrity" setting, which
+   *  strips attribution from installs that arrive without evidence. In React
+   *  Native pass `nativeDeviceIntegrity` from "react-native-revnix/store";
+   *  it needs iOS 14+ with App Attest, or Google Play services on Android.
+   *  Simulators and emulators return nothing.
+   *
+   *  Called at most once per customer id and bounded to 10s. A rejection,
+   *  timeout, or missing/malformed result sends the request without
+   *  evidence and reports `op: "deviceIntegrity"` through `onDiagnostic`. */
+  deviceIntegrity?: (
+    customerId: string
+  ) => Promise<IntegrityEvidence | null | undefined>;
+  /** Google Advertising ID source, stored on the customer as `gps_adid` at
+   *  launch and resent only when it changes. In React Native pass
+   *  `nativeAdvertisingId` from "react-native-revnix/store"; it needs
+   *  `play-services-ads-identifier` and the `AD_ID` permission in the app and
+   *  answers null on iOS and on opt-out, and rejects when the id cannot be
+   *  read. A null answer deletes a previously stored `gps_adid`; a
+   *  rejection changes nothing and reports `op: "advertisingId"`. */
+  advertisingId?: () => Promise<string | null | undefined>;
 }
 
+/** Device integrity evidence for `POST /v1/installs` and `/v1/attribution`.
+ *  iOS: an App Attest key id and its attestation (standard base64) over
+ *  SHA-256 of the customer id. Android: a classic Play Integrity token whose
+ *  nonce is base64url (no padding) of SHA-256 of the customer id. */
+export type IntegrityEvidence =
+  | { platform: "ios"; keyId: string; attestation: string }
+  | { platform: "android"; token: string };
+
 /** AT11: the install-attribution verdict — GET
  *  /v1/customers/{id}/attribution. `installMatch: "unknown"` (no install
  *  recorded yet, a normal cold-start race) is never sent to hosts as such;