sentalong-react-native

Sentalong attribution for React Native apps: record partner clicks from deep links, tie them to users at signup, and report qualification stages.

A thin client over Sentalong's public tracking API. Zero runtime dependencies beyond your app's own platform: HTTP uses the built-in fetch, persistence uses @react-native-async-storage/async-storage (a peer dependency). The SDK sends only the fields you pass in — no analytics, no fingerprinting, no device identifiers.

Install

npm install sentalong-react-native @react-native-async-storage/async-storage
# or
yarn add sentalong-react-native @react-native-async-storage/async-storage

iOS: cd ios && pod install (for AsyncStorage).

Quickstart

1. Configure once at startup

import { configure } from 'sentalong-react-native';

configure('https://YOUR-SENTALONG-ORIGIN.com', 'prg_your_program_id');
// Custom attribution param (defaults to "via"):
// configure(baseUrl, programId, { urlParam: 'ref' });

2. Set up deep links and feed them to Sentalong

First make sure your app opens links at all — universal links / App Links for https:// URLs and/or a custom scheme (myapp://) — per the React Native Linking docs.

Then let the SDK listen. subscribeToDeepLinks processes the cold-start initial URL and every subsequent url event:

import { useEffect } from 'react';
import { subscribeToDeepLinks } from 'sentalong-react-native/linking';

export function App() {
  useEffect(() => {
    const subscription = subscribeToDeepLinks();
    return () => subscription.remove();
  }, []);
  // ...
}

Prefer to wire it yourself (e.g. you already have a Linking listener or use a navigation library's deep-link handling)? Call handleUrl directly:

import { Linking } from 'react-native';
import { handleUrl } from 'sentalong-react-native';

Linking.getInitialURL().then((url) => url && handleUrl(url));
Linking.addEventListener('url', ({ url }) => handleUrl(url));

handleUrl accepts any URL shape — https://site.com/?via=maya&sub_id=x or myapp://open?via=maya — extracts the attribution param, sub_id (also sub1), and ad-click ids (gclid, fbclid, ttclid, twclid, li_fat_id, msclkid), records the click, and persists the returned click id (cid) for the attribution window the server specifies. It returns the cid or null, and never throws — network failures resolve to null. A link with via=test is a dry run: the SDK logs Sentalong: test click received and sends/stores nothing.

3. Identify at signup

When the user creates an account, tie the stored click to them:

import { identify } from 'sentalong-react-native';

const referralId = await identify(email, { externalId: user.id });
if (referralId) {
  // The signup was referred — referralId is "ref_…"
}

identify returns null if there is no stored (unexpired) click or the request fails. It is safe to call on every signup and safe to repeat — the server is idempotent.

4. Optional: report qualification stages

import { qualify } from 'sentalong-react-native';

await qualify('signup');     // 'signup' | 'onboarded' | 'demo'

Attribution limits on iOS (honest edition)

There is no install referrer on iOS. Android's Play Store passes the referring URL's parameters through installation; the App Store does not. What that means in practice:

• App already installed — attribution works. A universal link or custom scheme link with ?via=partner opens the app, handleUrl sees the parameters, the click is recorded.
• App not installed — the link sends the user to the App Store, and the query parameters are lost. When the app is opened after install there is no URL to hand you, so the click cannot be attributed by this SDK.

If install attribution on iOS matters to you, route partner links through a web landing page on your Sentalong-instrumented site first (the web snippet records the click there), or use your own deferred-deep-link mechanism and pass the reconstructed URL to handleUrl. This SDK will not fingerprint devices to guess at attribution — that is both unreliable and an App Store policy risk.

Testing your integration

Append ?via=test to your link and open it: the SDK logs Sentalong: test click received without recording anything.

In unit tests, inject storage and fetch fakes:

configure('https://example.com', 'prg_x', {
  storage: myInMemoryStorage, // { getItem, setItem, removeItem }
  fetchFn: myMockFetch,
});

API

| Function | Returns | Notes | | --- | --- | --- | | configure(baseUrl, programId, { urlParam?, storage?, fetchFn? }) | void | Call once at startup. | | handleUrl(url) | Promise<string \| null> | cid on success; never throws. | | identify(email, { externalId? }) | Promise<string \| null> | referralId or null. | | qualify(stage) | Promise<boolean> | | | subscribeToDeepLinks(onUrlHandled?) (from /linking) | { remove() } | Initial URL + url events. |

Storage keys used: sentalong.cid, sentalong.cid_expires_at.

License

MIT