The Challenge: A Fragmented User Journey

When users click a promotional link, the expected behavior varies drastically based on their device OS and whether the app is already installed.

  • iOS users should be routed to the App Store if uninstalled.
  • Android users must hit Google Play if uninstalled.
  • If the app is already installed, the user expects to land deep inside the app on the specific product screen, completely bypassing the browser. However, in a Flutter cross-platform environment, getting iOS Universal Links (Associated Domains), Android App Links, and deferred deep linking (for post-install routing) to work harmoniously is notoriously difficult. OneLink solves this, but its implementation requires rigorous OS-level configuration. Universal Links Routing

SDK Initialization Protocol

The order of execution during app startup is critical. AppsFlyer must be initialized after Firebase (if used for push/analytics) but strictly before the first Flutter screen renders to ensure the routing payload is caught and acted upon.

void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
await AppsFlyerService.initialize();
runApp(MyApp());
}
class AppsFlyerService {
static AppsflyerSdk? _sdk;
static Future<void> initialize() async {
final options = AppsFlyerOptions(
afDevKey: AppConfig.appsFlyerDevKey,
appId: Platform.isIOS ? AppConfig.iosAppId : null,
showDebug: kDebugMode,
timeToWaitForATTUserAuthorization: 15.0,
);
_sdk = AppsflyerSdk(options);
// Register handlers before init!
_sdk!.onInstallConversionData((data) => _handleConversionData(data));
_sdk!.onAppOpenAttribution((data) => _handleDeepLink(data));
_sdk!.onDeepLinking((DeepLinkResult result) {
if (result.status == Status.FOUND) _handleUDL(result.deepLink!);
});
await _sdk!.initSdk(
registerConversionDataCallback: true,
registerOnAppOpenAttributionCallback: true,
registerOnDeepLinkingCallback: true,
);
}
}

iOS Configuration: Associated Domains

iOS relies on the Apple App Site Association (AASA) file hosted securely domains. 1. Entitlements configuration (Runner.entitlements):

<key>com.apple.developer.associated-domains</key>
<array>
<string>applinks:yourbrand.onelink.me</string>
<string>applinks:yourdomain.kz</string>
</array>

2. AASA Host File (/.well-known/apple-app-site-association): Must be uncompressed JSON served over strictly HTTPS without redirects.

{
"applinks": {
"apps": [],
"details": [{
"appID": "TEAMID.kz.yourdomain.app",
"paths": ["/open/*", "/promo/*", "/invite/*"]
}]
}
}

Android Configuration: Verified App Links

Android 12+ requires App Links to be strictly verified using Digital Asset Links. 1. AndroidManifest.xml intent filter:

<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="yourdomain.kz"/>
</intent-filter>

2. assetlinks.json Hosting:

[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "kz.yourdomain.app",
"sha256_cert_fingerprints": ["AA:BB:CC:..."]
}
}]

Rigorous QA Methodology

Deep links fail silently. To prevent broken user experiences, we executed a 15-point test matrix:

Test scenarioExpected result
iOS: OneLink tap, app not installApp Store opens gracefully
iOS: OneLink tap, app installedTarget app screen opens instantly via Universal Link
iOS: Install via tap (Deferred)First open triggers onInstallConversionData routing
Android: Tap, installedApp Links intercept without browser disambiguation dialog
Meta in-app browserFalls back properly without getting trapped in WebView
ATT prompt iOS 14.5+Initialization respects timeToWaitForATTUserAuthorization

Business Outcomes

After successfully deploying and verifying OneLink across both platforms, campaign conversion rates from Influencer and CRM push channels skyrocketed by 34%. Users were no longer dropping off at the App Store front page; they were transported directly to the cart with their promo codes pre-applied.

Further Reading & Deeper Dive

Understanding how deep links interact with the OS layer is vital for modern mobile engineers.