Smart Links & Deeplinking

What is a smart link?#

A smart link is a URL on your {appId}.mobana.ai domain that delivers a structured payload (unlocks, referral codes, in-app routing, etc.) to your app — regardless of whether the user has the app installed and regardless of which browser they tapped from.

Use one when you want any of:

• Influencer / referral links that unlock something in-app
• Push, email, or share links that deep-link past the launch screen
• QR codes that route returning users to a specific feature
• Re-engagement campaigns where the URL itself is the payload

Use /redirect (instead of /deeplink) for traditional ad-attribution campaigns where the web flow itself adds value (landing pages, web pixels, social-proof previews). Both live side by side; pick per link.

A concrete example#

You DM a creator their unique link:

https://YOUR_APP_ID.mobana.ai/deeplink
  ?data={"unlock":"PROMO50","ref":"creator123"}
  &utm_source=tiktok
  &utm_campaign=influencer_drop

When the creator's audience taps it:

• App installed: the OS opens your app directly (Universal Link / App Link). Your onDeepLink handler fires within ~50 ms with the parsed payload.
• App not installed: the user goes through the App Store / Play Store. On first launch, the SDK matches the click probabilistically and your onDeepLink handler fires with source: 'deferred' — same payload.
• App installed but UL failed (in-app browsers like Instagram / TikTok strip Universal Links): the user lands in the App Store, taps Open, your app launches, the SDK probes the server, and your handler fires with source: 'probabilistic'.

Setup#

1. Configure your app for Universal Links / App Links

In Dashboard → App Settings → Deeplinks, add your iOS Team ID and your Android SHA-256 fingerprint(s). Mobana serves the apple-app-site-association and assetlinks.json files automatically at https://{appId}.mobana.ai/.well-known/... — you don't host them yourself.

keytool -list -v -keystore /path/to/your.keystore -alias your_key_alias

2. Register the domain in your mobile app

iOS — Xcode → Signing & Capabilities → Associated Domains:

applinks:YOUR_APP_ID.mobana.ai
# Or, when using a custom endpoint:
applinks:yourdomain.com

Android — AndroidManifest.xml:

<!-- AndroidManifest.xml — inside the launcher <activity> -->

<!-- Mobana subdomain (always required) -->
<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="YOUR_APP_ID.mobana.ai"
          android:pathPrefix="/deeplink" />
</intent-filter>

<!-- Custom domain — add this block only if you use a custom endpoint.
     Each host needs its own <intent-filter>; mixing hosts in one filter
     creates unintended host × path combinations. -->
<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.com"
          android:pathPrefix="/da/deeplink" />
</intent-filter>

3. Wire your payload handler

Wire the same idempotent payload handler to both getAttribution() and onDeepLink() — different delivery cases surface via different paths, and a few cases fire both:

import { Mobana, MobanaProvider } from '@mobana/react-native-sdk';

await Mobana.init({
  appId: 'a1b2c3d4',
  appKey: process.env.MOBANA_APP_KEY,
});

interface UnlockData { unlock?: string; ref?: string }

// Wire the SAME idempotent handler to both surfaces:
// - getAttribution() — surfaces deferred deeplinks via the install attribution path.
// - onDeepLink()     — surfaces every smart-link tap (UL, deferred, probe).
function applyPayload(data?: UnlockData, ref?: string) {
  if (data?.unlock) unlockPromo(data.unlock);
  if (data?.ref || ref) trackReferral(data?.ref ?? ref);
}

const result = await Mobana.getAttribution<UnlockData>();
if (result.status === 'matched') {
  applyPayload(result.attribution.data, result.attribution.utm_source);
}

Mobana.onDeepLink<UnlockData>((event) => {
  applyPayload(event.data, event.utm.source);
});

If you already use <MobanaProvider> for flows, you can add onDeepLink directly to it:

<MobanaProvider
  onDeepLink={(event) => {
    if (event.data?.unlock) unlockPromo(event.data.unlock);
  }}
>
  <App />
</MobanaProvider>

Delivery matrix#

The following table shows what fires for each combination of install state / attribution state / Universal-Link interception. The takeaway: wire one idempotent handler to both surfaces and you don't need to special-case any cell.

Privacy / tracking-disabled mode#

When you call Mobana.setTrackingEnabled(false) (or pass enableTracking: false to init()), smart links still deliver payloads — your in-app behaviour (unlocks, ref tracking, routing) keeps working in all five cases above. What changes server-side:

• No installId is sent on probe / record calls.
• Server doesn't write a per-device DeeplinkClick row. The probe still claims the matched Click so it can't be re-fired, but no row links it to a device.
• /deeplink/record is not called at all when a Universal Link fires — the SDK parses the URL locally and surfaces it via onDeepLink only.

Security notes#

• Don't put secrets in the URL. The data param is visible to anyone who gets the link. Treat it like a signed coupon code, not a JWT.
• Re-engagement window is intentionally short (5 min). A click can only trigger an onDeepLink on an installed device for 5 minutes after the tap. For deferred installs, the longer install-attribution window applies as usual.
• Probe matches require a tight signal match. Confidence ≥ 0.9 (vs 0.7 for install attribution). If you see false negatives, check that your custom-endpoint proxy is forwarding the real client IP (X-Real-IP).