Flinku Docs
Go to Dashboard

Capacitor SDK

Same class-based, instance-only API as the React Native SDK for Capacitor hybrid apps. Create one Flinku instance at app startup and call every method on that instance. There is no configure() method and no exported singleton. The package exports both a named export and a default export.

Installation

bash
npm install flinku-capacitor@^0.7.5
npx cap sync

Setup

Create one instance when your app starts and reuse it everywhere. Pass a stable userId, your project baseUrl, and your publishable apiKey when you need link creation or referrals. Complete native iOS Associated Domains and Android App Links as in the Quick Start and React Native SDK docs.

flinku.ts
import { Flinku } from 'flinku-capacitor';
// or: import Flinku from 'flinku-capacitor';
 
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_) belong on your backend only. In the app, use a publishable key (flk_pk_) or call your own server to create links.
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 '@capacitor/share';
import { flinku } from './flinku';
 
const created = flinku.createLinkInstant({
  title: 'Summer Campaign',
  deepLink: 'yourapp://promo',
  params: { ref: 'instagram' },
});
await Share.share({ text: created.shortUrl });

Referrals

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

TypeScript example

flinku.ts
import { Flinku } from 'flinku-capacitor';
 
const flinku = new Flinku({
  userId: 'unique-device-or-user-id',
  baseUrl: 'https://yourapp.flku.dev',
  apiKey: 'flk_pk_...',
});
 
export async function initFlinku() {
  const link = await flinku.match();
  if (link?.deepLink) {
    return link.deepLink;
  }
  return null;
}
 
export async function makeShareLink() {
  return flinku.createLink({
    title: 'Capacitor promo',
    deepLink: 'myapp://promo',
    params: { ref: 'web' },
  });
}

Backend-only (Node): keep the secret key on the server. The app calls your API; your API calls Flinku.

server.js (backend only)
// Backend only: never put flk_live_ in the Capacitor app
app.post('/create-share-link', async (req, res) => {
  const response = await fetch('https://flku.dev/api/links', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer flk_live_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      projectId: 'your_project_id',
      title: 'Capacitor promo',
      deepLink: 'myapp://promo',
      params: { ref: 'web' },
    }),
  });
  const { shortUrl } = await response.json();
  res.json({ shortUrl });
});