App Integration Guide

End-to-end setup for Flutter, iOS, and Android: HTTPS app links, optional URI scheme fallback, SDK initialization, and testing.

1. Overview

Flinku can deliver users into your app in two ways:

Universal Links / App Links (recommended)

iOS and Android open your app directly from the HTTPS short link (e.g. https://yourapp.flku.dev/abc123). Requires Associated Domains (iOS) and verified App Links (Android). This is the most seamless and secure path for production.

URI scheme fallback

The OS can open your app via a custom scheme (e.g. masroofati://). Easier to configure for quick tests, but weaker for security and consistency than verified HTTPS links.

2. Flutter integration

Step 1: Add dependency

pubspec.yaml

dependencies:
  flinku_sdk: ^0.7.2

Step 2: iOS: Add Associated Domains

Open Xcode → Runner → Signing & Capabilities → + Capability → Associated Domains.
Add: applinks:yourapp.flku.dev
If using a custom domain: also add applinks:links.yourdomain.com (replace with your verified host).

Step 3: iOS: Add URI scheme (fallback)

In ios/Runner/Info.plist:

Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourapp</string>
    </array>
  </dict>
</array>

Step 4: Android: Add App Links

In android/app/src/main/AndroidManifest.xml inside <activity>:

AndroidManifest.xml

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https" android:host="yourapp.flku.dev" />
</intent-filter>

Step 5: Android: Add URI scheme (fallback)

AndroidManifest.xml

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="yourapp" />
</intent-filter>

Step 6: Initialize SDK in main.dart

ℹ️Info

Ensure Firebase is initialized (e.g. Firebase.initializeApp()) before reading FirebaseAuth if you use the snippet below.

main.dart

import 'package:firebase_auth/firebase_auth.dart';
import 'package:flinku_sdk/flinku_sdk.dart';
import 'package:flutter/material.dart';
 
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final user = await FirebaseAuth.instance.authStateChanges().first;
  final flinku = Flinku(
    userId: user?.uid ?? '',
    baseUrl: 'https://yourapp.flku.dev',
  );
  final link = await flinku.match();
  if (link != null) {
    // Navigate to link.deepLink
    // Access link.params for custom data
  }
  runApp(MyApp());
}

3. iOS (Swift) integration

Associated Domains: In Xcode, add applinks:yourapp.flku.dev (and custom domain entries if applicable).
URI scheme: Add your URL scheme in Info.plist as in the Flutter section above.

Initialize SDK (AppDelegate or SwiftUI)

AppDelegate.swift

import FlinkuSDK
 
let flinku = Flinku(userId: Auth.auth().currentUser?.uid ?? "", baseUrl: "https://yourapp.flku.dev")
flinku.match { link in
  guard let link = link else { return }
  // Navigate to link.deepLink
  // Access link.params
}

💡Tip

Add import FirebaseAuth (and configure Firebase) so Auth.auth() resolves.

4. Android (Kotlin) integration

App Links: Add the HTTPS intent-filter with yourapp.flku.dev as in the Flutter section.
URI scheme: Add the optional yourapp scheme intent filter for fallback.

Initialize SDK (MainActivity or Application)

MainActivity.kt

import dev.flinku.sdk.Flinku
 
val flinku = Flinku(userId = FirebaseAuth.getInstance().currentUser?.uid ?: "", baseUrl = "https://yourapp.flku.dev")
lifecycleScope.launch {
  val link = flinku.match()
  link?.let {
    // Navigate to it.deepLink
    // Access it.params
  }
}

💡Tip

Import com.google.firebase.auth.FirebaseAuth and ensure Firebase is initialized before use.

5. Create links programmatically

Flutter SDK 0.7.0+ and native SDKs (iOS 0.7.0+, Android 0.7.0+, React Native 0.7.1+, Capacitor 0.7.1+, Unity 0.7.0+) expose createLink() so you can generate short URLs without calling the REST API directly. Pass your publishable key (flk_pk_) when configuring the SDK in the app. Never embed flk_live_ in client code.

Flutter

dart

final flinku = Flinku(
  userId: user.uid,
  baseUrl: 'https://yourapp.flku.dev',
  apiKey: 'flk_pk_...', // publishable key only, never flk_live_
);
 
final link = await flinku.createLink(FlinkuLinkOptions(
  title: 'Summer Campaign',
  deepLink: 'yourapp://promo',
  params: {'ref': 'instagram', 'promo': 'SAVE20'},
  utmSource: 'instagram',
  utmMedium: 'social',
));
 
print(link.shortUrl); // https://yourapp.flku.dev/summer-campaign

iOS (Swift)

swift

var options = FlinkuLinkOptions(title: "Summer Campaign")
options.deepLink = "yourapp://promo"
options.params = ["ref": "instagram"]
 
flinku.createLink(options) { result in
  switch result {
  case .success(let link):
    print(link.shortUrl)
  case .failure(let error):
    print(error)
  }
}

Android (Kotlin)

kotlin

val link = flinku.createLink(FlinkuLinkOptions(
  title = "Summer Campaign",
  deepLink = "yourapp://promo",
  params = mapOf("ref" to "instagram")
))
println(link.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.