The OneLink Developer Hub

Welcome to the OneLink developer hub. You'll find comprehensive guides and documentation to help you start working with OneLink as quickly as possible, as well as support if you get stuck. Let's jump right in!

Unified deep linking

At a glance: Unified deep linking sends new and existing users to a specific in-app activity as soon as the app is opened.

Overview

Deep linking directs mobile users into a specific activity or content in an app.

This routing to a specific in-app activity is possible due to the onDeepLinking method that carries click data whether or not the users already have the app installed. The AppsFlyer OneLink ensures that the correct parameters are passed along with the user's click when onDeepLinking is called, thus personalizing the user’s experience.

The marketer and developer must coordinate regarding desired app behavior and deep_link_value. The marketer uses the parameters to create deep links, and the developer customizes the behavior of the app based on the value received.

The AppsFlyer SDK returns the parameters from the link that the user clicked, and it is the developer's responsibility to make sure the parameters are handled correctly in the app, for both in-app routing, and personalizing data in the link.

The flow works as follows:

  1. User clicks the OneLink short URL.
  2. The Android App Links (for deep linking) or the deferred deep link, trigger the SDK.
  3. The SDK triggers the onDeepLinking method, and passes the deep link result object to the user.
  4. The onDeepLinking method uses the deep link result object that includes the deep_link_value and other parameters to create the personalized experience for the users, which is the main goal of OneLink.

Considerations

The unified deep linking API:

  • Requires AppsFlyer Android SDK V6.1 or later.
  • Does not support SRN campaigns.
  • Does not provide af_dp in the API response.

Procedures

To implement the onDeepLinking method and set up the parameter behaviors, the following action checklist of procedures need to be completed.

Procedure checklist

  1. Deciding app behavior and deep_link_value (and other parameter names and values) - with the marketer
  1. Planning method input, i.e. deep_link_value (and other parameter names and values) - with the marketer
  1. Implementing the onDeepLinking() logic

Deciding app behavior

To decide what the app behavior is when the link is clicked:

Get from the marketer: The expected behavior of the link when it is clicked.

Planning method input

When the onDeepLinking method is called by the AppsFlyer SDK, it gets a deep link object as an input.

The input object is described in the onDeepLink API reference.

The marketer and developers need to plan the deep_link_value (and possible other parameters and values) together based on the desired app behavior when the link is clicked.

To plan the deep_link_value, and other parameter names and values based on the expected link behavior:

  1. Tell the marketer what parameters and values are needed in order to implement the desired app behavior.
  2. Decide on naming conventions for the deep_link_value and other parameters and values.
    Note: Custom parameters will not appear in raw data collected in AppsFlyer.

📘

Tip

The marketer and developers need to decide together on the best long term system for the deep_link_value (and any other parameters/values) to minimize additional app updates.

The deep_link_value can be based on a SKU, post ID, path, or anything else. We strongly recommend agreeing with your developers on a system that allows for you to enter dynamic values on your chosen parameter, so you can generate many different deep links that go to different content within the app, without any further changes to the app code by the developers.

See the following URL examples. The deep_link_value of a fruit type was chosen by the marketer and developer together. And the developers made the values dynamic, so the marketer could enter any fruit without the need for further work by the dev team.

https://onelink-sample-app.onelink.me/H5hv?pid=Email&c=fruit_of_the_month**&deep_link_value=apples**...
https://onelink-sample-app.onelink.me/H5hv?pid=Email&c=fruit_of_the_month**&deep_link_value=bananas**...
https://onelink-sample-app.onelink.me/H5hv?pid=Email&c=fruit_of_the_month**&deep_link_value=peaches**...

Implementing onDeepLinking() logic

The Android App Links (for deep linking) and the deferred deep link both trigger the SDK. The SDK triggers the onDeepLinking method, that passes the deep link result object to the user. The deep link result object carries an error-handling code, and the deep_link_value and other parameters that implement the specific user experience when the application is opened.

To implement the logic:

  1. Implement the logic based on the chosen parameters and values. See the following code example.
  2. Once completed, send confirmation to the marketer that the app behaves accordingly.

📘

Sample code

appsflyer.subscribeForDeepLink(new DeepLinkListener(){
    @Override
    public void onDeepLinking(@NonNull DeepLinkResult deepLinkResult) {
        DeepLinkResult.Error dlError = deepLinkResult.getError();
        if (dlError != null) {
            // You can add error handling code here
            Log.d(LOG_TAG, "There was an error getting Deep Link data");
            return;
        }
        DeepLink deepLinkObj = deepLinkResult.getDeepLink();
        try {
            Log.d(LOG_TAG, "The DeepLink data is: " + deepLinkObj.toString());
        } catch (Exception e) {
            Log.d(LOG_TAG, "DeepLink data came back null");
            return;
        }
        // An example for using is_deferred
        if (deepLinkObj.isDeferred()) {
            Log.d(LOG_TAG, "This is a deferred deep link");
        } else {
            Log.d(LOG_TAG, "This is a direct deep link");
        }
        // An example for using a generic getter
        String fruitName = "";
        try {
            fruitName = deepLinkObj.getStringValue("deep_link_value");
            Log.d(LOG_TAG, "The DeepLink will route to: " + fruitName);
        } catch (Exception e) {
            Log.d(LOG_TAG, "Custom param fruit_name was not found in DeepLink data");
            return;
        }
        goToFruit(fruitName, deepLinkObj);
    }
});
private void goToFruit(String fruitName, DeepLink dlData) {
    String fruitClassName = fruitName.concat("Activity");
    try {
        Class fruitClass = Class.forName(this.getPackageName().concat(".").concat(fruitClassName));
        Log.d(LOG_TAG, "Looking for class " + fruitClass);
        Intent intent = new Intent(getApplicationContext(), fruitClass);
        if (dlData != null) {
            // TODO - make DeepLink Parcelable
            String objToStr = new Gson().toJson(dlData);
            intent.putExtra(DL_ATTRS, objToStr);
        }
        intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        startActivity(intent);
    } catch (ClassNotFoundException e) {
        Log.d(LOG_TAG, "Deep linking failed looking for " + fruitName);
        e.printStackTrace();
    }
}

⇲ Github links: Java

📘

Calling start() in activity vs application class

You can call start() either in the activity class or application class.

However, if you call start() to initialize the AppsFlyer SDK in the activity class (instead of the application class):

  • If subscribed for a deep link listener, when the app launches, both deep linking and deferred deep linking work.
  • If not subscribed for a deep link listener, only deep linking works; deferred deep linking does not work.

📘

Note

onDeepLinking is not called when the app is running in the background and Application LaunchMode is not standard.

To correct this, call setIntent(intent) method to set the intent value inside the overridden method onNewIntent if the application is using a non-standard LaunchMode.

import android.content.Intent;
...
...
...
@Override
protected void onNewIntent(Intent intent) 
{ 
  super.onNewIntent(intent);     
  setIntent(intent);
}

Updated 6 days ago


Unified deep linking


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.