Deep link contract

The URL format AppMate emits when the public flow completes — what every SDK parses, and how to coexist with your existing handlers.

Shape

text
{yourscheme}://retention-flow/action
  ?type={action_key}
  &session_id={sid}
  [&feature_id=...]
  [&offer_id=...]
  [&paywall_id=...]
  [&topic=...&message=...]
  [&url=...]

Host is always retention-flow, path is always /action. Together they namespace AppMate's URLs so your existing deep-link handlers never accidentally claim one.

Action keys

  • return_to_app — open your home screen.
  • open_premium — show the paywall. Optional paywall_id.
  • open_offer — required offer_id; your app maps it to a StoreKit promo / Play Billing offer / RevenueCat offering / custom paywall.
  • open_support — optional topic + message for prefill.
  • open_feature — required feature_id.
  • manage_subscription— StoreKit 2's sheet on iOS, Google Play's subscriptions page on Android; no extra params.
  • external_url — required url, must be https.
  • onboarding_complete — emitted by a web-to-app onboarding funnel the SDK presented; carries an optional claim_token the SDK redeems for the captured answers + email. See the onboarding funnel guide.
  • wishlist_submitted — emitted by a hosted wishlist board the SDK presented when a new idea is submitted; carries idea_id.
  • referral — the installed-app invite link; carries the referral code. Pass the URL to redeemReferralFromURL (iOS) / redeemReferralFromUri (Android).
  • none — reserved / unknown; handle defensively.

Coexisting with your existing deep links

The SDK's deepLink(from:) returns nil for URLs that don't match the contract. Chain it in front of your existing handler — non-AppMate URLs pass through:

swift
.onOpenURL { url in
    if let link = RetentionFlow.deepLink(from: url) {
        handleAppMate(link)
        return
    }
    handleMyExistingDeepLinks(url)
}
manage_subscription never enters your URL handler — the SDK calls Apple's StoreKit sheet directly.

On Android

The Android SDK presents hosted flows in its own in-app WebView and intercepts the retention-flow navigation there, so flows the SDK opens need no manifest intent-filter — the action arrives in your onAction callback. Register the scheme only for links that open the app from outside (the referral installed-app link), then chain the parser the same way:

kotlin
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    if (RetentionFlow.handleDeepLink(intent) { link -> handleAppMate(link) }) return
    handleMyExistingDeepLinks(intent)
}

See the Android SDK guide for the manifest entry.