React Native SDK

The React Native SDK (@tolinku/react-native-sdk) provides event tracking, deferred deep linking, referrals, and in-app messages for React Native 0.72+.

Installation

npm install @tolinku/react-native-sdk

You also need the peer dependency for dismiss/impression state persistence:

npm install @react-native-async-storage/async-storage

If using Expo:

npx expo install @react-native-async-storage/async-storage

Setup

Initialize the SDK early in your app:

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

// In App.tsx or index.js
Tolinku.init({
  apiKey: 'tolk_pub_your_key',
  // baseUrl: 'https://your-app.tolinku.com', // optional
  // debug: true,  // optional
  // timeout: 30000 // optional, ms
});

User identification

Tolinku.setUserId('user_123');

// Get current user ID
const userId = Tolinku.getUserId();

// Clear on logout
Tolinku.setUserId(null);

Event tracking

// Simple event
await Tolinku.track('custom.screen_view');

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

// Force flush
await Tolinku.flush();

Events are batched (10 events or 5-second timer) and auto-flushed when the app enters the background via React Native’s AppState listener.

Ecommerce tracking

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

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 and cart events
await Tolinku.ecommerce.viewItem({ items: [{ item_id: 'sku_1' }] });
await Tolinku.ecommerce.addToCart({ items: [{ item_id: 'sku_1' }] });
await Tolinku.ecommerce.beginCheckout({});

// Search and ratings
await Tolinku.ecommerce.search({ search_term: 'shoes' });
await Tolinku.ecommerce.rate({ item_id: 'sku_1', rating: 4.5 });

// Force flush ecommerce events
await Tolinku.ecommerce.flush();

Ecommerce events are batched (10 events or 5-second timer) and auto-flushed when the app enters the background. The SDK manages cart IDs automatically via AsyncStorage, clearing them after purchase.

Deep link handling

Use React Native’s Linking API to handle incoming deep links, then pass tokens to the deferred module:

import { Linking } from 'react-native';

// Handle links when app is already running
Linking.addEventListener('url', ({ url }) => {
  const parsed = new URL(url);
  const path = parsed.pathname; // e.g. "/merchant/abc123"
  // Navigate to the deep link destination
});

// Handle the initial URL (app launched from a link)
const initialUrl = await Linking.getInitialURL();
if (initialUrl) {
  // Parse and navigate
}

Deferred deep linking

Claim the original link destination after the user installs your app.

Token-based claiming (Android)

On Android, Tolinku appends a tolk_token parameter to the Play Store referrer string. After install, use the react-native-install-referrer library or a native module to read the install referrer, then extract the token:

import { getInstallReferrer } from 'react-native-install-referrer';

const referrer = await getInstallReferrer();
// referrer is e.g. "tolk_token=abc123"
const params = new URLSearchParams(referrer);
const token = params.get('tolk_token');

if (token) {
  const link = await Tolinku.deferred.claimByToken(token);
  if (link) {
    // Navigate to link.deep_link_path
  }
}

Signal-based claiming (iOS)

On iOS, use fingerprint matching instead:

const link = await Tolinku.deferred.claimBySignals({
  appspaceId: 'your_appspace_id'
});

Signal-based claiming uses Dimensions.get('screen') for screen size and Intl.DateTimeFormat for timezone. Language must be passed explicitly if needed.

Referrals

const { referrals } = Tolinku;

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

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

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

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

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

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

In-app messages

Use the TolinkuMessages component to display in-app messages:

import { TolinkuMessages } from '@tolinku/react-native-sdk';

function App() {
  return (
    <View style={{ flex: 1 }}>
      <MainContent />
      <TolinkuMessages
        trigger="on_open"
        onDismiss={(messageId) => {
          console.log('Dismissed:', messageId);
        }}
        onButtonPress={(action, messageId) => {
          // Handle CTA action URL
        }}
      />
    </View>
  );
}

The component fetches messages and displays the highest-priority undismissed message as a React Native modal.

Props

Prop	Type	Description
`trigger`	string	Filter messages by trigger type
`triggerValue`	string	Filter by trigger value
`onDismiss`	function	Called when the user dismisses a message
`onButtonPress`	function	Called when the user taps a CTA button

Cleanup

Clean up when reconfiguring or unmounting:

await Tolinku.destroy();