- OneLink™, a unique attribution link solution that lets advertisers utilize three primary features with a single click:
- Device Detection and Redirection: OneLink detects the device type (Android, iOS, desktop, etc.) when clicked and redirects the user to a matching destination.
- Deep Linking: Where the advertised mobile app is already installed, OneLink supports app launch after the click and/or serves the user with personalized content such as sending the user to a specific activity/page in the app).
- Deferred Deep Linking: Where the advertised mobile app is not installed, OneLink can serve the user with personalized content such as sending the user to a specific activity/page in the app, on first launch of the app after install.
- Advertisers typically deploy OneLink with:
- Their owned media, such as email, SMS campaigns, website banners, landing pages, viral posts on social media, and QR codes on physical poster.
- Brand OneLinks with your domain.
Implment Branded Links
This guide covers OneLink basic setup, which enables device detection and redirection.
Once this basic setup is complete you can continue to the step-by-step Deep Linking Guide.
Example
AwesomeCom has released a new app for Android and iOS. Jill, the mobile marketer, decides to launch an SMS campaign using AwesomeCom's users mobile phone numbers database. The short message contains a call to action and a single OneLink URL.
All Android users clicking the link are redirected to the app's page on Google Play. All iOS users clicking the same link are redirected to the app's page on iTunes.
The campaign manages to convert 23.5% of AwesomeCom's registered users to mobile users using OneLink!
Device detection and redirection flow
When you use an engaged device, and click on a OneLink the following occurs:
- You are redirected to AppsFlyer's servers
- There, your click URL and its parameters are saved for later, for attribution and deep linking purposes, should you choose to install the app
- Immediately afterwards, based on the user agent of the device, the device type is detected
- You are then redirected to the designated destination according to OneLink's template (see below), which fits your device type
There are two stages required for OneLink's set up to achieve these steps:
Note
OneLink also supports the following platforms:
- Android - Android based Smart TVs
- Apple - Apple TV (tvOS)
- Amazon Fire TV - for Amazon Fire TV use the Custom Android APK URL option
- Windows - All Universal Windows Platforms including Xbox
OneLink template setup
The OneLink template is where all the different destinations per device types are defined.
Once the basic OneLink template setup is complete, you can create many custom links with different parameters, that lead to the same destinations stated in the OneLink template (except if overridden).
Each mobile app under an AppsFlyer account can be defined in multiple OneLink templates. For details on assigning an app to more than one OneLink template go here.
Important!
Although it is possible to define a mobile app in multiple OneLink templates, in most cases there is no need for it. Generally, an app should only be set up ONCE in the OneLink template.
Use this setup to create many custom attribution links that have different attributes, but lead to the same destinations.
OneLink templates list
The OneLinks templates list page is at account level, meaning it is common between all apps and contains all the OneLink templates of the account.
- From the dashboard of any of your apps, under the Engagement & Deep Linking section, click OneLink templates to open the page:
- Each OneLink template has its own unique OneLink template ID (provided the OneLink subdomain is defined): http://myapp.onelink.me/onelinkid.
Each OneLink also has its own custom name. - For a new OneLink template click
. - To work on an existing OneLink template click the respective Template name.
Note
If needed, you can delete a OneLink template. However, attribution links based on deleted templates lose their ability to attribute users and even to redirect them to the app stores.
Therefore, it's recommended not to delete OneLink templates, that have been used by attribution links. Instead, you can edit the OneLink templates to fit your needs.
After selecting an existing OneLink template, or adding a new one, the OneLink template page opens.
OneLink template page
From here you can set the destinations for iOS, Android and Windows phone devices. In addition, there are some more advanced destinations you can set. The following explains each of these options.
OneLink template name
Set a meaningful name for the participating apps in the template. If you don't set the name, the default name "Untitled OneLink" is generated for the template.
You can change the OneLink name at any time.
Subdomain
Required for deep linking mobile users, but not for basic redirection.
Subdomain is mandatory for deep linking of iOS Universal Links or Android App Links users.
URI scheme
Required for deep linking mobile users, but not for basic redirection.
- Mandatory for deep linking of Android users below 6.0, and for iOS 9.0 users and below.
- Mandatory for Android 6.0 users and above, if Android App Links is not implemented.
- The URI scheme serves as default value for OneLink URLs using this template, but can be customized per OneLink URL.
Note
- The value for Subdomain cannot include a '.':
- myapp - is valid.
- my.app - is not valid
- The value for URI Scheme must follow a specific pattern: URL Scheme should consist of a sequence of characters beginning with a letter and followed by any combination of letters, digits, plus ("+"), period ("."), or hyphen ("-").
- my-app:// - is valid.
- my_app:// - is not valid.
iOS setup
- Your iOS app - use the dropdown menu to select the iOS app you want the user to be redirected to in the App Store.
- Landing Page URL (optional) - use it only to redirect iOS users to a destination different from the App Store (know more about recording mobile installs from landing pages).
- Deep linking with Universal Links - switch toggle on ONLY to enable deep linking options for iOS.
The following fields appear if toggle is switched on. - Team ID (AKA App ID prefix) - Application-identifier key in your app's entitlements. You can find it in Apple Developer Portal.
- Additional iOS apps (optional) - If you are using a test app to develop your iOS app, you can test it using OneLink. Fill up the values for Team ID and for iOS App Bundle ID, as defined on XCode.
Note
Both values are found on developers.apple.com in the Identifiers >> App IDs section. Click the corresponding registered App ID as shown below.
- iPad app version (optional) - If you have a separate iPad app version, select it in the iPad dropdown menu, to redirect iPad users to it. Fill up the values for Team ID and for iOS App Bundle ID, as defined on XCode.
Android setup
- Your Android app - use the dropdown menu to select the Android app you want the user to be redirected to in Google Play.
- Landing Page URL (optional) - use this link for your Android app, if it is out of Google Play, Android users are redirected to this link.
- Deep linking with Android App Links - Android App Links is an advanced method for performing deep linking on Android devices from Android OS version 6.0 and above. Switch toggle on ONLY to enable deep linking with Android App Links for Android.
- When to define Android App Links in the OneLink template note - see capture above.
- Add SHA256 fingerprint - Click the button and add the SHA256 fingerprint that you got earlier (instructions on how to get it here).
- Make sure the Subdomain value is set.
- Copy the <intent-filter> XML snippet below Add SHA256 Fingerprint and save it on the side. The developer needs this XML snippet for step 2 of their part of the set up.
- In your app's AndroidManifest.xml file, add the <intent-filter> XML snippet to any activity that you want to deep link into.
Desktop web setup
This optional field enables you to redirect desktop users to a specific web page.
- If not specified, desktop users who click on OneLink URLs using this template, are redirected to the app page in iOS App Store.
- If the template doesn't contain an iOS app, users are redirected to the app's page in Google Play.
Amazon Kindle Fire setup
To enable attribution for Amazon Fire apps:
- Switch on Amazon Kindle Fire setup toggle.
- Set the Amazon Store ASIN or app page URL.
Windows Phone app
To enable attribution for Windows Phone apps:
- Switch on Windows Phone setup toggle.
- Select Your Windows Phone app.
- Landing Page URL (optional) - use it only to redirect Windows Phone users to a destination different from the Windows Phone App Store (know more about recording mobile installs from landing pages).
Creating custom links from the OneLink template
Now that your OneLink template is ready, you can create parameter-rich attribution links using it. These attribution links can differ by values such as the media source and campaign names (e.g. emails, website, banners etc.), but the basic OneLink redirections are common for all links (except if you override them).
You can create OneLink attribution links manually using the custom attribution links setup window. For details click here.
Alternately, if you want to automatically create OneLink attribution links or by bulk, you can do this using the OneLink REST API.
Testing OneLink's redirections
To test your newly-configured OneLink template follow these instructions:
1. Create a Multi-platform 'test' custom attribution link
2. Select the OneLink template the attribution link is intended for
3. Fill in the media source and campaign names. You can create different links for any type of tests you run. However, AppsFlyer recommends using the test media source name for all of them
Tip
Always prefer using test media source (&pid=test) when you test anything with AppsFlyer, to see all test results under the test media source. Add the test type under the campaign name parameter (&c={test type}, e.g. &c=redirections) to distinguish between different test types with the campaign name parameter.
4. Generate the attribution link and use either the long or short URL for testing
Example:
https://go.onelink.me/{AUTO_GENERATED}?pid=test&c=redirections
5. For every OS version configured in the OneLink template page:
- Send the test URL - To the respective whitelisted device using email, QR code etc.
Note
In iOS, use iMessenger or email to send the link to the device. Don't paste the link in the iOS Notes app and then click on it because it might break the link.
- Click on the test URL - Verify the device is redirected to the configured destination (Google Play, iTunes, web page etc.)
- Install the mobile app - On the device and launch it
- Check results - On the dashboard's overview page look for a new click and install under 'test' media source and the campaign name you put in the URL (e.g. redirections)
Warning
Completing the above tests successfully means your app is ready for performing OneLink redirections only. For deep linking tests click here.
Overriding OneLink's template destinations
Although OneLink's template-configured redirections are common for all attribution links that use it, you can override them with custom parameters. Placing the following destination parameters on the attribution link sends clicking users to the values stated in the link instead of the template's configured values.
Destination parameters
| Destination Parameter Name | Description | AppsFlyer's Tip |
|---|---|---|
| af_ios_url | Redirect iOS users to a different URL than the app's page on iTunes | Use this for landing page redirections, or as fallback in case deep linking fails. Note - Mac desktop users, with Safari 13.0.0 and above, are redirected according the af_ios_url, and not according to af_web_dp. |
| af_android_url | Redirect Android users to a different URL than the app's page on Google Play | Use this for landing page redirections, or as fallback in case deep linking fails. |
| af_r | Redirect users to the specified URL on all operating systems and platforms | Use this for landing page redirections. |
| af_web_dp | Redirect desktop users to a different web page than configured in the OneLink template |
Use this to keep attribution data of desktop users on other platforms (e.g. Google Analytics or Omniture).
Note - Mac desktop users, with Safari 13.0.0 and above, are redirected according the af_ios_url, and not according to af_web_dp. |
| af_dp | The path for an internal activity in the app that users are deep linked into | Use this for deep linking and retargeting. |
| af_ios_fallback | Supply fallback URL for users of iOS 10.3 and above | Use this to improve the broken flow for iOS 10.3 users. |
| af_param_forwarding | When set to false, none of the parameters that are on the OneLink pass to the redirected page | Use this for a cleaner looking URL in the redirected page, or if OneLink parameters might cause issues due to query parameter handling on the redirected page. |
Warning
Do not use any of the following characters as part of the destination parameter values (not even URL-encoded). Using them blocks OneLink's redirection or deep linking actions.
The characters are: []<>;(){}'`"
Example
Android users that click the following example link are redirected to google.com rather than the preconfigured android app page on Google Play. Clicking iOS users are redirected to apple.com:
https://go.onelink.me/{AUTO_GENERATED}pid=test&c=redirections&
af_android_url=http%3A%2F%2Fwww.google.com&
af_ios_url=http%3A%2F%2Fwww.apple.com
OneLink & social apps
Advertisers may want to use OneLink with "viral" posts on social apps, as potential users that are exposed to such posts cannot be targeted in advance according to their devices.
Unfortunately, limitations set mainly by Apple's Universal Links, in conjunction with restrictions of some of the social apps, complicate the use of OneLink for deep linking, or even sometimes for basic device recognition, redirection and attribution.
The following table summarizes what you can do with OneLink in today’s popular social apps:
| Social App | Android Redirection | Android Deep Linking | iOS Redirection | iOS Deep Linking |
|---|---|---|---|---|
| Y | Y* | Y | Y* | |
| Facebook Messenger | Y | Y* | Y | Y* |
| Snapchat | Y | Y* | Y | Y* |
| Y | Y | Y | N | |
| N | N | N | N | |
| Slack | Y | Y* | Y | Y* |
| Y | Y* | Y | Y* | |
| Y (See WeChat FAQ) |
N | N | N | |
| Y | Y | Y | Y |
Y* - if URI scheme is used instead of App or Universal link, or if you set a landing page.
The landing page workaround for social apps
To avoid the aforementioned OneLink limitations, and still enable device redirection on social apps' posts, we recommend using the social app landing page.
Alternatively, you can create your own landing page. The flow is as follows:
- Create a landing page with a "Download app" button, with OneLink behind it
- Post the link to the landing page on the social app
- A User clicks on the landing page link inside the post on the social app
- The user is redirected to a landing page
- Landing page contains a "Download app" button, with OneLink behind it. User clicks the button
- The regular OneLink flow follows including deep linking and attribution using fingerprinting
Note
The conversion rates for landing pages may be a bit lower than the original sources, due to the second click required from the users.
To learn more about attributing mobile users coming from Facebook to landing pages go here.
For performing deep linking from social media posts with OneLink go to the deep linking guide.
Using OneLink with integrated networks
OneLink is mainly used with owned media, and not with ad networks.
It is rare for ad networks to require OneLink since they usually advertise on apps. This enables them to know the user's platform, device ID etc., so their app and platform-specific attribution links suffice.
However, sometimes ad networks don't know their users' platform in advance, for example when they run email or SMS campaigns themselves.
Important!
OneLink with integrated networks requires you to use the long version of OneLink.
OneLink setup with integrated networks
- Go to Integrated Partners on your Android app's dashboard and select the relevant ad network.
- Copy the app's attribution link from the setup window and save it to an external document.
- For your iOS app, repeat steps 1+2.
Now build the attribution link:
- Make sure OneLink is properly set up
- Create a basic OneLink URL in the Custom Attribution Link window and save it to an external document. When you create the basic OneLink URL, use "test" as the media source name:
- After you click Generate Link, you see the following screen:
- Copy the long link.
- In the long link, Replace the "test" media source with the exact PID of the integrated partner to the link https://greatapp.onelink.me/U8ru?pid=network_int&c=MyCampaign
- Add ALL parameters from BOTH attribution links
If the attribution link of the iOS and Android app are identical, simply copy the parameters from either one of the links. Otherwise, make sure you have all the parameters from both links.
If all the integrated network parameters are added correctly, once OneLink is clicked and redirected to the right platform, the required parameters are sent to the network within a postback after the user installs.
Example
https://greatapp.onelink.me/3287867539?pid=network_int&c=email&
idfa{$IDFA}&gaid={$GAID}&clickid=$SITEID&
af_sub1=[pixel_code]&af_sub2=[creative]
The network uses either the IDFA or GAID parameters according to the client's device platform and disregards the other parameter.
FAQ
Yes, using target="_blank" in the HTML href tag does not result in redirecting to Google Play or App Store. If OneLink URL is placed inside an html a tag with target="_blank" attribute, it opens a blank page in Chrome on Android and iOS. This affects OneLink functionality. Make sure that the a tag doesn't include the target attribute.
Yes, there are several Instagram limitations:
- Due to the way Instagram renders the text of a page post, links do not become clickable when entered into a post caption.
- Instagram profile descriptions do not support clickable links.
- Linking from profile website links is possible, however it directs to the App Store all the time since Universal Links are not supported in Instagram (iOS only).
To overcome this, OneLink can recognize clicks in WeChat and loads a dedicated landing page instructing the user to click the options button and then to click Open in Browser. This opens the redirect URL defined in the OneLink template setup.
If the user’s WeChat language is registered as Chinese, OneLink generates a localized version of the landing page:
