# Flinku Documentation

> Flinku is a modern Firebase Dynamic Links replacement, a deep linking platform for mobile app developers. Firebase Dynamic Links shut down in August 2025. Flinku provides all the same features plus more, starting free.

## What is Flinku?

Flinku is a deep linking and deferred deep linking platform. It lets developers create short links that open mobile apps to specific screens, even if the app is not yet installed (deferred deep linking). SDK 0.6.0 also includes automatic deferred referral attribution.

Base URL for all API calls: https://api.flinku.dev
Dashboard: https://app.flinku.dev
Short link domain: https://{subdomain}.flku.dev

## Pricing

- Free: 3 projects, 300 links, 10,000 clicks/month
- Indie: $12/month: 10 projects, 5,000 links, 300,000 clicks/month
- Growth: $24/month: 25 projects, 15,000 links, 1,000,000 clicks/month, custom domains included
- Studio: $39/month: unlimited projects, unlimited links, 10M clicks/month, remove "Powered by Flinku" branding

No MAU (Monthly Active User) pricing. Ever.

## SDKs

All SDKs are open source on GitHub (github.com/flinku-dev). Current version across all platforms: **0.7.0**.

- Flutter: pub.dev/packages/flinku_sdk (v0.7.0). createLinkInstant(options): returns shortUrl instantly, saves to server in background
- iOS Swift: github.com/flinku-dev/ios-sdk (v0.7.0). Swift Package Manager. createLinkInstant(options): returns shortUrl instantly, saves to server in background. configure(baseUrl:apiKey:readClipboard:): set readClipboard: false to skip clipboard read and suppress iOS paste dialog when Universal Links handle attribution. Default is true.
- Android Kotlin: github.com/flinku-dev/android-sdk (v0.7.0). JitPack: com.github.flinku-dev:android-sdk. createLinkInstant(options): returns shortUrl instantly, saves to server in background
- React Native: npmjs.com/package/flinku-react-native (v0.7.1). createLinkInstant(options): returns shortUrl instantly, saves to server in background
- Capacitor: npmjs.com/package/flinku-capacitor (v0.7.1). createLinkInstant(options): returns shortUrl instantly, saves to server in background
- Unity: github.com/flinku-dev/unity-sdk (v0.7.0). createLinkInstant(options): returns shortUrl instantly, saves to server in background

⚠️ 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.

## Authentication

Two methods:
1. Firebase ID Token (for dashboard users): Authorization: Bearer <firebase-id-token>
2. Secret API Key (server-side only): Authorization: Bearer flk_live_your_api_key

Publishable keys (`flk_pk_...`) are safe to embed in mobile apps and are required for referral tracking. Secret keys (`flk_live_...`) must never ship in client code. Create both in the dashboard under Settings → API Keys.

## Core Features

### Deferred Deep Linking
When a user clicks a Flinku link and doesn't have the app installed, they are sent to the App Store/Play Store. After install, the app opens to the exact screen the link pointed to. This works via fingerprint matching, clipboard, and (on Android Play Store installs) Play Install Referrer.

### Deferred match consumption (server-side, all SDKs, July 21 2026)
When match() successfully returns a deferred link, the server marks it consumed on first return. A 5-minute grace window allows the same match to be returned again (app restart mid flow). After the grace window, the server will not return that match again. Fingerprint attribution remains available for 24 hours from click to first app open. SDK reset() clears client cache only; it does not undo server consumption.

### match() vs resolving a short link
`match()` is for deferred deep linking: the install attribution match after a user clicked a link before installing. Resolving a short URL that an already-installed user taps (via Universal Links / App Links) is a different job. Use the public endpoint:

GET https://api.flinku.dev/api/links/resolve/:slug?subdomain=yourapp

No authentication required. Returns JSON without redirecting:

```json
{ "slug": "abc123", "deepLink": "yourapp://product/42", "params": { "ref": "instagram" }, "title": "Spring Sale" }
```

400 if slug or subdomain is missing: `{ "error": "slug and subdomain are required" }`
404 if not found: `{ "error": "Link not found" }`

Example: extract slug and subdomain from `https://yourapp.flku.dev/abc123`, then GET `/api/links/resolve/abc123?subdomain=yourapp`, then navigate with `deepLink` and `params`.

### Referral attribution (SDK 0.6.0)
Create invite links with `referrerId` (and optional `referrerLabel`) in params. Pass your publishable `flk_pk_` key to configure. After the new user signs up, call `setUserId`. The SDK attributes the referral automatically. Call `qualifyReferral(event)` when they do the rewarded action. Do not call `/api/referrals/track` from the app, and do not build DIY attribution by manually reading a `ref` param and posting to your own backend for Flinku's referral system.

