Skip to content
Developer docs
⌘ K
Dashboard ↗

Reference

@grizzlee/sdk/tracking

Use this entry point in a website or mobile app with a publishable key. It has no server API key.

Reads a referral from an absolute link, such as https://shop.example/join?ref=KARL7Q or myapp://open?.... Reads grizzlee_ref, grizzlee_program and grizzlee_channel from older links, then ref, program and channel. Returns null without a code, or when ref holds something that cannot be a partner code.

ts
declare const readReferralLink: (link: string) => ReferralLink | null;

INSTALL_CLAIM_PARAM

The query parameter that carries an install claim code in a Play Store referrer.

ts
declare const INSTALL_CLAIM_PARAM: "grizzlee_claim";

createPlayStoreUrl

Builds a Play Store link whose install referrer carries an install claim code or a referral. The Play Store hands the referrer to the app after install, with no matching on device or IP. extra adds more referrer pairs, such as utm_source.

ts
declare const createPlayStoreUrl: (options: { packageName: string; installClaim?: string | undefined; referral?: ReferralLink | undefined; extra?: Record<string, string> | undefined; }) => string;

isInstallClaimCode

True when the value looks like an install claim code, such as K7Q2-M9XD-4HPA.

ts
declare const isInstallClaimCode: (value: string) => boolean;

normalizeInstallClaimCode

An install claim code in canonical form: uppercase, without spaces or hyphens. Null when the value cannot be one. Codes are 12 characters of Crockford base32, which has no I, L, O or U.

ts
declare const normalizeInstallClaimCode: (value: string) => string | null;

readAppsFlyerReferral

Reads a referral from an AppsFlyer payload. Pass the result of onDeepLink or onInstallConversionData, or its data or deepLink. A JSON string, which Android can deliver, works too. Looks for grizzlee_ref, grizzlee_program and grizzlee_channel, or ref, program and channel, then a referral link in deep_link_value, then deep_link_sub1 (code), deep_link_sub2 (program) and deep_link_sub3 (channel). The program can be left out when the code is a partner code. Deferred deep links for new installs carry only deep_link_value and deep_link_sub1 to deep_link_sub10, so use those in OneLink. Change the sub keys with keys.

Returns null when the deep link was not found, for organic installs, and for conversion data whose is_first_launch is false, so a cached payload is not captured again on every launch.

ts
declare const readAppsFlyerReferral: (payload: unknown, options?: { keys?: Partial<AppsFlyerReferralKeys> | undefined; }) => ReferralLink | null;

readBranchReferral

Reads a referral from a Branch deep link payload. Pass the event from branch.subscribe ({ error, params, uri }) or its params. Looks for grizzlee_ref, grizzlee_program and grizzlee_channel, or ref, program and channel, in the link data first, then in the query of +non_branch_link, ~referring_link, +url, $canonical_url and $deeplink_path. Returns null when Branch reports an error or +clicked_branch_link is false.

ts
declare const readBranchReferral: (payload: unknown) => ReferralLink | null;

readInstallReferrer

Reads the install referrer string from the Play Install Referrer API, such as grizzlee_claim=K7Q2M9XD4HPA&utm_source=store. Returns the claim code when there is one, otherwise a referral from grizzlee_ref and grizzlee_program or from ref, otherwise null.

ts
declare const readInstallReferrer: (referrer: string | null | undefined) => InstallReferrer | null;

AppsFlyerReferralKeys

Where an AppsFlyer payload carries each referral field when the grizzlee_ keys are absent.

ts
type AppsFlyerReferralKeys = AppsFlyerReferralKeys;

InstallReferrer

What a Play Store install referrer carried: an install claim code, or a referral to capture.

ts
type InstallReferrer = ReferralLink | { installClaim: string; };

CaptureReferralResponse

Response of the public capture endpoint.

ts
type CaptureReferralResponse = CaptureReferralResponse;

InstallClaim

A single-use code that carries a web capture into a freshly installed app. The landing page puts it in the Play Store referrer or shows it to the visitor, and the app redeems it at first launch.

ts
type InstallClaim = InstallClaim;

PlacementResolution

ts
type PlacementResolution = PlacementResolution;

ProgramDisplay

What a partner or customer screen shows for a program, in every supported language. Missing copy falls back: publicName to the default language's public name and then the program name, headline to terms.text.headline, and the milestone label to "step" and "steps".

ts
type ProgramDisplay = ProgramDisplay;
ts
type ReferralLink = ReferralLink;

ReferralChannel

ts
type ReferralChannel = "link" | "qr" | "coupon" | "in_app";

computeIncentiveCents

Discount for one order in minor units, for your checkout to apply and report as incentiveAppliedCents. baseCents is the amount your checkout discounts. It returns 0 below minOrderCents. A percentage rounds half up and stops at maxDiscountCents. A fixed amount never exceeds baseCents. It does not check eligibility. Ask your backend for that.

ts
declare const computeIncentiveCents: (terms: IncentivePricingTerms, baseCents: number) => number;

IncentiveOffer

A program's friend incentive with the program currency. Public responses use this shape.

ts
type IncentiveOffer = ({ type: "percent"; rateBps: number; orders: number; newCustomersOnly: boolean; expiresAfterDays: number | null; returnOnFullRefund: boolean; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; orders: number; newCustomersOnly: boolean; expiresAfterDays: number | null; returnOnFullRefund: boolean; amountCents: number; minOrderCents?: number | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; }) & { currency: "CAD" | "USD" | "EUR" | "GBP"; };

IncentivePricingTerms

The pricing part of a friend incentive. IncentiveOffer and FriendIncentive both fit.

ts
type IncentivePricingTerms = { type: "percent"; rateBps: number; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; } | { type: "fixed"; amountCents: number; minOrderCents?: number | undefined; };

ReferralStorage

ts
type ReferralStorage = ReferralStorage;

ReferralReceipt

ts
type ReferralReceipt = ReferralReceipt;

MemoryReferralStorage

ts
class MemoryReferralStorage {
  getItem(key: string): string | null;
  setItem(key: string, value: string): void;
  removeItem(key: string): void;
}

GrizzleeTrackingClient

Public capture only. Your backend claims receipts and records payments.

ts
class GrizzleeTrackingClient {
  constructor(options: { baseUrl: string; publishableKey: string; storage?: ReferralStorage; fetch?: typeof fetch; });
  resolvePlacement(key: string): Promise<PlacementResolution>;
  capture(input: { programId?: string; referralCode: string; channel?: "link" | "qr" | "coupon" | "in_app"; installClaim?: boolean; destination?: string; }): Promise<CaptureReferralResponse>;
  redeemInstallClaim(code: string): Promise<CaptureReferralResponse>;
  captureInstallReferrer(referrer: string | null | undefined): Promise<CaptureReferralResponse | null>;
  captureFromUrl(link: string, channel?: "link" | "qr" | "in_app"): Promise<CaptureReferralResponse | null>;
  receipt(programId: string): Promise<ReferralReceipt | null>;
  forget(programId: string): Promise<void>;
  forgetAfterOrder(programId: string, usedReceipt: string): Promise<void>;
}