Deferred deeplinks in Adapty User Acquisition

Deferred deeplinks allow you to pass custom data to your app when users install it after clicking your ads. For example, you can navigate them to a specific location in your app right after they install and launch it.

Here’s how it works:

When a user clicks your ad, Adapty saves the click data.
When Adapty registers the install event, it gets deferred data from the click.
After the user installs your app, and it launches for the first time, Adapty retrieves the stored data and your app receives the custom parameters, allowing you to react to different values in the app code.

Adapty supports the following deferred data parameters:

ios_deferred_data
android_deferred_data
deferred_data_sub[1-10]

To add deferred data parameters, append them to your link in your campaign settings:

Open your campaign from the Integrations -> Meta/TikTok Ads page. Or, open your tracking link from the Tracking links page. Copy the click link you will use in your campaign.

In your ad platform (Meta, TikTok, Google Ads, etc.), paste the link into the ad destination URL field, then append the deferred data parameters to it as extra query parameters — each prefixed with &. For example, to send iOS users to a ‘Welcome’ screen after install, add &ios_deferred_data=welcome. The final destination URL will look like this:

https://api-ua.adapty.io/api/v1/attribution/click?adpt_cid=__ADAPTY__ID__&ios_deferred_data=welcome&campaign_id=__CAMPAIGN_ID__&adset_id=__AID__&ad_id=__CID__&campaign_name=__CAMPAIGN_NAME__&adset_name=__AID_NAME__&ad_name=__CID_NAME__&redirect_url=__APP_LINK__

Respond to parameters in your app code. Note that deferred data parameters are in the payload parameter, and the payload parameter is an escaped JSON, so you need to parse it in your app code.

For example, here is how you can handle installations where ios_deferred_data is welcome:

Adapty.delegate = self

nonisolated func onInstallationDetailsSuccess(_ details: AdaptyInstallationDetails) {
    guard
        let payloadStr = details.payload,
        let data = payloadStr.data(using: .utf8),
        let payload = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
        let deeplink = payload["ios_deferred_data"] as? String,
        deeplink == "welcome"
    else { return }

    DispatchQueue.main.async {
        print("Navigate to welcome screen")
        // navigate to your screen here
    }
}

Adapty.setOnInstallationDetailsListener(object : OnInstallationDetailsListener {
    override fun onInstallationDetailsSuccess(details: AdaptyInstallationDetails) {
        details.payload?.let {
            runCatching {
                val json = JSONObject(it)
                if (json.optString("android_deferred_data") == "welcome") {
                    println("Navigate to welcome screen")
                    // navigate here
                }
            }.onFailure(Throwable::printStackTrace)
        }
    }
})

adapty.addEventListener('onInstallationDetailsSuccess', details => {
    // Parse the payload JSON and navigate to welcome screen if needed
    try {
        if (details.payload) {
            const payload = JSON.parse(details.payload);
            if (payload.ios_deferred_data === 'welcome') {
                // Navigate to welcome screen
                // Replace with your app's navigation logic
                // For example, using React Navigation:
                // navigation.navigate('Welcome');
                console.log('Navigate to welcome screen');
            }
        }
    } catch (error) {
        console.error('Error parsing installation details payload:', error);
    }
});

Adapty().onUpdateInstallationDetailsSuccessStream.listen((details) {
  final payloadStr = details.payload;
  if (payloadStr == null) return;

  final payload = json.decode(payloadStr) as Map<String, dynamic>;
  if (payload['ios_deferred_data'] == 'welcome') {
    print('Navigate to welcome screen');
  }
});