At a glance: Customize OneLinks that are automatically generated and embedded behind a button or banner on your brand's website.

About OneLink Smart Script

Users arrive at your mobile website before reaching your app store page, either organically, or via advertising campaigns. However, since there are two clicks (the first that directs to the web page and the second that directs from the web page to the app store), collecting click conversion metrics and deep linking is problematic.

OneLink Smart Script solves these problems. The script:

Uses the incoming URLs leading to the webpage to automatically generate unique outgoing OneLink URLs leading to the app store.
Provides accurate web-to-app metrics collection for all media sources.
Can be used for deep linking.
Runs seamlessly on any webpage or landing page.

The outgoing URLs are generated using the arguments you receive from the marketer and input into the script. Note: The afParameters argument has a structure made up of several other arguments (parameters), each of which contains a configuration object that has keys, override values, and a default value. The arguments and configuration object structure are described in the sections that follow.

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

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

Argument		Remarks	Example
oneLinkURL (required)		Provide the OneLink template domain + template ID. Note: Not a OneLink custom link URL!	yourbrand.onelink.me/A1b2 Branded domain example: yourbrand.com/A1b2
afParameters (required)	mediaSource (required)	Configuration object for media source	Keys: ['incoming_mediasource’' 'utm_source'] Override values: {twitter: 'twitter_int', orig_src: 'new_src'} Default value: ['any_source']
	campaign	Configuration object for campaign	Keys: ['incoming_campaign', 'utm_campaign'] Override values: {campaign_name: 'new_campaign_name'} Default value: ['any_campaign_name']
	channel	Configuration object for channel	Keys: ['incoming_channel', 'utm_channel'] Override values: {video: 'new_video'} Default value: ['any_video']
	ad	Configuration object for ad	Keys: ['incoming_ad', 'utm_ad'] Override values: {ad_name: 'new_ad_name'} Default value: ['any_ad_name']
	adSet	Configuration object for adset	Keys: ['incoming_adset', 'utm_adset'] Override values: {'adset_name': 'new_adset_name'} Default value: ['any_adset_name']
	deepLinkValue	Configuration object for `deep_link_value`	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]`
	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 of 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 `paramKey` in the configuration object.	paramKey: 'deep_link_sub1' Keys: ['page_id'] Override values: {page12: 'new_page12'} Default value: 'page1'
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.

Procedures

To set up the Smart Script, you can either:

Embed the script in your website.
Use Google Tag Manager.

Embed the script in your website

To embed the script to your website:

Download the script and import it into the mobile site/pages on which you want it to run.
Get from the marketer: The arguments to call the script which maps the incoming parameters to the outgoing parameters.
Initialize the Smart Script arguments and configuration objects.
generate the URLS by calling the script in the web/landing page HTML using the following method:

var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters,
  referrerSkipList // optional
})

Possible return values are:
- An outgoing Onelink URL.
- null. If the script returns null, implement your desired flow. For example: the web/landing page's existing URL is not changed.

Use Google Tag Manager

To set up the Smart Script in Google Tag Manager:

Confirm that the marketer has the OneLink Smart Script code, followed by the Smart Script initialization code (with the arguments and configuration objects).
Make sure the initialization code has a result passed to AF_SMART_SCRIPT_RESULT that is not null.
Use the result value to generate the link on your website.

Examples

Basic attribution

The following example shows the basic conversion of an incoming URL to an outgoing OneLink URL, with a single key for media_source and campaign

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/single_key.html?incmp=gogo&inmedia=email

Script:

//Initializing Smart Script arguments
var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
var mediaSource = {keys: ["inmedia"]};
var campaign = {keys: ["incmp"]};

//Call the function after embedding the code through a global parameter on the window object called window.AF_SMART_SCRIPT.
//Onelink URL is generated
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
    oneLinkURL,
    afParameters:{
        mediaSource: mediaSource,
        campaign: campaign,
    }
})

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?pid=email&c=gogo&af_js_web=true&af_ss_ver=2

Multiple keys

The following example shows the conversion of an incoming URL to an outgoing OneLink URL, with multiple keys for media_source and campaign.

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/single_key.html?incmp11=gogo11&inmedia22=email22

Script:

//Initializing Smart Script arguments
var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
var mediaSource = {keys: ["inmedia11", "inmedia22"]};
var campaign = {keys: ["incmp11", "incmp22"]};

//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT.
//Onelink URL is generated
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters:{
    mediaSource: mediaSource,
    campaign: campaign,
  }
})

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?af_js_web=true&af_ss_ver=2&pid=email22&c=gogo11

UTM parameters

The following example shows the conversion of an incoming URL to an outgoing OneLink URL, with UTM parameters for media_source and campaign.

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/utm_parameters.html?utm_campaign=mycmpn&utm_source=mysource

Script:

//Initializing Smart Script arguments
var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
var mediaSource = {keys: ["inmedia","utm_source"]};
var campaign = {keys: ["incmp", "utm_campaign"]};

//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT.
//Onelink URL is generated
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters:{
    mediaSource: mediaSource,
    campaign: campaign,
  }
})

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?pid=mysource&c=mycmpn&af_js_web=true&af_ss_ver=2

Override values

The following example shows the conversion of an incoming URL to an outgoing OneLink URL, replacing the incoming media_source value.

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/override_mediasource.html?inmedia=old_value

Script:

/Initializing Smart Script arguments
var oneLinkURL = “https://engmntqa.onelink.me/LtRd/”;
var mediaSource = {keys: [“inmedia”], overrideValues: {old_value: “new_value”}};
//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT.
//Onelink URL is generated
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters:{
    mediaSource: mediaSource
  }
})

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?pid=new_value&af_js_web=true&af_ss_ver=2

Default values

The following example shows the conversion of an incoming URL to an outgoing OneLink URL, using the default value when an incoming media_source value isn't found.

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/override_mediasource.html?inmedia_found=orig_media_value

Script:

//Initializing Smart Script arguments
var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
var mediaSource = {keys: ["not_there_inmedia"], overrideValues: {old_value: "new_value"}, defaultValue: "my_media_default_value"};

//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT.
//Onelink URL is generated
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters:{
    mediaSource: mediaSource
  }
})

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?pid=my_media_default_value&af_js_web=true&af_ss_ver=2

Forced default values

The following example shows the conversion of an incoming URL to an outgoing OneLink URL, using the default value even when an incoming media_source value is found.

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/forced_default_values.html?inmedia_found=plain_media_source

Script:

//Initializing Smart Script arguments
var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
var mediaSource = {keys: [], defaultValue: "my_media_value"};
var campaign = {keys: [], defaultValue: "my_campaign"};

//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT.
//Onelink URL is generated
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters:{
    mediaSource: mediaSource,
    campaign: campaign
  }
})

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?pid=my_media_value&c=my_campaign&af_js_web=true&af_ss_ver=2

Google click ID passthrough to af_sub

The following example shows the conversion of an incoming URL to an outgoing OneLink URL that passes the Google click ID to af_sub2. Note: When a GCLID is found, the script looks for the incoming parameter keyword, and puts the keyword value in the outgoing URL as the value of af_keywords.

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/google_clickid.html?inmedia=email&gclid=1a2b3c&keyword=sale%2Bboat

Script:

//Initializing Smart Script arguments
var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
var mediaSource = {keys: ["inmedia"]};
var googleClickIdKey = "af_sub4";

//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT.
//Onelink URL is generated
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
    oneLinkURL,
    afParameters:{
    mediaSource: mediaSource,
    googleClickIdKey: googleClickIdKey
    }
})

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?af_js_web=true&af_ss_ver=2&pid=email&af_sub4=1a2b3c&af_keywords=sale+boat

Facebook click ID passthrough to af_sub

The following example shows the conversion of an incoming URL to an outgoing OneLink URL that passes the Facebook click ID to af_sub2.

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/facebook_clickid.html?inmedia=email&fbclid=7hjy89

Script:

//Initializing Smart Script arguments
var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
var mediaSource = {keys: ["inmedia"]};
// Facebook clickid is placed in af_sub2
var afSub2 = {keys: ["fbclid"], defaultValue: "no_fbclid"};

//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT.
//Onelink URL is generated
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
    oneLinkURL,
    afParameters:{
        mediaSource: mediaSource,
        afSub2: afSub2
    }
})

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?af_js_web=true&af_ss_ver=2&pid=email&af_sub2=7hjy89

Set attribution and OneLink parameters

The following example shows the conversion of an incoming URL to an outgoing OneLink URL with AppsFlyer attribution and OneLink parameters.

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/onelink_parameters.html?inmedia=email&dp_dest=apples&inchnl=this_channel&promo=buy99

Script:

//Initializing Smart Script arguments
 var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
 var mediaSource = {keys: ["inmedia"]};
 var channel = {keys: ["inchnl"]};
 var deepLinkValue = {keys: ["dp_dest"], defaultValue: "peaches"};
 var afSub3 = {keys: ["promo"]};

//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT. //Onelink URL is generated
 var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
    oneLinkURL,
     afParameters:{
         mediaSource: mediaSource,
        channel: channel,
         deepLinkValue: deepLinkValue,
        afSub3: afSub3
     }
 })

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?af_js_web=true&af_ss_ver=2&pid=email&af_channel=this_channel&deep_link_value=apples&af_sub3=buy99

Set additional custom parameters

The following example shows the conversion of an incoming URL to an outgoing OneLink URL with additional custom parameters (including the af_prt parameter for agencies).

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/onelink_custom_parameters.html?inmedia=email&dp_dest=apples&pageid=2g4f&productid=shirt12&partner=bigagency

Script:

//Initializing Smart Script arguments
var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
var mediaSource = {keys: ["inmedia"]};
var deepLinkValue = {keys: ["dp_dest"], defaultValue: "peaches"};
// Setting an attribution parameter
var custom1 = {paramKey: "af_prt", keys: ["partner"], defaultValue: "defaultPartner"};
// Setting OneLink custom parameter
var custom2 = {paramKey: "dl_page_id", keys: ["pageid"], defaultValue: "1a1a"};
var custom3 = {paramKey: "dl_product_id", keys: ["productid"], overrideValues: {shirt12: "men_shirt_012"}, defaultValue: "no_shirt"};
// This custom value is forced
var custom4 = {paramKey: "dl_product_source", keys: [], defaultValue: "dl_new_source"};

//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT.
//Onelink URL is generated
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
    oneLinkURL,
    afParameters:{
        mediaSource: mediaSource,
        deepLinkValue: deepLinkValue,
        afCustom: [
            custom1,
            custom2,
            custom3,
            custom4
        ]
    }
})

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?af_js_web=true&af_ss_ver=2&pid=email&deep_link_value=apples&af_prt=bigagency&dl_page_id=2g4f&dl_product_id=men_shirt_012&dl_product_source=dl_new_source

Skip list

You can disable the Smart Script for a particular click (for example, from Twitter or Facebook) by creating a skip list. If any of the strings in the skip list appear in the HTTP referrer of the click, the Smart Script returns null.

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/skip_list.html?incmp=gogo&inmedia=email

Script:

//Initializing Smart Script arguments
var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
var mediaSource = {keys: ["inmedia"]};
var campaign = {keys: ["incmp"]};
var referrerSkipList = ["facebook"];

//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT.
//Onelink URL is generated
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
    oneLinkURL: oneLinkURL,
    afParameters:{
        mediaSource: mediaSource,
        campaign: campaign,
    },
    referrerSkipList: referrerSkipList
})

Outgoing URL:
No output from script.

Smart Script set up with Google Tag Manager

The following example shows the conversion of an incoming URL to an outgoing OneLink URL using OneLink Smart Script set up using Google Tag Manager.

Incoming URL:
https://appsflyersdk.github.io/appsflyer-onelink-smart-script/examples/google_tag_manager.html?my_source=email&app_dest=planes&typeid=b787&msg_id=f7h8

Script:

//Initializing Smart Script arguments
var oneLinkURL = "https://engmntqa.onelink.me/LtRd/";
var mediaSource = {keys: ["my_source"], defaultValue: "noMediaSource"};
var deepLinkValue = {keys: ["app_dest"], defaultValue: "default_view"};
// Setting an attribution parameter
var afSub4 = {keys: ["msg_id"], defaultValue: "no_msg_id"};
// Setting OneLink custom parameter
var deepLinkSub1 = {paramKey: "deep_link_sub1", keys: ["typeid"], defaultValue: "1a1a"};

//Function is embedded on the window object in a global parameter called window.AF_SMART_SCRIPT.
//Onelink URL is generated
AF_SMART_SCRIPT_RESULT = window.AF_SMART_SCRIPT.generateOneLinkURL({
    oneLinkURL,
    afParameters:{
        mediaSource: mediaSource,
        deepLinkValue: deepLinkValue,
        afSub4: afSub4,
        afCustom: [
            deepLinkSub1
        ]
    }
})

Outgoing URL:
https://engmntqa.onelink.me/LtRd/?af_js_web=true&af_ss_ver=2&pid=email&deep_link_value=planes&af_sub4=f7h8&deep_link_sub1=b787