The official Tolinku SDK for React Native. Add deep linking, analytics, referral tracking, deferred deep links, and in-app messages to your React Native app. Works with both React Native CLI and Expo projects.
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.
npm install @tolinku/react-native-sdk @react-native-async-storage/async-storageOr with yarn:
yarn add @tolinku/react-native-sdk @react-native-async-storage/async-storage@react-native-async-storage/async-storage is a required peer dependency used for message impression tracking and dismissal state.
This SDK is compatible with Expo. No custom native modules are required.
npx expo install @tolinku/react-native-sdk @react-native-async-storage/async-storageMost features (analytics, referrals, in-app messages) work in Expo Go. However, deep linking (Universal Links and App Links) requires a development build or production build, since Expo Go cannot register custom domain associations. Use npx expo run:ios or eas build --profile development to create a dev build for testing deep links.
For bare React Native projects, install the packages above and run pod install for iOS:
cd ios && pod installimport { Tolinku } from '@tolinku/react-native-sdk';
// Initialize the SDK (typically at app startup)
Tolinku.init({ apiKey: 'tolk_pub_your_api_key' });
// Identify a user
Tolinku.setUserId('user_123');
// Track a custom event
await Tolinku.track('purchase', { plan: 'growth' });Track custom events with automatic batching. Events are queued and sent in batches of 10, or every 5 seconds.
await Tolinku.track('signup_completed', { source: 'landing_page' });
// Flush queued events immediately
await Tolinku.flush();Create and manage referral programs with 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
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);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 covering the full shopping journey. Cart IDs are managed automatically via AsyncStorage and cleared after purchase. Events auto-flush when the app enters the background.
Short links open your app but arrive as an opaque code, /s7k2p9q/4821.
Nothing in that URL says which route it is, and nothing on the device can work
it out, so an app parsing the path itself does nothing and the link appears to
fail with no error and no screen.
resolve asks Tolinku, which answers with the route, the token and the
canonical path. A readable URL comes back unchanged, so you can resolve
everything rather than guessing which kind you have. It never throws: a link it
cannot resolve is one to fall back to your own handling for.
import { Tolinku } from '@tolinku/react-native-sdk';
const link = await Tolinku.links.resolve(url);
if (link) {
// link.deep_link_path -> "/order/4821/receipt"
// link.token -> "4821"
// link.route.prefix -> "order/{token}/receipt"
route(link.deep_link_path);
}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. Timezone, language, screen size, pixel ratio and
// OS version are detected for you.
const link = await Tolinku.deferred.claimBySignals({
appspaceId: '64f0a1b2c3d4e5f60718',
});On Android the Play Install Referrer is the deterministic mechanism: a Tolinku link attaches a token to the store URL, Play keeps it through the install, and this SDK reads it back on first launch. It names the exact click, survives for days, and does not depend on the network the device was on. Device signals are the fallback, and the only option on iOS, where no equivalent exists.
Prefer claimDeferredLink() over choosing a mechanism yourself:
// Referrer first, device signals as the fallback.
const link = await Tolinku.deferred.claimDeferredLink({
appspaceId: '64f0a1b2c3d4e5f60718',
});
if (link) routeTo(link.deep_link_path);Call it once on first launch. Calling again is safe, but a claim is consumed the first time it succeeds, so a second call returns nothing.
The Android side is bundled with this package, so there is nothing else to install. Autolinking is per-platform, so an iOS-only app never builds it. In Expo Go the native module is absent and Android falls back to signal matching; a development build gets the referrer.
appspaceId is your Appspace ID, not your subdomain or slug. Copy it from the dashboard
under Integrate or Settings. It looks like 64f0a1b2c3d4e5f60718.
Display server-configured in-app messages using the <TolinkuMessages> component. Drop it anywhere in your React Native component tree to automatically fetch and render messages as a modal overlay. Messages are created and managed from the Tolinku dashboard without shipping app updates.
import { TolinkuMessages } from '@tolinku/react-native-sdk';
function App() {
return (
<>
<MainContent />
<TolinkuMessages
trigger="milestone"
triggerValue="first_purchase"
onButtonPress={(action, messageId) => {
console.log(`Action: ${action}, Message: ${messageId}`);
}}
onDismiss={(messageId) => {
console.log(`Dismissed: ${messageId}`);
}}
/>
</>
);
}The component automatically filters dismissed and suppressed messages, and shows the highest-priority match. It respects dismiss_days, max_impressions, and min_interval_hours settings from the server.
Props:
| Prop | Type | Description |
|---|---|---|
trigger |
string? |
Filter messages by trigger type |
triggerValue |
string? |
Match a specific trigger value |
onButtonPress |
(action, messageId) => void |
Called when a message button is pressed. Only for http and https actions; anything else is blocked before this runs |
onDismiss |
(messageId) => void |
Called when a message is dismissed |
Tolinku.init({
apiKey: 'tolk_pub_your_api_key', // Required. Your Tolinku publishable API key.
baseUrl: 'https://api.tolinku.com', // Optional. API base URL.
debug: false, // Optional. Enable debug logging.
timeout: 30000, // Optional. Request timeout in ms.
});
// Set user identity at any time
Tolinku.setUserId('user_123');
// Shut down the SDK
await Tolinku.destroy();| Method | Description |
|---|---|
init(config) |
Initialize the SDK (static) |
isConfigured() |
Check if the SDK is initialized (static) |
setUserId(userId) |
Set or clear the current user ID (static) |
getUserId() |
Get the current user ID (static) |
track(eventType, properties?) |
Track a custom event (static) |
flush() |
Flush queued analytics events (static) |
destroy() |
Shut down the SDK and release resources (static) |
| 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 |
| 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 |
| Method | Description |
|---|---|
claimByToken(token) |
Claim a deferred link by token |
claimBySignals(options) |
Claim a deferred link by device signals |
| Prop | Description |
|---|---|
trigger |
Filter messages by trigger type |
triggerValue |
Match a specific trigger value |
onButtonPress |
Callback for button presses, for http and https actions only |
onDismiss |
Callback for message dismissal |
Full documentation is available at tolinku.com/docs.
MIT