### iOS Universal Links
The apple-app-site-association (AASA) file is served automatically at:
https://{subdomain}.flku.dev/.well-known/apple-app-site-association

No manual hosting required. Configure your Bundle ID and Team ID in the project settings.

### Android App Links
The assetlinks.json file is served automatically at:
https://{subdomain}.flku.dev/.well-known/assetlinks.json

Configure your package name and SHA-256 fingerprint in project settings.

### Deepview Pages
Mobile landing pages shown when a user clicks a link. Shows your app icon (fetched from iTunes API automatically), app name, and a download button. Customizable with custom colors, layout, and branding on Studio plan.

## Flutter SDK Usage

```dart
// pubspec.yaml
dependencies:
  flinku_sdk: ^0.7.0

// Configure once at app start (baseUrl required; apiKey required for referrals)
Flinku.configure(
  baseUrl: 'https://yourapp.flku.dev',
  apiKey: 'flk_pk_...', // publishable key only, never flk_live_
);

// After install / cold start, get the deep link
final match = await Flinku.match();
if (match != null) {
  final screen = match.params?['screen'];
  final productId = match.params?['id'];
}

// Referrals (after signup or login)
Flinku.setUserId(user.id);
Flinku.qualifyReferral('purchase'); // when they do the rewarded action
```

createLinkInstant(options): returns shortUrl instantly, saves to server in background

reset(): `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(): `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.

## iOS Swift SDK Usage

```swift
// Swift Package Manager, Exact Version 0.7.0
// https://github.com/flinku-dev/ios-sdk

import FlinkuSDK

Flinku.configure(
  baseUrl: "https://yourapp.flku.dev",
  apiKey: "flk_pk_..." // publishable key only, never flk_live_
)

let match = await Flinku.match()
if let params = match?.params {
  let screen = params["screen"]
}

// Referrals
Flinku.setUserId(user.id)
Flinku.qualifyReferral("purchase")
```

createLinkInstant(options): returns shortUrl instantly, saves to server in background

configure(baseUrl:apiKey:readClipboard:): set readClipboard: false to skip clipboard read and suppress iOS paste dialog when Universal Links handle attribution. Default is true.

reset(): `Flinku.reset()` clears the cached match result only (removes the two match keys). Does not clear the stored user id or pending referral attribution. This changed in 0.6.0.

resetAll(): `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.

## Android Kotlin SDK Usage

```kotlin
// build.gradle: JitPack (https://jitpack.io must be in repositories)
implementation 'com.github.flinku-dev:android-sdk:0.7.0'

Flinku.configure(
  context = this,
  baseUrl = "https://yourapp.flku.dev",
  apiKey = "flk_pk_..." // publishable key only, never flk_live_
)

val match = Flinku.match(this)
val productId = match?.params?.get("id")

// Referrals
Flinku.setUserId(this, user.id)
Flinku.qualifyReferral(this, "purchase")
```

createLinkInstant(options): returns shortUrl instantly, saves to server in background

reset(): `Flinku.reset(context)` clears the cached match result only. Does not clear the stored user id or pending referral attribution. This changed in 0.6.0.

resetAll(): `Flinku.resetAll(context)` 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.

## React Native SDK Usage

Class-based, instance-only API. Create one `Flinku` instance at startup; there is no `configure()` method and no exported singleton.

```typescript
// npm install flinku-react-native@^0.7.1
import { Flinku } from 'flinku-react-native';

const flinku = new Flinku({
  userId: 'anonymous',
  baseUrl: 'https://yourapp.flku.dev',
  apiKey: 'flk_pk_...', // publishable key only, never flk_live_
});

const link = await flinku.match();

// Referrals
flinku.setUserId(user.id);
flinku.qualifyReferral('purchase');
```

reset(): `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(): `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.

## Capacitor SDK Usage

Class-based, instance-only API (named and default export). Create one `Flinku` instance at startup; there is no `configure()` method and no exported singleton.

```typescript
// npm install flinku-capacitor@^0.7.1
import { Flinku } from 'flinku-capacitor';

const flinku = new Flinku({
  userId: 'anonymous',
  baseUrl: 'https://yourapp.flku.dev',
  apiKey: 'flk_pk_...',
});

