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

dependencies:
  flinku_sdk: ^0.3.2

Step 2: iOS — Add Associated Domains

1. Open Xcode → Runner → Signing & Capabilities → + Capability → Associated Domains.
2. Add: applinks:yourapp.flku.dev
3. 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:

CFBundleURLTypes

  
    CFBundleURLSchemes
    
      yourapp

Step 4: Android — Add App Links

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

Step 5: Android — Add URI scheme (fallback)

Step 6: Initialize SDK in main.dart

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

import 'package:firebase_auth/firebase_auth.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

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

Initialize SDK (AppDelegate or SwiftUI)

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

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

Initialize SDK (MainActivity or Application)

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.3.2+ and native SDKs 0.3.0+ expose createLink() so you can generate short URLs without calling the REST API directly. Pass your API key when constructing Flinku.

Flutter

final flinku = Flinku(
  userId: user.uid,
  baseUrl: 'https://yourapp.flku.dev',
  apiKey: 'flk_live_your_api_key',
);

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)

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)

val link = flinku.createLink(FlinkuLinkOptions(
  title = "Summer Campaign",
  deepLink = "yourapp://promo",
  params = mapOf("ref" to "instagram")
))
println(link.shortUrl)

6 — Testing your integration

• Build and install the app on a real device.
• Create a test link in the Flinku dashboard.
• Open the link in Safari or Chrome (not by typing the URL manually).
• Verify the app opens directly from the link.
• Uninstall the app, tap the link, install from the store, then open the app and verify deferred deep linking restores the intended destination.