At a glance: Create a link that sends new users who don't have your app to the relevant store or web page, depending on their platform. If the AppsFlyer SDK is installed on your app, the users are attributed to the correct source—including to your owned media, such as banners, emails, SMS campaigns, or QR codes on posters.
 |
 |
 |
 |
Scope of work
|
Who's involved Only the marketer is required. If the AppsFlyer SDK is already installed, you can complete this guide entirely using the AppsFlyer dashboard, without a developer making any changes to your app's code. |
|
Prerequisites
|
|
Time required Approximately 30 minutes |
|
Outcome
|
Example
Mark is the marketer of a successful grocery delivery service called "Feed Me". Mark targets his user-base phone numbers to download Feed Me's new mobile iOS and Android apps. An SMS campaign is planned, targeting registered users who have not yet installed the app. However, Mark doesn't know which users have Android or iOS devices.
To solve this, Mark sends the SMS containing a short URL powered by OneLink. When a user receives the SMS and clicks the link, it automatically directs them to the appropriate app store or landing page, where it's easy for them to install the app.
These new installs are attributed to the SMS campaign, enabling Mark to check the success of the SMS campaign in AppsFlyer.
Procedures
Complete the following procedures to set up a custom link that:
- Directs users to the correct app store or web page based on their device.
- Attributes the click/install to your owned media source.
1. Creating a OneLink template
A OneLink template represents the routing logic at the core of your links. A OneLink template is not a clickable link for your end-users; it is the foundation for generating many custom links. A OneLink template is where you record your decisions on how to redirect users, based on their platform, and on whether they have your app installed.
A single OneLink template can be the basis for creating many links, as we'll see later in this guide. It is rare to need more than one or two OneLink templates in the lifetime of an app (outside of testing).
To create a OneLink template:
- In the AppsFlyer dashboard, go to Engagement & deep linking > OneLink Custom Links.
OneLink is an account-level feature, which lets you create OneLink templates and their custom links for all your apps. - In the top left corner of the page, click on Add OneLink template.
The OneLink template setup page opens.
- In the OneLink template name field, enter a name.
Note
- A good OneLink template name includes the name of the app (for example feed_me) or the use case or experience represented by the OneLink (for example pre_launch_landing_page).
- The name should not include the campaign or channel name or media source (since this isn't the actual end-user link, just the underlying template to create many links), or the name of the platform (Android, iOS, since multiple platforms are usually the reason for using a OneLink template in the first place).
- This template name is only used internally. It doesn't affect your marketing attribution data and is not seen by users.
- In the Subdomain field, enter your subdomain name.
- Choose a subdomain that matches your brand. For example, if your website is www.acme.com choose acme as your subdomain.
- Only use lower-case letters, digits, or hyphen (-).
- OneLink also supports fully branded links. Learn more
-
Select your Android app, iOS app, or both. This takes care of redirecting clicking users without your app to the correct app store.
- [optional] Change to a different URL: In some cases, you may prefer to take new users to a mobile web experience instead of directly to the app store (or your app may not be listed in the store). To implement, enter that URL in the URL field.
- If you've selected an Android app and an iOS app, the template is configured to send new and existing users to their respective destinations.
- If you've selected only one app, Android or iOS, the template is configured to send ALL users (iOS and Android, new and existing) to the single defined destination.
- Skip When app is installed. This is discussed in the next guide.
- [optional] Change destination for When link is clicked on desktop.
- In some cases, your link might be clicked on a desktop computer, especially if it is sent via email or social media. If you expect a lot of desktop traffic to your link, you might want to send those users to a landing page or the main website homepage, or a page where they can request an SMS link on their phone, instead of the relevant app store.
- By default, desktop users are redirected to your app's iOS App Store page, or to Google Play's app page, If an iOS app isn't defined.
- [optional] Select apps from other platforms
If you have a dedicated app version for the following:- Windows phone - activate toggle and select app or Change to a different URL.
- iPad - activate toggle and select iPad app
- Amazon Kindle Fire - activate toggle and add Amazon store ASIN or app page URL.
- Click Save OneLink template (Update OneLink template for edited templates).
Your OneLink template is now created and can be used to create many different clickable links (see the following section).
2. Creating a custom attribution link for users
The OneLink template is ready! Now it's time to add a custom link to attribute users to an owned media campaign. Setup the custom link to get the URL to share with your users.
To create a custom link based on the OneLink template:
- In the AppsFlyer dashboard, go to Engagement & deep linking > OneLink Custom Links.
- Select the OneLink template to add a custom link for.
- New template - Click Add custom link.
- Template with defined links - Click Add custom link or click on a Custom link name in the list to edit it.
The Custom link page opens.
- In the Short URL field, customize the short URL slug to be a specific value (for example, your brand), or leave the default value as it is.
- In the Attribution tab, you can select the parameters to attribute clicking users to a media source, campaign, channel, etc.
- Select a Campaign name (for example, summer 2020). This enables you to compare different campaigns under the same owned media source.
Note: For the purposes of getting started or testing your link, name the media source 'test' and name the campaign 'getting started guide'. - Click on one of the suggested Owned media sources (for example, SMS) or select Custom to set a different name. The selected name is the Media source name, under which all clicking users' data is collected. Read more about selecting a good custom media source name.
- Skip the Retargeting campaign toggle. We cover it in the following guide.
- Click Add parameter to add more attribution parameters, such as Ad set name, Ad name, Channel, your own custom parameters, or 1-5 Subscriber parameters. This enables a more granular analysis of your marketing efforts. Read more about the additional attribution parameters.
- [optional] Change the Click-through Lookback window value. Enable Customize lookback window to reveal the slider and set a Lookback window, 1-23 hours, or 1-30 days. If deactivated, the default value is 7 days.
- [optional] Set a fixed cost per install. Enable cost per install and select the currency and amount that each new install costs you. This enables you to see the ROAS of your owned media campaigns.
- Select a Campaign name (for example, summer 2020). This enables you to compare different campaigns under the same owned media source.
- Skip the Redirecting & deep linking and Social app landing page tabs.
They will become useful when we enable deep linking, in the next guide.
However, ONLY if you wish to redirect users to a different URL than the app page, you can do it in the Redirecting & deep linking tab by specifying custom Android and iOS URLs. Note! If your OneLink template already has a set value for a custom URL, these custom link URLs override it. - Click Generate Link.
A popup displays prompting you to name your link. - Enter a name for your custom link.
- Click Generate link.
A short URL and long URL are displayed, each with a corresponding QR code.
3. Testing
To test your link:
Prerequisites: A registered test device without the app.
- In the AppsFlyer dashboard, go to Engagement & deep linking > OneLink Custom Links.
- Hover over the Actions icon of the link you want to test and click Get URL.
- Send the short or long URL to your phone. You can either:
- Scan the QR code with your phone camera or QR scanner app.
- Email or WhatsApp yourself the link, and open it on your phone.
Note: Do not paste into iOS notes, or directly into a mobile browser. Often, the mobile operating system intentionally will not open the app in this context.
- Click the link on your mobile device.
Depending on your platform, it should take you to the app store or landing page.
Note: A real click on a mobile device is needed. Javascript or 301/302 redirects can't trigger Universal Links and Android App Links. Even basic redirections fail with these methods on some browsers. - Download and launch the app.
- In the AppsFlyer Overview dashboard look for a new organic install.
Look for a new click and install under media source (e.g. test) and the campaign name you put in the URL.
Link not behaving as expected? Check out our troubleshooting guide.
If you completed all three procedures in this article, then congratulations! You have created a link you can send to all new users who do not have your app and direct them to the correct app store.
The following sections contain various FAQs and general explanations about OneLink.
OneLink template FAQs
How to assign an app to multiple OneLink templates
You can use a single OneLink template to create a limitless number of OneLink URLs, however, in some cases, you might have to assign an app to more than one OneLink template.
For example, if you have multiple versions of an Android app for out-of-store markets, you may need a separate OneLink template per Android version, yet have the same iOS app assigned to all of them.
For each template to which you add an app (after the first template), complete the following instructions, according to the relevant deep linking method.
Android: URI scheme
No special actions required.
iOS: Universal links
For the new OneLink to work, the app's AASA file must be updated. After creating the new OneLink template, submit a new version to the store. Only iOS users who updated to the new version can activate a OneLink URL built on the new template.
Android: App links
- After creating the new OneLink template, copy the new OneLink ID generated for it.
- Copy the XML snippet at the bottom of the App Link section and add it to your AndroidManifest.xml file inside the intent you want to deep link into, in addition to the previous intent/s.
- Release the new version to the store. Only Android users who updated to the new version can activate a OneLink URL built on the new template.
Note
AppsFlyer accounts are limited to a maximum of 100 defined OneLink templates per account.
Can I delete a OneLink template?
Yes, it's possible to delete a OneLink template, but only by contacting your CSM.
Note: If there are OneLink URLs using the deleted template out there, clicking users would not even be redirected to the app store. Therefore, make sure there are no OneLink URLs using the template before deletion. Alternately, see if you can just change the template configuration.
Can an ad agency create a OneLink template?
No, agencies are not able to create OneLink templates on their own. However, agencies can use existing OneLink templates to create custom attribution links for them. This can be done if the agency is a partner of ALL the apps in the template.
Can I edit the subdomain in a OneLink template?
You can edit the subdomain in a OneLink template as long as there are not any custom links in AppsFlyer based on the template.
If you have already created custom links in AppsFlyer based on the OneLink Template, then editing the subdomain is not possible, due to the concern that there may already be live links in use and changing the subdomain breaks their redirection/deep linking behavior. To change the subdomain, you can either:
- Create a new OneLink template with the different subdomain, and create links based on it.
- Delete all custom links in AppsFlyer that you created based on the template. Once there are no links based on the template, the subdomain will become editable.
OneLink parameter FAQs
What can I use as a custom media source name?
Integrated Partner reserved pid values (ending with _int), cannot be used as media source values in Custom Attribution Links. Use the Integrated Partners setup to create partner-related attribution links. For more details, click here.
Do not use "Facebook," "Facebook Ads," "GoogleAdwords," "Twitter," or "Organic" as your custom media source name (case insensitive). Using these names for custom attribution links may affect attribution data integrity, as installs from your owned media would get attributed to integrated partners.
Additional attribution parameters
You can add further attribution parameters to enable you to perform a thorough drill-down analysis.
| Attribution parameter | Description | Parameter link name |
|---|---|---|
| Campaign | Add it to compare different campaigns within the owned media source | c |
| Adset | Set ad set names to compare different ad sets within specific campaigns of the media source | af_adset |
| Ad Name |
Set ad names to compare different creatives within specific ad sets/campaigns of the owned media source |
af_ad |
| Channel | Set channel names if you have more than one distribution channel for your owned media that you want to compare. For example, if you split SMS messages between two SMS service providers, specify on the channel parameter which provider it is. Later, you can compare conversion rates to decide on the better provider | af_channel |
| Subscriber Parameters | Use any of the 5 subscriber parameters to insert useful values. Note that these parameters get parsed and appear in the raw data report, which makes them useful for performing data aggregation or filtering | af_sub1, af_sub2, af_sub3, af_sub4, af_sub5 |
| Custom Parameters | Similar to subscriber parameters, you can use fields with any values and any names. However, these are not parsed and made available on the raw data reports; only as part of the full original URL |
Custom |
See more information about AppsFlyer Attribution Link Structure and Parameters.
Customized Lookback Window
Enabling the Customized Lookback Window button allows you to set the maximum click to install time. Installs (first launches) that take place within the lookback window are attributed to the media source. Installs that take place afterward, are attributed as Organic.
By default, the window is set to 7 days, but you may wish to set it otherwise in different cases.
Example
A regular 7-day lookback window for email campaigns is reasonable. However, if an email contains an attractive and memorable video, it makes sense to extend its lookback window to 14 days.
More details about click lookback windows here.
Cost per install
Enabling the Cost per install button allows you to apply a specific CPI value for each install coming from the link.
Select the cost currency and then a numeric ONLY value (float - up to 4 digits after the decimal point) representing the CPI.
Example
An SMS campaign costs $20 per 1000 messages (CPM). From your experience, these campaigns achieve a 5% conversion rate, meaning the derived CPI is $0.40. Setting the cost per install to 0.40 USD enables you to easily see the eventual ROI of the SMS campaign.
More details about measuring cost and ROI here.
Attribution link parameters: af_cost_currency, af_cost_value
Are parameter names case-sensitive?
Yes. When you set parameters on the attribution link, make sure that you use consistent naming. Do not use upper and lower case names intermittently.
If you don't keep the same case in parameter names, it might cause issues with viewing data in the dashboard and raw data.
For example, if you set pid=MyMediaSource on one attribution link and pid=mymediasource on another, discrepancies in data may occur. The same goes for any other param that you set on the attribution link. If you choose a case, upper or lower, make sure you always use it.
Preventing parameter forwarding on redirections
af_r, af_ios_url, af_android_url, and af_web_dp carry parameters from the attribution link or OneLink over to the redirected page. To prevent such parameters from being carried over to the redirected page, add af_param_forwarding=false to the attribution link.
Are single-platform custom links still available?
OneLink is now the only supported method for creating custom attribution links for owned media.
In the past, app owners could also use single-platform (app-specific) custom links without using OneLink. This method is deprecated, and new custom links can only be created based on a OneLink template.
However, if you have legacy single-platform custom links, they still work as always. You can also view and edit your legacy links, by clicking the View legacy single platform links link, on the top right corner of OneLink Custom Links page.
Custom impression URLs
Custom impression links enable you to:
- Measure the impressions to clicks conversion rates of your owned media.
- Receive attribution for clicks.
AppsFlyer detects the user's device platform and attributes the click to the correct source.
Prerequisites: A working Onelink custom link
Who is involved:
Marketer and web developer
To create impression URLs for measuring impressions only:
- In the AppsFlyer dashboard, go to Engagement & deep linking > OneLink Custom Links.
- Hover over the Actions icon of the link you want to test and click Get URL.
- Copy the OneLink's long URL for editing.
Example:https://go.onelink.me/j7rN?pid=email&c=Spring& - Replace 'go' (or your app's unique subdomain) with 'impressions'.
Example:https://impressions.onelink.me/j7rN?pid=email&c=Spring& - Copy the impression URL and send it to your developer.
- Instruct your web developer to implement the impression URL in the website logic.
Now you have an impression URL, that can be used to count impressions on your website pages but can't attribute new installs. For view-through attribution, follow the next steps.
To use impression URLs for attribution:
- Prepare the impression URL as described in the earlier steps.
- Add the visitor's device ID, IDFA (
idfa=) for iOS users and GAID (advertising_id=) for Android users.Note
- For iOS 14 devices, IDFA is not collected.
- If GAID isn't available for some reason include Android ID (
android_id=) on the link. If that isn't available use IMEI (imei=). - The Device ID values can be hashed for better security using SHA1. The parameter name should begin with "sha1_" and be followed by the parameter name and the hashed value, e.g., sha1_idfa, sha1_advertising_id, sha1_android_id and sha1_imei
- [Optional] If you wish to change the default 1-day view-through lookback window value, add the
af_viewthrough_lookbackparameter with the new value. For example,af_viewthrough_lookback=5d&. - Copy the impression URL and send it to your developer.
- Instruct your web developer to implement the impression URL in the website logic.
Full impression URL example:
https://impressions.onelink.me/j7rN?pid=email&c=Spring&af_viewthrough_lookback=5d&.shIntegrated partner FAQs
Using OneLink URLs in social apps (unpaid)
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, and sometimes even for basic device recognition, redirection and attribution.
The following table summarizes when OneLinks can be used in today’s popular social apps:
| Social app | Android users without app installed | Android deep linking | iOS users without app installed | iOS deep linking |
|---|---|---|---|---|
| Facebook (including boosted posts) | ✓ | ✓* | ✓ | ✓* |
| Facebook Messenger | ✓ | ✓* | ✓ | ✓* |
| Snapchat | ✓ | ✓* | ✓ | ✓* |
| ✓ | ✓ | ✓ | ✓* | |
| - | - | - | - | |
| Slack | ✓ | ✓* | ✓ | ✓* |
| ✓ | ✓* | ✓ | ✓* | |
| ✓† | ✓† | ✓* | ✓*† | |
| ✓ | ✓ | ✓ | ✓ | |
|
* If URI scheme, or a Social app landing page set up. ** User may be prompted to open the link in an external browser. |
||||
Using OneLink with integrated networks (paid)
OneLink is mainly used with owned media; 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 the users' platform in advance—for example, when they run email or SMS campaigns themselves.
Important!
OneLink with integrated networks requires you to use the OneLink long URL.
- 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.
In the Attribution section, use "test" as the media source name. - Click Generate Link.
The short and long URLs appear. - Copy the long URL.
- 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 the user is 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.
Are there any limitations on posting OneLink on Instagram?
Yes, there are a couple of 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.
- Linking from profile website links is possible. However, for iOS, you need URI scheme, or a Social landing page set up.
What is AppsFlyer's solution for Android OneLink redirections on WeChat?
To overcome this, OneLink can recognize clicks in WeChat and load 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:
Limitations
What are the limitations of OneLink URLs?
- Total URL length must not exceed 2000 characters
- Link Name and Media Source: must not exceed 100 characters
- The following special characters are not allowed in OneLink parameters or values: ;, *, !, @, #, ?, $, ^, :, &, ~, `, =, +, ’, >, <, /
- Short URL ID must not exceed 50 characters
Is there any limitation on posting OneLink on web pages?
Yes. Using target="_blank" in the HTML href tag does not result in redirection to Google Play or App Store. If the OneLink URL is placed inside an html a tag with the 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.
Next step
Follow the instructions in OneLink guide 2/4 to send existing app users who click your link directly to the app itself.