OneLink Smart Script V2

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

OneLink Smart Script uses incoming URLs leading to the webpage to automatically generate unique outgoing OneLink URLs leading to the app store.

The outgoing URLs are generated using 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.

Implementation steps

To set up the Smart Script, you can either:

Embed the script in your website

The Smart Script initialization and calling code can be either come from the Smart Script generator in the AppsFlyer dashboard (recommended), or imported and called manually by the developer.

📘

Preserve incoming URL parameters

In order to ensure incoming URL parameters will be mapped to the generated OneLink, it is recommended to import the Smart Script in every website page, whether a OneLink is generated in the page or not.

Available from version 2.5.0.

More details and a full example here.

Use code generated by the Smart Script generator

1. Get the file from the marketer that includes the script, initialization code, and arguments.
2. Test the script on the Smart Script test page. Ensure the correct outgoing URL is generated.
3. Follow the test and use Smart Script result instructions.

See integration example in Github

Manually configure the script

1. Download the script.
2. Get the arguments to call the script which map the incoming parameters to the outgoing parameters from the marketer.
3. Initialize the Smart Script arguments and configuration objects.
4. 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
  urlSkipList // optional
})

5. Follow the test and use Smart Script result instructions.

Check and use Smart Script result

1. Check the return value in result. Possible return values are:
   • An outgoing Onelink URL. Use the result value as needed. For example, to place it as a link under a CTA on your website.
   • null. If the script returns null, implement your desired error flow. For example: the web/landing page's existing URL is not changed.

      var result_url = "No output from script"
      if (result) {
            result_url = result.clickURL;            
            // Put the generated OneLink URL behind CTA buttons
            document.getElementById('andrd_link').setAttribute('href', result_url);
            document.getElementById('ios_link').setAttribute('href', result_url);
            // Optionally - Create QR code from the generated OneLink URL
            window.AF_SMART_SCRIPT.displayQrCode("my_qr_code_div_id");
            //The size of the QR code is defined in the CSS file under #my_qr_code_div_id
            // #my_qr_code_div_id canvas { 
            //  height: 200px;
            //  width: 200px;
            //}
            // Optionally - fire an impression.
            // The impression will fire to https://impressions.onelink.me//.... 
            setTimeout(() => {
              window.AF_SMART_SCRIPT.fireImpressionsLink();
              console.log("Impression fired"); 
            }, 1000);
      }

Use Google Tag Manager

To set up the Smart Script in Google Tag Manager:

1. Confirm that the marketer followed their instructions and placed the Smart Script code into GTM.
2. Check the return value in AF_SMART_SCRIPT_RESULT. Possible return values are:
   • An outgoing OneLink URL. Use the result value as needed. For example, to place it as a link under a CTA on your website.
   • null. If the script returns null, implement your desired error flow. For example: the web/landing page's existing URL is not changed.

      var result_url = AF_SMART_SCRIPT_RESULT.clickURL;
      if (result_url) {
            document.getElementById('andrd_link').setAttribute('href', result_url);
            document.getElementById('ios_link').setAttribute('href', result_url);
            // Optionally - Create QR code from the generated OneLink URL
            window.AF_SMART_SCRIPT.displayQrCode("my_qr_code_div_id");
            //The size of the QR code is defined in the CSS file under #my_qr_code_div_id
            // #my_qr_code_div_id canvas { 
            //  height: 200px;
            //  width: 200px;
            //}
            // Optionally - fire an impression.
            // The impression will fire to https://impressions.onelink.me//.... 
            setTimeout(() => {
              window.AF_SMART_SCRIPT.fireImpressionsLink();
              console.log("Impression fired"); 
            }, 1000);            
      }

3. Test the script on the Smart Script test page. Ensure the correct outgoing URL is generated.

Create a QR code with the Smart Script result

Prerequisite: Smart Script V2.6+

📘

Best practices

• Customize the QR code according to your app brand with a center logo and a relevant code color
• Show the QR code when users are on desktop and show the button with the link when users are on mobile

To create a QR code:

1. Create a div tag with a specific ID in your site's HTML page to host the QR code.
   You can style the div tag however you want.
2. After you run the Smart Script and generate a OneLink URL, call the following method displayQrCode

displayQrCode

Method signature

const qrOptions = {
  logo,
  colorCode
}

window.AF_SMART_SCRIPT.displayQrCode(divId, qrOptions)

Input arguments

qrOptions object

Usage examples:

• QR code without logo and without custom color Github example
• QR code with logo and custom code color Github example

Fire an impression

