OneLink Smart Script V2 setup

At a glance: Set up OneLink Smart Script to convert and attribute your mobile website visitors, coming from any source, into mobile app users.

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.

Scope of work
Who's involved Advertiser: Decides what the outgoing URL should contain based on the configuration objects and arguments in the script that process the incoming URL. This determines the attribution and deep linking data that gets appended to the outgoing URL, either by manipulating the incoming URL or by forcing certain values. Makes sure all campaigns leading to the mobile website have incoming URLs with parameters that the script works for. Web developer: Embeds the script in the website or specific page/s. Configures the data to initialize the script and enters the arguments (parameters and values) necessary to generate the outgoing OneLink URLs based on the incoming URL parameters provided by the marketer. This includes mandatory and optional parameters.
Prerequisites An AppsFlyer account with at least one app. A OneLink template that serves as the value of the OneLinkURL parameter.

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.

Scope of work
Who's involved Advertiser: Disclaimer: Advertiser needs to know how to code in javascript to configure and initialize the script. Otherwise, a developer is required. Decides what the outgoing URL should contain based on the configuration objects and arguments in the script that process the incoming URL. This determines the attribution and deep linking data that gets appended to the outgoing URL, either by manipulating the incoming URL or by forcing certain values. Configures the data to initialize the script and enters the arguments (parameters and values) necessary to generate the outgoing OneLink URLs based on the incoming URL parameters provided by the marketer. This includes mandatory and optional parameters. This may require developer assistance. Enters the Smart Script code and initialization code in Google Tag Manager. Makes sure all campaigns leading to the mobile website have incoming URLs with parameters that the script works for. Web developer: Makes sure the initialization code returns a result and uses the result as needed. For example, to place it as a link under a CTA on your website.
Prerequisites An AppsFlyer account with at least one app. A Google Tag Manager account integrated with your website. A OneLink template that serves as the value of the OneLinkURL parameter.

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:
1. Paste the OneLink Smart Script code.
2. After the Smart Script code, add the Smart Script initialization code with your arguments and configuration objects. See sample initialization code.
3. Replace the following line of code:
```
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
```
  with this:
```
AF_SMART_SCRIPT_RESULT = window.AF_SMART_SCRIPT.generateOneLinkURL({
```
4. [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;
      if (result_url) {
            document.getElementById('output_url').innerHTML = result_url;
```
  enter:
```
window.AF_SMART_SCRIPT.displayQrCode("my_qr_code_div_id");
```
5. Wrap everything inside a <script></script> tag.
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.

Configuration object
Argument	Description	Example
keys	List of strings List of possible parameter/s in the incoming URL the script looks for, the value of which is placed as the value in the outgoing URL. The script searches from left to right and stops at the first match.	Example: ['in_channel', 'utm_channel'] For the channel parameter in the script, the script searches the incoming link for in_channel and uses the value as the value for channel.
overrideValues	Dictionary {string: string} For values you want changed in the outgoing link, list the values in the incoming URL, alongside what you want them to be replaced with. The script replaces the param values of the incoming URL with the values you define.	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	String State what you want your "fallback" value to be. If a parameter is not found from your key list, the defaultValue value is used in the outgoing URL. You can force a default value by passing an empty keys list.	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.

Arguments (parameters and values) provided to the developer to implement the Smart Script
Argument		Remarks	Record your responses (for the developer to use)
oneLinkURL (required)		Provide the OneLink template domain + template ID. Note: Not a OneLink custom link URL! Example: yourbrand.onelink.me/A1b2 Branded domain example: click.yourbrand.com/A1b2
afParameters (required)	mediaSource (required)	Configuration object for media source. Example: Keys: ['incoming_mediasource’' 'utm_source'] Override values: {twitter: 'twitter_int', orig_src: 'new_src'} Default value: ['any_source']	Keys: Override values: Default value:
	campaign	Configuration object for campaign. Example: Keys: ['incoming_campaign', 'utm_campaign'] Override values: {campaign_name: 'new_campaign_name'} Default value: ['any_campaign_name']	Keys: Override values: Default value:
	channel	Configuration object for channel. Example: Keys: ['incoming_channel', 'utm_channel'] Override values: {video: 'new_video'} Default value: ['any_video']	Keys: Override values: Default value:
	ad	Configuration object for ad. Example: Keys: ['incoming_ad', 'utm_ad'] Override values: {ad_name: 'new_ad_name'} Default value: ['any_ad_name']	Keys: Override values: Default value:
	adSet	Configuration object for adset. Example: Keys: ['incoming_adset', 'utm_adset'] Override values: {adset_name: 'new_adset_name'} Default value: ['any_adset_name']	Keys: Override values: Default value:
	deepLinkValue	Configuration object for deep_link_value. Example: Keys: ['product_id', 'page_name'] Override values: {twenty_percent_off: 'thirty_percent_off'} Default value: 'ten_percent_off'
	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. Note! To display in AppsFlyer raw data reports, the param must be one of af_sub[1-5].
	Other (custom) query parameters	List any other parameters you want to be included in the outgoing OneLink URL for attribution or deep linking, along with their configuration objects. The name of the custom parameter is listed by the developer as a paramKey in the configuration object. Example: paramKey: 'deep_link_sub1' Keys: ['page_id'] Override values: {page12: 'new_page12'} Default value: 'page1'	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 `null`. This can be useful for SRNs like Twitter and Facebook, for which clicks are already reported.
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 `null`. This can be useful if you use an AppsFlyer attribution link with af_r to redirect users to your mobile website, and don't want data from the original click to be lost.

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 an Adwords 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.

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:

Related reading

Setup

Note

Set up OneLink Smart Script

Configuration object

Arguments

Use cases

UTM parameters

Google Ads GCLID

Note

Facebook click ID

SRNs, owned media, and other media source links

Example

AppsFlyer attribution links

Example

Desktop

Agencies

Example

QR codes

Example

Comments

Articles in this section

Page contents:

OneLink Smart Script V2 setup

Related reading

Setup

Note

Set up OneLink Smart Script

Configuration object

Arguments

Use cases

UTM parameters

Google Ads GCLID

Note

Facebook click ID

SRNs, owned media, and other media source links

Example

AppsFlyer attribution links

Example

Desktop

Agencies

Example

QR codes

Example

Comments

Articles in this section

Related articles

Page contents: