OneLink Smart Script V2—Web-to-app URL generator
This page has a newer version
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.
Use code generated by the Smart Script generator
- Get the file from the marketer that includes the script, initialization code, and arguments.
- Test the script on the Smart Script test page. Ensure the correct outgoing URL is generated.
- Follow the test and use Smart Script result instructions.
See integration example in Github
Manually configure the script
- Download the script.
- Get the arguments to call the script which map the incoming parameters to the outgoing parameters from the marketer.
- 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
urlSkipList // optional
})
- Follow the test and use Smart Script result instructions.
Check and use Smart Script result
- 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 returnsnull
, 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//....
window.AF_SMART_SCRIPT.fireImpressionsLink();
}
Use Google Tag Manager
To set up the Smart Script in Google Tag Manager:
- Confirm that the marketer followed their instructions and placed the Smart Script code into GTM.
- 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 returnsnull
, 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//....
window.AF_SMART_SCRIPT.fireImpressionsLink();
}
- 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.1+
To create a QR code:
- 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. - After you run the Smart Script and generate a OneLink URL, call the following function and pass it the div ID:
window.AF_SMART_SCRIPT.displayQrCode("my_qr_code_div_id");
- Best practice: Once you have the result, show the QR code when users are on desktop and show the button with the link when users are on mobile.
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:
- Follow the instructions to run the Smart Script and generate a click URL.
- Make sure the result is valid (and not null).
- Run the following impression function:
window.AF_SMART_SCRIPT.fireImpressionsLink();
Arguments
Argument | Remarks | Example | |
---|---|---|---|
oneLinkURL (required) |
|
|
|
afParameters (required)
|
mediaSource (required) |
Configuration object for media source |
|
campaign |
Configuration object for campaign |
|
|
channel |
Configuration object for channel |
|
|
ad |
Configuration object for ad |
|
|
adSet |
Configuration object for adset |
|
|
deepLinkValue |
Configuration object for |
|
|
afSub1-5 |
Configuration object for |
||
googleClickIdKey |
State what to call the parameter that carries the
GCLID. |
||
Other (custom) query parameters |
|
|
|
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.
|
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. |
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.
Google click ID passthrough to af_sub
See example of the conversion of an incoming URL to an outgoing OneLink URL that passes the Google click ID to af_sub4. 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.
Facebook click ID passthrough to af_sub
See example of the conversion of an incoming URL to an outgoing OneLink URL that passes the Facebook click ID to af_sub2.
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 (including the af_prt parameter for agencies).
Referrer skip list
See example of how 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
.
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.
QR code
See example of how the Smart Script generates a QR code.
Impression
See example of an impression.
Updated 2 months ago