Web SDK

The Web SDK (@tolinku/web-sdk) provides event tracking, smart banners, in-app messages, referral management, and deferred deep link claiming for browser and Node.js environments.

Installation

npm

npm install @tolinku/web-sdk

yarn

yarn add @tolinku/web-sdk

pnpm

pnpm add @tolinku/web-sdk

Setup

import { Tolinku } from '@tolinku/web-sdk';

const tolinku = new Tolinku({
  apiKey: 'tolk_pub_your_key',
  baseUrl: 'https://your-app.tolinku.com' // optional
});

The baseUrl defaults to https://api.tolinku.com. Set it to your Appspace’s domain if you use a custom domain.

User identification

Set a user ID for analytics attribution and segment targeting:

tolinku.setUserId('user_123');

// Clear the user ID (e.g. on logout)
tolinku.setUserId(null);

Event tracking

Track custom events:

// Simple event
tolinku.track('custom.page_view');

// Event with properties
tolinku.track('custom.purchase', {
  campaign: 'spring-sale',
  source: 'email',
  user_id: 'user_123'
});

Events are batched automatically (10 events or every 5 seconds) and sent via navigator.sendBeacon on page unload to avoid losing data.

You can force an immediate flush:

await tolinku.flush();

Ecommerce tracking

Track purchases, cart activity, and product events via tolinku.ecommerce:

// Set user ID for attribution
tolinku.setUserId('user_123');

// Track a purchase
await tolinku.ecommerce.purchase({
  transaction_id: 'order_456',
  revenue: 49.99,
  currency: 'USD',
  items: [
    { item_id: 'sku_1', item_name: 'T-Shirt', price: 24.99, quantity: 2 }
  ]
});

// Track product views
await tolinku.ecommerce.viewItem({
  items: [{ item_id: 'sku_1', item_name: 'T-Shirt', price: 24.99 }]
});

// Track add to cart
await tolinku.ecommerce.addToCart({
  items: [{ item_id: 'sku_1', quantity: 1 }]
});

// Track checkout flow
await tolinku.ecommerce.beginCheckout({});
await tolinku.ecommerce.addPaymentInfo();

// Search and product interactions
await tolinku.ecommerce.search({ search_term: 'red shoes' });
await tolinku.ecommerce.rate({ item_id: 'sku_1', rating: 4.5, max_rating: 5 });

Ecommerce events are batched separately from custom events (10 events or 5-second timer) and sent to the ecommerce batch endpoint. The SDK automatically manages a cart ID across cart events and clears it after purchase.

Note

Ecommerce tracking requires a paid plan (Standard or above).

Smart banners

Display a smart app banner on your web page:

// Show the highest-priority active banner
await tolinku.showBanner();

// Filter by label
await tolinku.showBanner({ label: 'summer-promo' });

// Dismiss the current banner
tolinku.dismissBanner();

Tip

For simple website banners that do not require the full SDK, you can use the standalone banner.js script instead. See the Smart Banners user guide for details.

In-app messages

Display in-app messages:

// Show the highest-priority undismissed message
await tolinku.showMessage();

// Filter by trigger
await tolinku.showMessage({ trigger: 'on_open' });

// Dismiss the current message
tolinku.dismissMessage();

Messages are rendered as a DOM modal overlay.

Referrals

Access referral methods via tolinku.referrals:

// Create a referral code
const { referral_code, referral_url } = await tolinku.referrals.create({
  userId: 'user_123',
  userName: 'Jane Doe'
});

// Look up a referral
const info = await tolinku.referrals.get('ABC123');

// Link a referred user (status stays pending until reward milestone is reached)
await tolinku.referrals.complete({
  code: 'ABC123',
  referredUserId: 'user_456'
});

// Update milestone (completes the referral if it matches the reward milestone)
await tolinku.referrals.milestone({
  code: 'ABC123',
  milestone: 'first_purchase'
});

// Claim reward (after granting it in your system)
await tolinku.referrals.claimReward('ABC123');

// Get leaderboard
const { leaderboard } = await tolinku.referrals.leaderboard(10);

Tip

If you have ecommerce auto-completion enabled, you don’t need to call milestone() manually. Just track the purchase via tolinku.ecommerce.purchase() and the server will auto-complete the referral.

Deferred deep links

Claim deferred deep links after a user arrives from a deep link and installs your app:

// Token-based claiming (if you have a tolk_token from a referrer or URL parameter)
const link = await tolinku.deferred.claimByToken(token);
if (link) {
  // Navigate to link.deep_link_path
}

// Signal-based claiming (fingerprint matching)
const link = await tolinku.deferred.claimBySignals({
  appspaceId: 'your_appspace_id'
});

For token-based claiming, the token is the tolk_token value from the Play Store install referrer (Android) or a URL parameter. Signal-based claiming automatically collects timezone, language, and screen dimensions from the browser.

Cleanup

For single-page applications, clean up when unmounting:

tolinku.destroy();

This flushes any queued events, removes DOM elements (banners, messages), and cancels pending requests.