@zaynforce/web-sdk

Browser SDK for sending attributed campaign and revenue events to Zaynforce.

For the fastest website install, Zaynforce also supports a hosted browser loader:

<script
  async
  src="https://app.zaynforce.com/sdk/v1/zayn.min.js"
  data-key="zf_pk_..."
  data-endpoint="https://api.zaynforce.com"
></script>

Install

npm install @zaynforce/web-sdk

pnpm add @zaynforce/web-sdk

Usage

import { init, trackPageView, trackSignup, trackPurchase } from '@zaynforce/web-sdk';

init({
  endpoint: 'https://api.zaynforce.com',
  publishableKey: 'zf_pk_your_workspace_key'
});

await trackPageView();

await trackSignup({
  externalUserId: 'user-1',
  metadata: { plan: 'pro' }
});

await trackPurchase({
  externalUserId: 'user-1',
  amount: 4999,
  currency: 'USD'
});

The generic track(type, payload) helper is still available for custom event flows.

publishableKey is the code option for your workspace Site Key. It is recommended for all new browser integrations. Keyless init() is still accepted during the current transition window for older installs.

Attribution resolution

When the SDK needs attribution context, it resolves it in this order:

1. A fresh Visitor Token captured in the current landing flow
2. The Visitor Token already stored in the browser cookie
3. The Visitor Token stored in local browser storage
4. No attribution context

Tokens always expire from their signed issue time plus the SDK TTL window. If a stored token is stale or invalid, re-open the starter link and try again.

For multi-subdomain websites, the landing flow can persist the Visitor Token across subdomains by passing a cookie domain:

persistAttributionSession({
  token,
  cookieDomain: '.example.com'
});

If your product needs consent-aware persistence, pass consent: 'denied' to skip both cookie and localStorage writes until tracking is allowed.

If you want profit visibility without sending sensitive cost data in events, set a default campaign margin in Zaynforce and the dashboard will show estimated profit.

Mobile Event API

Mobile teams can use the same /events API contract from React Native, iOS, and Android manual client implementations:

• open the campaign link first so attribution context is captured
• send SIGNUP and PURCHASE events with the Link Code and Visitor Token plus the Site Key
• include amount, currency, and optional grossProfit, grossMarginPercent, or costOfGoodsSold

Verified browser trust

Website installs that include a Site Key can now be classified as:

• verified browser install: request origin or referrer matched an allowlisted workspace domain
• unverified browser install: Site Key was present, but request origin or referrer did not match the allowlist
• legacy browser install: browser traffic arrived without a Site Key

Quick Test remains a manual verification flow and does not count as verified browser trust on its own.

Publish

This package is intended to be published from this monorepo. See docs/sdk-npm-publishing.md for the npm org setup, token, and release workflow.