OneLink Smart Script V2 setup

For:
Marketers Developers
Last update:

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

7901_Smart_Script_flow_1920x1080_2__1_.png

 Related reading

For a complete picture of working with Smart Banners, check out these articles:

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. It can be generated in the AppsFlyer UI without developer assistance. If  for some reason, a developer is needed, their 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

  • Advertiser:

    • Decides what the outgoing URL should contain based on the 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.

    • Generates the Smart Script in the AppsFlyer UI. 

    • Makes sure all campaigns leading to the mobile website have incoming URLs with parameters that the script works for.
    • Tests the Smart Script. 
  • Web developer:
    • Verifies the script runs on the mobile site/pages on which you want it to work.
    • Uses the result value as needed, for example, to place it as a link under a CTA on your website.
    • May be needed to create QR codes using the script.
    • May be needed to manually add advanced arguments to the script.

Prerequisites
Scope of work

To set up the OneLink Smart Script:

  1. In AppsFlyer, go to Experiences & Deep Linking > Web-to-app > Smart Script.
  2. Select a OneLink template to base the script on. The template contains the basic redirection settings.
  3. Map the parameters that the outgoing URL should contain. These parameters are based on the parameters of the incoming URL. Note: The media source (pid) parameter is mandatory.
    1. Select the outgoing parameter/dimension to map.
      Often, this is an AppsFlyer parameter name that can't be changed, but in some cases, you need to enter your parameter name.
    2. Decide and configure what the value of the outgoing parameter should be based on either:
      • Incoming URL parameters: List one or more possible incoming URL parameters that you want replaced by the outgoing URL parameter. The values of the incoming URL parameters will be the values of your outgoing URL parameter.
        • Example: any_param_name, utm_param_name. If utm_param_name is found in the incoming URL, its value will be used as the value of your selected outgoing URL parameter.
        • The Smart Script searches the list of parameters from left to right and maps the first match to the outgoing parameter URL.
        • This list of parameters is referred to by developers as keys.
      • Default value: Enter your desired default value for the outgoing parameter value for when an incoming URL parameter isn't found or if you don’t list any incoming URL parameters.
        • Example: For the outgoing parameter, if the incoming URL parameter lists any_paramname, utm_paramname, when neither parameter in the list is found, the default value will be used as the value of the outgoing parameter.
      • Override values: Configure one or more values from the incoming URL alongside the values of the outgoing URL you want them to be replaced with.
        • Example: For the campaign parameter, if the value in the incoming URL is campaign_name, the value in the outgoing URL can be changed to new_campaign_name.
    3. [Optional] Click + New parameter to map additional parameters. See all the additional arguments (parameter configurations) you can use.
  4. Select how to implement the Smart Script on your website:
    • Embed the script in your website.
    • Use Google Tag Manager.
  5. Click Generate.
  6. Click Download script.
  7. If you selected to embed the script in your website: Send the script to your web developer to implement and tell them what to do with the generated outgoing URL. For example, place it under a CTA button on your mobile site or present a QR code on your desktop site. Developer instructions
  8. If you selected to use Google Tag Manager:
    1. In Google Tag Manager, create a new tag, name the tag, click Tag Configuration, and select Custom HTML.
    2. In the HTML box, paste the generated Smart Script code.
    3. Click Triggering, create a new trigger, name it, and choose a Trigger Configuration (for example, all page views). See GTM documentation to learn more
    4. Click Save.
    5. Tell your web developer what to do with the generated outgoing URL. For example, place it under a CTA button on your mobile site or present a QR code on your desktop site. Developer instructions
  9. Test the script on the Smart Script test page. Ensure the correct outgoing URL is generated.

Important! Every time you update the script, it needs to be implemented again.

Argument structure

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 structure (referred tp by developers as a configuration object) that has keys, override values, and a default value, as described in the table that follows.

Argument Description Example
Incoming URL parameters (referred to by developers as 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.
Default value
  • 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.

Override values
  • 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.
Configuration object 

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 you or your 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']
    • Default value: ['any_source']
    • Override values: {twitter: 'twitter_int', orig_src: 'new_src'}

Keys:

Default value:

Override values:

campaign
  • Configuration object for campaign.
  • Example:
    • Keys: ['incoming_campaign', 'utm_campaign']
    • Default value: ['any_campaign_name']
    • Override values: {campaign_name: 'new_campaign_name'}

Keys:

Default value:

Override values:

channel
  • Configuration object for channel.
  • Example:
    • Keys: ['incoming_channel', 'utm_channel']
    • Default value: ['any_video']
    • Override values: {video: 'new_video'}

Keys:

Default value:

Override values:

ad
  • Configuration object for ad.
  • Example:
    • Keys: ['incoming_ad', 'utm_ad']
    • Default value: ['any_ad_name']
    • Override values: {ad_name: 'new_ad_name'}

Keys:

Default value:

Override values:
adSet
  • Configuration object for adset.
  • Example:
    • Keys: ['incoming_adset', 'utm_adset']
    • Default value: ['any_ad_name']
    • Override values: {adset_name: 'new_adset_name'}

Keys:

Default value:

Override values:
deepLinkValue
  • Configuration object for deep_link_value.
  • Example:
    • Keys: ['product_id', 'page_name']
    • Default value: 'new_offers_page'
    • Override values: {twenty_percent_off: 'thirty_percent_off'}

Keys:

Default value:

Override values:
afSub1-5

Configuration object for af_sub[1-5].

Keys:

Default value:

Override values:
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']
    • Default value: 'page1'
    • Override values: {page12: 'new_page12'}

Param key:

Keys:

Default value:

Override values:
Arguments (parameters and values) to implement the Smart Script

Advanced arguments

The following table describes arguments that technical-savvy marketers or developers can implement in the Smart Script. 

Argument Remarks Record your responses (for you or your developer to use)
 
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.
  • Implementing this argument results in the script NOT generating a OneLink URL.

 
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.
  • Implementing this argument results in the script NOT generating a OneLink URL.

 
Advanced arguments (parameters and values) to implement the Smart Script

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:

  1. 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). 
  2. 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:

  1. 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.
  2. 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:

  1. Get the GCLID data from the param af_sub[1-5] via CSV, or Push API in real-time for every install.
  2. 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:

  1. 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.
  2. 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:

  1. Make a list of the media source and campaign parameter names that are in the incoming links.
  2. Provide these in the list of arguments to the web developer.
    T    he 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:

  1. Make sure you use Smart Script 2.1+ when you set up your Smart Script.
  2. Tell your developer to follow their instructions to create a QR code with the Smart Script result.
  3. 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): 

  1. Make sure you use Smart Script 2.2+ when you set up your Smart Script.
  2. Tell your developer to call the impression function in the Smart Script.
  3. Make sure view-through attribution is turned on.
  4. [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.

Specs and limitations

Spec

Remarks

URI scheme

 Even if a URI scheme is set in the OneLink template to open the app for existing users, for links created using Smart Script, the af_dp parameter with the URI scheme must be added by the developer to URLs as a custom parameter.