const link = await flinku.match();
flinku.setUserId(user.id);
flinku.qualifyReferral('purchase');
```

reset(): `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(): `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.

## Unity SDK Usage

```csharp
// UPM: https://github.com/flinku-dev/unity-sdk.git (tag 0.7.0)
var sdk = FlinkuSDK.Initialize(new FlinkuConfig {
  BaseUrl = "https://yourapp.flku.dev",
  ApiKey = "flk_pk_..."
});

sdk.SetUserId(user.Id);
sdk.QualifyReferral("purchase");
```

reset(): `FlinkuSDK.Instance.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(): `FlinkuSDK.Instance.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.

## Key API Endpoints

### Match API (deferred deep linking)
POST https://api.flinku.dev/api/match
Body: { "subdomain": "yourapp", "userAgent": "..." }
Returns: { "deepLink": "yourapp://screen", "params": { "id": "123" } }

### Links API
GET /api/projects/{projectId}/links: list links
POST /api/projects/{projectId}/links: create link
DELETE /api/projects/{projectId}/links/{linkId}: delete link

### Analytics API
GET /api/projects/{projectId}/analytics: click analytics
GET /api/analytics/influencers?projectId=X: influencer breakdown

### Referrals API
Apps must use SDK methods (`setUserId`, `qualifyReferral`), not these endpoints by hand from the mobile client.
POST /api/referrals/track: called automatically by Flinku.setUserId (do not call by hand from the app)
POST /api/referrals/qualify: called by Flinku.qualifyReferral (prefer the SDK)
GET /api/referrals?projectId=X&range=7d|30d|all: funnel and referrers (auth required)

Invite links should include params:
```json
{ "referrerId": "user_123", "referrerLabel": "Alice" }
```

## Link Features

- Password protection: links can require a password before redirecting
- Scheduled links: activate at a specific date/time (shows "Coming Soon" page before)
- Link expiry: set an expiry date, link stops working after
- Max clicks: limit total clicks on a link
- Geo routing: redirect to different URLs based on country
- Smart fallback chain: HEAD-check multiple URLs, redirect to first live one
- Custom params: key-value pairs appended to the deep link URI
- UTM parameters: standard UTM tracking
- QR codes: auto-generated for every link, customizable
- Link tags: organize links with tags
- Link cloning: duplicate links with a new name
- Bulk CSV import: import up to 500 links at once
- Dynamic URL variables: #{platform}, #{country}, #{slug} in URLs

## Influencer & Affiliate Tracking

Set an influencerId on any link:
```json
{
  "title": "Sarah promo",
  "deepLink": "yourapp://promo",
  "influencerId": "sarah_jones"
}
```

After match(), read the influencerId and store it. When a purchase occurs, send influencerId to your backend to record commission. Flinku tracks clicks and installs per influencer. Commission calculation and payouts are handled by your own backend.

For user-to-user invite programs, use the Referral attribution system above (`referrerId` + `setUserId` + `qualifyReferral`), not DIY influencer wiring.

## Firebase Migration

Flinku has a built-in migration tool at app.flinku.dev/migrate. It converts existing Firebase Dynamic Links to Flinku links. Also available via API:
POST /api/migration/preview: preview conversion
POST /api/migration/convert: convert Firebase links

## Free Tools (no login required)

Available at flinku.dev/tools:
- Deep Link Tester
- AASA Validator (7 validation checks)
- Android Assets Validator
- UTM Builder
- Social Preview Checker

## Custom Domains (Growth and Studio plans)

Add your own domain (e.g. links.yourapp.com) instead of yourapp.flku.dev.
Add a CNAME record pointing to flinku.dev, then verify in dashboard.
SSL is provisioned automatically via Let's Encrypt.

## Retargeting Pixel

A 1×1 pixel for retargeting campaigns:
GET https://{subdomain}.flku.dev/api/pixel/{projectId}

## Journeys Web Banner

Add a smart banner to your website that prompts mobile users to open your app:
```html
<script src="https://{subdomain}.flku.dev/api/projects/{projectId}/journey.js"></script>
```

Shows only on mobile browsers. Uses the URI scheme to open the app directly.

## Testing deferred deep links on Android
Installing over ADB (npm run android, Android Studio Run, adb install) exercises fingerprint matching only. Play Install Referrer is only available on Play Store installs. To verify the referrer path end-to-end, use a Google Play Internal Testing track build and install from the Play Store.

## Support

- Docs: docs.flinku.dev
- Referral system: docs.flinku.dev/docs/referral-system
- Dashboard: app.flinku.dev
- Email: hello@flinku.dev