React Native SDK

Class-based SDK for deferred deep linking and programmatic link creation. Create one Flinku instance at app startup and call every method on that instance. There is no configure() method and no exported singleton.

Installation

bash

npm install flinku-react-native@^0.7.5

Setup

Create one instance when your app starts (for example in a module-level singleton) and reuse it everywhere. Pass a stable userId (Firebase UID, your own user id, or a device UUID for anonymous users), your project baseUrl, and your publishable apiKey when you need link creation or referrals. Complete iOS Associated Domains and Android App Links as in the Quick Start.

flinku.ts

import { Flinku } from 'flinku-react-native';
 
export const flinku = new Flinku({
  userId: 'unique-device-or-user-id',
  baseUrl: 'https://yourapp.flku.dev',
  apiKey: 'flk_pk_...', // publishable key only, never flk_live_
});

`match()`

match() recovers deferred install attribution. It is not your App Link / Universal Link / URI scheme handler. If your app already routes a launch URL, do not let a deferred match() result overwrite it — call match() only when no launch URL is present. See Apps that already handle their own deep links.

typescript

import { flinku } from './flinku';
 
const link = await flinku.match();
if (link?.deepLink) {
  // Navigate using your router
}

`reset()`

typescript

await flinku.reset();

Clears the cached match result only. Does not clear the stored user id or pending referral attribution. This changed in 0.6.0.

`resetAll()`

typescript

await flinku.resetAll();

Clears everything reset() clears, plus the stored user id, referral project id, all pending referral records, and any tracked-once markers. Testing only — do not call in production. Calling it in production destroys real referral attribution. Added in 0.7.0.

`createLink()`

⚠️ Never ship secret API keys in mobile appsSecret keys (flk_live_) can be extracted from any compiled APK or .ipa. Use your publishable key (flk_pk_) in the app, or proxy link creation through your backend with the secret key.

App → Your Backend → Flinku API → short URL → App shares it (secret key stays on the server)

typescript

const created = await flinku.createLink({
  title: 'Summer Campaign',
  deepLink: 'yourapp://promo',
  params: { ref: 'instagram' },
});
console.log(created.shortUrl);

`createLinkInstant()`

Returns the short URL instantly without waiting for the server. The link is saved in the background. Use this for share buttons where speed matters.

If the background save fails on a transient error (network, timeout, 5xx, or 429), the SDK retries up to three times with 1s, 2s, and 4s delays. A URL shared immediately can still 404 for up to roughly 7 seconds while retries run. Set debug: true in the constructor to log terminal failures.

⚠️ Do not wrap createLinkInstant in an async function. It is synchronous and returns immediately. Wrapping it in async/await will add unnecessary delay and defeat the purpose.

typescript

import { Share } from 'react-native';
import { flinku } from './flinku';
 
const created = flinku.createLinkInstant({
  title: 'Summer Campaign',
  deepLink: 'yourapp://promo',
  params: { ref: 'instagram' },
});
await Share.share({ message: created.shortUrl });

Referrals

typescript

flinku.setUserId(user.id);
flinku.qualifyReferral('purchase');

Full TypeScript example

FlinkuBootstrap.tsx

import React, { useEffect, useState } from 'react';
import { View, Text, Button } from 'react-native';
import { Flinku, type FlinkuLink } from 'flinku-react-native';
 
const flinku = new Flinku({
  userId: 'unique-device-or-user-id',
  baseUrl: 'https://yourapp.flku.dev',
  apiKey: 'flk_pk_...',
});
 
export function FlinkuBootstrap() {
  const [pending, setPending] = useState<FlinkuLink | null>(null);
 
  useEffect(() => {
    void (async () => {
      const link = await flinku.match();
      if (link) setPending(link);
    })();
  }, []);
 
  const shareCampaignLink = async () => {
    const link = await flinku.createLink({
      title: 'Partner promo',
      deepLink: 'yourapp://promo',
      params: { ref: 'instagram' },
    });
    console.log('Short URL:', link.shortUrl);
  };
 
  return (
    <View style={{ padding: 16 }}>
      {pending?.deepLink ? (
        <Text>Deferred link: {pending.deepLink}</Text>
      ) : (
        <Text>No pending Flinku link</Text>
      )}
      <Button title="Create link" onPress={shareCampaignLink} />
    </View>
  );
}