@tolinku/web-sdk

The official Tolinku SDK for the web. Add deep linking, analytics, referral tracking, deferred deep links, smart banners, and in-app messages to any website or web app.

What is Tolinku?

Tolinku is a deep linking platform for mobile and web apps. It handles Universal Links (iOS), App Links (Android), deferred deep linking, referral programs, analytics, and smart banners. Tolinku provides a complete toolkit for user acquisition, attribution, and engagement across platforms.

Get your API key at tolinku.com and check out the documentation to get started.

Installation

npm install @tolinku/web-sdk

Or with yarn:

yarn add @tolinku/web-sdk

Quick Start

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

const tolinku = new Tolinku({ apiKey: 'tolk_pub_your_api_key' });

// Identify a user
tolinku.setUserId('user_123');

// Track a custom event
await tolinku.track('purchase', { plan: 'growth' });

Features

Analytics

Track custom events with automatic batching (events are queued and sent in batches of 10, or every 5 seconds). On page unload, remaining events are delivered via navigator.sendBeacon for reliable delivery.

await tolinku.track('signup_completed', { source: 'landing_page' });

// Flush queued events immediately
await tolinku.flush();

Referrals

Create and manage referral programs with built-in leaderboards and reward tracking.

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

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

// Complete a referral (when a referred user converts)
await tolinku.referrals.complete({
  code: referral_code,
  referredUserId: 'user_456',
  referredUserName: 'Bob',
});

// Update milestone
await tolinku.referrals.milestone({
  code: referral_code,
  milestone: 'first_purchase',
});

// Claim reward
await tolinku.referrals.claimReward(referral_code);

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

Ecommerce

Track purchases, cart activity, and product events with built-in revenue analytics. Available on paid plans.

tolinku.setUserId('user_123');

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

// 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 }]
});

// Flush ecommerce events
await tolinku.ecommerce.flush();

The SDK supports 13 event types: viewItem, addToCart, removeFromCart, addToWishlist, viewCart, addPaymentInfo, beginCheckout, purchase, refund, search, share, rate, and spendCredits. Cart IDs are managed automatically via sessionStorage and cleared after purchase.

Deferred Deep Links

Recover deep link context for users who installed your app after clicking a link. Deferred deep linking lets you route users to specific content even when the app was not installed at the time of the click.

// Claim by referrer token (from Play Store referrer or clipboard)
const link = await tolinku.deferred.claimByToken('abc123');
if (link) {
  console.log(link.deep_link_path); // e.g. "/merchant/xyz"
}

// Claim by device signal matching
const link = await tolinku.deferred.claimBySignals({
  appspaceId: 'your_appspace_id',
});

In-App Messages

Display visually rich, server-configured messages as modal overlays. Create and manage messages from the Tolinku dashboard without shipping app updates.

// Show the highest-priority message matching a trigger
await tolinku.showMessage({ trigger: 'milestone' });

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

Messages support components including headings, text blocks, images, buttons, sections, spacers, and dividers. Impression tracking and suppression rules (max impressions, minimum interval, dismiss duration) are handled automatically.

Smart Banners

Display app install banners that link users to the App Store, Google Play, or a custom URL. Smart banners help convert web visitors into app users with a non-intrusive prompt.

// Show a smart banner
await tolinku.showBanner({ position: 'top' });

// Dismiss the banner
tolinku.dismissBanner();

Banners include an app icon, title, body text, and a call-to-action button. Dismissal state is tracked so banners do not reappear until the configured duration has passed.

Configuration Options

const tolinku = new Tolinku({
  apiKey: 'tolk_pub_your_api_key',     // Required. Your Tolinku publishable API key.
  baseUrl: 'https://api.tolinku.com', // Optional. API base URL.
});

// Set user identity at any time
tolinku.setUserId('user_123');

API Reference

Tolinku

| Method | Description | |--------|-------------| | new Tolinku(config) | Create a new SDK instance | | setUserId(userId) | Set or clear the current user ID | | track(eventType, properties?) | Track a custom event | | flush() | Flush queued analytics events | | showBanner(options?) | Display a smart banner | | dismissBanner() | Dismiss the smart banner | | showMessage(options?) | Show an in-app message | | dismissMessage() | Dismiss the in-app message | | destroy() | Clean up all resources |

tolinku.analytics

| Method | Description | |--------|-------------| | track(eventType, properties?) | Queue a custom event | | flush() | Send all queued events |

tolinku.referrals

| Method | Description | |--------|-------------| | create(options) | Create a new referral | | get(code) | Get referral details by code | | complete(options) | Mark a referral as converted | | milestone(options) | Update a referral milestone | | claimReward(code) | Claim a referral reward | | leaderboard(limit?) | Fetch the referral leaderboard |

tolinku.ecommerce

| Method | Description | |--------|-------------| | viewItem(params) | Track a product view | | addToCart(params) | Track item added to cart | | removeFromCart(params) | Track item removed from cart | | addToWishlist(params) | Track item added to wishlist | | viewCart() | Track cart view | | addPaymentInfo() | Track payment info entered | | beginCheckout(params?) | Track checkout started | | purchase(params) | Track a purchase | | refund(params) | Track a refund | | search(params) | Track a product search | | share(params) | Track a product share | | rate(params) | Track a product rating | | spendCredits(params) | Track loyalty credits spent | | flush() | Send all queued ecommerce events |

tolinku.deferred

| Method | Description | |--------|-------------| | claimByToken(token) | Claim a deferred link by token | | claimBySignals(options) | Claim a deferred link by device signals |

Documentation

Full documentation is available at tolinku.com/docs.

Community

• GitHub
• X (Twitter)
• Facebook
• Instagram

License

MIT