At a glance: Set up OneLink Smart Script to convert and attribute your mobile website visitors, coming from any source, into mobile app users.
Related reading
For a complete picture of working with Smart Banners, check out these articles:
- OneLink Smart Script overview
- OneLink Smart Script V2 setup [this article]
- OneLink Smart Script V1 (legacy) setup
- Mobile web-to-app attribution solutions
Setup
There are two versions of OneLink Smart Script:
OneLink Smart Script V2 (recommended): If you are setting up OneLink Smart Script for the first time, this is the preferred version to use. The developer work portion is easier, and it can also be set up using Google Tag Manager. See developer instructions
OneLink Smart Script V1 (legacy): If you already have Onelink Smart Script set up, use the documentation for this version to maintain and edit this script. Note: Although not mandatory, consider migrating to V2.
Note
Click the Follow button in the article header, to get informed when there is an update to the article or script.
Set up OneLink Smart Script
To set up the Smart Script, you can either:
- Embed the script in your website.
- Use Google Tag Manager.
Who's involved
|
Prerequisites
|
To embed the script on the web page:
- Decide what parameters and values the automatically-generated outgoing OneLink URL should contain. See the arguments you can use.
- Make sure that all campaigns with incoming URLs have parameters that the script works for (for example, can place as the media source parameter in the outgoing URL).
- For each parameter, you must enter a configuration object that can contain keys, override values, and a default value.
- Provide the arguments to the web developer.
- Tell the developer to follow the dev instructions and implement the script so the correct outgoing link is generated.
Who's involved
|
Prerequisites
|
To implement the script on the web page:
- In Google Tag Manager, create a new tag.
- Name the tag, click Tag Configuration, and select Custom HTML.
- In the HTML box:
- Paste the OneLink Smart Script code.
- After the Smart Script code, add the Smart Script initialization code with your arguments and configuration objects. See sample initialization code.
- Replace the following line of code:
with this:var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
AF_SMART_SCRIPT_RESULT = window.AF_SMART_SCRIPT.generateOneLinkURL({
- [Optional] If you want to display a QR code instead of a button with a URL behind it, in the code, after:
var result_url = result.clickURL;
enter:
if (result_url) {
document.getElementById('output_url').innerHTML = result_url;
window.AF_SMART_SCRIPT.displayQrCode("my_qr_code_div_id");
- Wrap everything inside a
<script></script>
tag. - Click Triggering and create a new trigger by clicking on the plus icon at the top right-hand corner of the screen.
- Name the trigger, and choose a Trigger Configuration and define the conditions to trigger the tag (for example, all page views). See GTM documentation to learn more
- Click Save in the top right-hand corner.
- Tell the developer to follow their OneLink Smart Script for GTM instructions.
Configuration object
The OneLink Smart Script uses arguments to generate an outgoing URL based on the parameters of the incoming URL and the arguments defined in the script. The afParameters argument has a structure made up of several other arguments (parameters) used for attribution and deep linking, each of which contains a configuration object that has keys, override values, and a default value, as described in the table that follows.
Argument | Description | Example |
---|---|---|
keys |
|
|
overrideValues |
|
Example: {'video': 'video_new'} For the channel parameter in the script, anytime the incoming value is video, the script changes it to video_new on the outgoing link. |
defaultValue |
|
Example: ['web_video'] For the channel parameter in the script, if you have the param in_channel is not found, web_video is used as the channel value. |
Arguments
The OneLink Smart Script uses arguments to generate an outgoing URL based on the parameters of the incoming URL and the arguments defined in the script.
Argument | Remarks | Record your responses (for the developer to use) | |
---|---|---|---|
oneLinkURL (required) |
|
||
afParameters (required)
|
mediaSource (required) |
|
Keys: Override values: Default value: |
campaign |
|
Keys: Override values: Default value: |
|
channel |
|
Keys: Override values: Default value: |
|
ad |
|
Keys: Override values: Default value: |
|
adSet |
|
Keys: Override values: Default value: |
|
deepLinkValue |
|
|
|
afSub1-5 |
Configuration object for af_sub[1-5]. |
Keys: Override values: Default value: |
|
googleClickIdKey |
State what to call the parameter that carries the GCLID. |
||
Other (custom) query parameters |
|
Param key: Keys: Override values: Default value: |
|
referrerSkipList |
List of the strings in the HTTP referrer for a particular click (for example Twitter or Facebook) that if found, cause the Smart Script to return |
||
urlSkipList |
List of the strings in the URL for a particular click (for example af_r) that if found, cause the Smart Script to return |
Use cases
The following sections provide Smart Script use cases for some common campaign/media source scenarios.
UTM parameters
To set up the script for UTM parameters:
- Make a list of UTM parameters on the incoming URL (for example: utm_source and utm_campaign)and match them to the parameters for the outgoing URL (for example: media_source and campaign).
- Provide these in the list of arguments to the web developer.
Result: The values in the incoming parameters (utm_source and utm_campaign) are used to populate the values of the (media_source and campaign) parameters in the outgoing link.
Google Ads GCLID
The usual process for install attribution of Google Ads campaigns (which carry a GCLID parameter) requires users who click your ad to be redirected to the app's store page URL.
Since in this case, you are redirecting leads from Google Ads to a web/landing page, the script takes the GCLID parameter from the Google Ads install campaign URL and puts it into the outgoing URL in your choice of output parameter af_sub[1-5].
Note!
- This applies to install campaigns. For non-ACI search campaigns, meaning re-engagement campaigns, Google may be attributed as the media source, despite the Smart Script output.
- If a GCLID is found, the script looks for the incoming parameter keyword. If found, it puts the keyword value in the outgoing URL as the value of af_keywords.
Prerequisite: On the Google dashboard, enable auto-tagging.
With auto-tagging enabled, the URL contains the GCLID parameter.
To set up the script for Google Ads GCLID:
- Select a parameter in the outgoing URL to contain the GCLID.
Best practice: Select af_sub[1-5], so that the data displays in AppsFlyer raw data reports. - Provide this in the list of arguments to the web developer.
Result: In the outgoing URL, the GCLID is the value of the af_sub[1-5] param.
To notify Google Ads about these installs:
- Get the GCLID data from the param af_sub[1-5] via CSV, or Push API in real-time for every install.
- Upload the GCLID data to Google either manually or via Google Ads API.
Note
This GCLID solution is not officially supported or recommended by Google. In case Google deprecates the GCLID parameter we will change the script to support the changes. Follow this article, by clicking the Follow button in the article header, to get informed when there is an update to the article or attached script.
Facebook click ID
Facebook Ads carry click IDs. If you want this ID to be available in AppsFlyer raw data, take the Facebook click ID and put it into the outgoing URL in your choice of output parameter af_sub[1-5].
To set up the script for Facebook click ID:
- Select a parameter in the outgoing URL to contain the Facebook click ID.
Best practice: Select af_sub[1-5], so that the data displays in AppsFlyer raw data reports. - Provide this in the list of arguments to the web developer.
Result: In the outgoing URL, the Facebook click ID is the value of the af_sub[1-5] param.
SRNs, owned media, and other media source links
SRNs like Snapchat or Twitter, work differently than Google Ads or a cross-platform like Facebook. Campaigns from these SRNs lead your users to the web/landing page, and you are billed according to clicking leads, unrelated to any derived mobile users.
For these SRNs, script setup is the same as for links from owned media, or other media sources you might use.
To set up the script:
- Make a list of the media source and campaign parameter names that are in the incoming links.
- Provide these in the list of arguments to the web developer.
The SRN/media source type should be the media source value in the incoming URL, and the script finds it and uses it as the media_source value in the outgoing OneLink URL behind the download button on the web/landing page. If you want to change the outgoing media_source, provide the incoming media source value and the override media_source value in the list of arguments you give to the web developer.
Result: For these SRNs/media sources, the values in the media source and campaign parameters in the incoming link are used to populate the values for the media_source and campaign parameters in the outgoing link.
Example
Incoming URL: https://hotel.me/incoming_mediasource=twitter&incoming_campaign=big_social
Outgoing URL: https://hotel.onelink.me/Ac4G?pid=twitter&c=big_social
AppsFlyer attribution links
AppsFlyer attribution links can be used when the media source is a click ad network. When you set up such a link in AppsFlyer, you have the option to add a Redirection URL path (af_r) parameter with the desired URL path to your mobile website for web campaign-to-app attribution. You may not want the Script to create an outgoing OneLink URL, as then, some of the data from the original click may be lost.
Action: Use the urlSkipList argument to list the af_r parameter.
Result: When the Smart Script finds the af_r parameter on the incoming link, the Smart Script doesn't produce an outgoing URL and the developer must decide what link to place as the outgoing URL and implement it.
Example
Incoming URL: https://app.appsflyer.com/id123456789?pid=click_ad_network_int&c=orlando&af_r=hotel.me
Outgoing URL: No outgoing URL.
Desktop
Most use cases in this article are of users coming from mobile devices. Therefore, when directed from the mobile website to an app store, they can immediately download your app.
However, desktop users shouldn't immediately be sent to an app store, because their device (a desktop or laptop) isn't compatible with mobile app downloads.
To set up the script for desktop users:
- In your OneLink template, set a destination URL for When link is clicked on desktop. The URL should redirect to a dedicated web/landing page. The landing page can contain a web form where they fill in their details to get an SMS or an email with a link to download the app. It's up to you to create the web form and provide the URL to it in the script.
Result: The script detects the device or platform the user is on. If it's desktop, the script generates an outgoing OneLink URL that redirects the user to your dedicated web/landing page.
See also Desktop-to-app conversion.
Agencies
Installs are attributed to agencies using the af_prt parameter.
To add this attribution parameter using the OneLink Smart Script, tell your developer to follow these instructions.
Result: The script detects the additional parameter in the incoming URL with the agency name and adds the af_prt parameter to the outgoing URL.
Example
Incoming URL: https://hotel.me/incoming_campaign=gogo&incoming_media_source=email&partner_name=bigagency
Outgoing URL: https://hotel.me/pid=email&c=gogo&af_prt=agency
QR codes
Smart Script displays a QR code on your web page, instead of a button with a link behind it.
To display a QR code:
- Make sure you use Smart Script 2.1+ when you set up your Smart Script.
- Tell your developer to follow their instructions to create a QR code with the Smart Script result.
- Best practice: Tell the developer to show the QR code when users are on desktop and to show the button with the link when users are on mobile.
Result: The script displays a QR code instead of a button with a URL behind it. Note: QR codes created via the Smart Script can't be customized.
Example
Incoming URL:
https://hotel.me/qr_code.html?incmp=gogo&inmedia=email
Outgoing URL:
https://hotel.onelink.me/LtRd/?af_js_web=true&af_ss_ver=2_1_0&pid=email&c=gogo
Outgoing QR code:
Impressions
The OneLink Smart Script can be used to count impressions on your website. To do so, the developer needs to call the impression function. Installs are then attributed to the impressions via view-through attribution.
Note:
- Counting impressions is in addition to the normal Smart Script-produced URL that counts clicks. Smart Script can be used to count clicks, impressions, or both.
- View-through attribution via Smart Script only works on mobile devices; not on desktop.
To attribute new installs to these impressions (which is view-through attribution):
- Make sure you use Smart Script 2.2+ when you set up your Smart Script.
- Tell your developer to call the impression function in the Smart Script.
- Make sure view-through attribution is turned on.
- [Optional] If you wish to change the default 1-day view-through lookback window value, you or your developer needs to add the af_viewthrough_lookback parameter with the new value. For example, af_viewthrough_lookback=1d.
Comments
Please sign in to leave a comment.