You can fire an impression when a page loads, a CTA or banner displays, etc. Note: Impressions can only be fired on mobile devices; not on desktop.

Prerequisite: Smart Script V2.2+

To fire an impression:

1. Follow the instructions to run the Smart Script and generate a click URL.
2. Make sure the result is valid (and not null).
3. Run the following impression function:

🚧

A must-do workaround

Please wrap the call to fireImpressionsLink with setTimeout to make sure there is at least 1 second of delay between the call to generateOneLinkURL and fireImpressionsLink

setTimeout(() => {
  window.AF_SMART_SCRIPT.fireImpressionsLink();
  console.log("Impression fired"); 
}, 1000);

You can find examples for firing impressions for mobile only and for cross platform support

Arguments

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.

Examples

Basic attribution

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

Multiple keys

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

UTM parameters

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

Override values

See example of the conversion of an incoming URL to an outgoing OneLink URL, replacing the incoming media_source value.

Default values

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

Forced default values

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

GBRAID and WBRAID

See example of the conversion of an incoming URL to an outgoing OneLink URL, passing the gbraid parameter and another example for passing the wbraid parameter.

Google click ID passthrough

See example of the conversion of an incoming URL to an outgoing OneLink URL that passes the Google click ID to af_sub4 and gclid.
As of Smart Script version 2.8.1, the GCLID is automatically forwarded to the outgoing URL when present in the incoming URL.
Note: When a GCLID is detected, the script searches for the incoming keyword parameter, and inserts its value into the outgoing URL as the value for the af_keywords parameter.

Facebook click ID passthrough

See example of the conversion of an incoming URL to an outgoing OneLink URL that passes the Facebook click ID to af_sub2 and fbclid.
As of Smart Script version 2.8.1, the FBCLID is automatically forwarded to the outgoing URL when present in the incoming URL.

Set attribution and OneLink parameters

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

Set additional custom parameters

See example of the conversion of an incoming URL to an outgoing OneLink URL with additional custom parameters.

Referrer skip list

See example of how you can disable the Smart Script for a particular click (for example, from Twitter or Meta ads) 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.

URL skip list

See example of how you can disable the Smart Script for a particular string in the URL (for example, af_r) by creating a skip list. If any of the strings in the skip list appear in the URL of the click, the Smart Script returns null.

Smart Script set up with Google Tag Manager

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

Impressions - OneLink Template with mobile-only support

See example of an impressions fired using a OneLink template who has only mobile device.

🚧

A must-do workaround

Please wrap the call to fireImpressionsLink with setTimeout to make sure there is at least 1 second of delay between the call to generateOneLinkURL and fireImpressionsLink

Impressions - OneLink Template with Cross-platform support

See example of an impressions fired using a OneLink template who has cross-platform support.
For example an impression fired from a non-mobile platform (e.g desktop or console).

📘

Firing an impression from a cross platform landing page

You can find here a code example for firing an impression from a demo landing page

🚧

A must-do workaround

Please wrap the call to fireImpressionsLink with setTimeout to make sure there is at least 1 second of delay between the call to generateOneLinkURL and fireImpressionsLink

Preserve incoming URL parameters across pages

📘

Available from version 2.5.0.

Incoming parameters (e.g. utm_source) from a landing page are not passed to other pages in the website by default.
Importing Smart Script in every website page preserves the incoming URL parameters, and allows Smart Script to use them in other pages.

You can find here an example of this use case.

Copy HTTP referrer to outgoing URL

📘

Available from version 2.7.0.

You can set Smart Script to copy the HTTP document.referrer to either a custom outgoing URL parameter or predefined outgoing URL parameters. If you want to see web referrer values in dashboards or in raw data reports, we suggest using one of the following predefined outgoing URL parameters:

• af_channel - Parameter is available in dashboards and raw data
• af_sub1-5 - The parameter is available in raw data under the af_sub1-5 columns and in the original URL column.

If you want to set a custom parameter, Smart Script has to copy the  document.referrer property value and set it as the value of the parameter. In this example, Smart Script copies the document.referrer value to a custom outgoing URL parameter key defined by webReferrer. The selected custom key in the example is this_referrer.

For more information, see Web referrer mapping.

Utilizing Local Storage to Set Parameters for Deep Linking

You can choose to save any data from the website to local storage, and then configure Smart Script to retrieve this data and assign it to an outgoing URL parameter. For example, you can leverage website information to dynamically populate the deep_link_value parameter, enabling the deep linking of users directly to the app's relevant content.

In this example, you can see how the outgoing URL deep_link_value is populated by a value copied from the website's local storage. The copied value in this example is the product ID arriving from the website data.