Script intelligent OneLink

En bref : personnalisez des OneLink générés automatiquement et intégrés dans un bouton ou une bannière sur le site web de votre marque.

À propos de OneLink Smart Script

One Link Smart Script Utilise les URL entrantes qui mènent à la page web pour générer automatiquement des URL OneLink sortantes uniques dirigées vers l'app store.

Les URL sortantes sont générées à l'aide des arguments transmis par le marketeur et saisis dans le script. Remarque : afParameters la structure de l'argument (paramètres) est composée de plusieurs autres arguments (paramètres), chacun contenant un objet de configuration qui possède des clés, des valeurs de remplacement et une valeur par défaut.

Marche à suivre pour l'implémentation

Pour configurer le script intelligent, vous pouvez :

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.

Utiliser le code généré par le générateur Smart Script

  1. Demandez au marketeur de vous transmettre le fichier qui contient le script, le code d'initialisation et les arguments.
  2. Test the script on the Smart Script test page. Ensure the correct outgoing URL is generated.
  3. Lancez le test et suivez les instructions reltives au résultat Smart Script.

Voir un exemple d’intégration dans Github

Configurer manuellement le script

  1. Télécharger le script.
  2. Récupérez auprès du marketeur les arguments pour appeler le script qui mappe les paramètres entrants et les paramètres sortants.
  3. Initialisez les arguments arguments et les objets de configuration du script intelligent.
  4. Générez les URL en appelant le script dans le HTML de la page web/d'accueil à l'aide de la méthode suivante :
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters,
  referrerSkipList, // optional
  urlSkipList // optional
})
  1. Lancez le test et suivez les instructions reltives au résultat Smart Script.

Lire et utiliser les résultats du Smart Script

  1. Vérifiez la valeur renvoyées dans resultLes valeurs renvoyées possibles sont les suivantes :
    • 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. Si le script renvoie null, installez le processus de gestion des erreurs de votre choix. Par exemple : l'URL existante de la page web/d'accueil n'est pas modifiée.
      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

Pour configurer le script intelligent dans le gestionnaire de balises Google :

  1. Confirm that the marketer followed their instructions and placed the Smart Script code into GTM.
  2. Vérifiez la valeur renvoyées dans AF_SMART_SCRIPT_RESULTLes valeurs renvoyées possibles sont les suivantes :
    • Une URL Onelink sortante. Utilisez la valeur résultat selon les besoins. Exemple : vous pouvez l'utiliser sur votre site comme lien de CTA.
    • null. Si le script renvoie null, installez le processus de gestion des erreurs de votre choix. Par exemple : l'URL existante de la page web/d'accueil n'est pas modifiée.
      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);            
      }
  1. 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

Pour créer un QR code :

  1. Créez une balise div avec un ID spécifique sur la page HTML de votre site pour héberger le QR code. Vous pouvez donner à la balise div le style que vous souhaitez.
  2. After you run the Smart Script and generate a OneLink URL, call the following method displayQrCode

displayQrCode


Signature de la méthode

const qrOptions = {
  logo,
  colorCode
}

window.AF_SMART_SCRIPT.displayQrCode(divId, qrOptions)

Arguments d'entrée

TypeObligatoireNomDescriptionComment
StringOuidivIDA div tag with a specific ID in your site's HTML page to host the QR code
ObjectNonqrOptionsConfiguration object (see details in the table below)If the object is missing, the QR code will be created without a logo in default color

qrOptions object

TypeObligatoireNomDescriptionComment
StringNonlogoA valid image URL or an image data-URIIf the value is invalid, the QR code will be generated without the logo
StringNoncolorCodeHex color of the QR codeIf the value is invalid, the code color will fallback to the default black color

Usage examples:

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.

Condition préalable : Smart Script V2.2 et +

Pour lancer une impression :

  1. Suivez les étapes pour exécuter le Smart Script puis générer une URL de clic.
  2. Vérifiez que le résultat est bien valide (et non « null »).
  3. Exécutez la fonction d’impression ci-dessous :

🚧

A must-do workaround

Please wrap the call to fireImpressionsLink , 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

Argument Remarques Exemple
oneLinkURL (obligatoire)
  • Fournir le domaine du template OneLink + l'ID du template. Remarque : il ne s'agit pas d'une URL de lien personnalisé OneLink.
  • yourbrand.onelink.me/A1b2
  • Exemple de domaine de marque : votremarque.com/A1b2

afParameters

(requis)

 

 

 


mediaSource

(requis)

Objet de configuration pour la source média

  • Clés : ['incoming_mediasource'' 'utm_source']
  • Remplacer les valeurs : {title: 'twitter_int', orig_src: 'new_src'}
  • Valeur par défaut : ['any_source']

campaign

Objet de configuration pour la campagne

  • Clés : ['incoming_campaign', 'utm_campaign']
  • Remplacer les valeurs : {campaign_name: 'new_campaign_name'}
  • Valeur par défaut : ['any_campaign_name']

channel

Objet de configuration pour le canal

  • Clés : ['incoming_channel', 'utm_channel']
  • Remplacer les valeurs : {video: 'new_video'}
  • Valeur par défaut : ['any_video']

ad

Objet de configuration pour la publicité

  • Clés : ['incoming_ad', 'utm_ad']
  • Remplacer les valeurs : {nom_ad : 'nouveau_nom_ad'}
  • Valeur par défaut : ['any_ad_name']
adSet

Objet de configuration pour l'adset

  • Clés  :: ['incoming_adset', 'utm_adset']
  • Remplacer les valeurs : {'adset_name': 'new_adset_name'}
  • Valeur par défaut : ['any_adset_name']
deepLinkValue

Objet de configuration pour deep_link_value

  • Clés : ['product_id', 'page_name']
  • Remplacer les valeurs : {twenty_percent_off: 'thirty_percent_off'}
  • Valeur par défaut : 'new_offers_page'
afSub1-5

Objet de configuration pour af_sub[1-5]

 
googleClickIdKey

Indiquez comment appeler le paramètre qui porte le GCLID.
Important ! Pour s'afficher dans les rapports de données brutes AppsFlyer, le paramètre doit être l'un des suivants  : af_sub[1-5].

 
Autres paramètres de requête (personnalisés)
  • Listez tous les autres paramètres que vous souhaitez inclure dans l'URL OneLink sortante pour l'attribution ou le deep linking, avec leurs objets de configuration.
  • Le nom du paramètre personnalisé est répertorié par le développeur en tant que paramKey dans l'objet de configuration.
  • paramKey: 'deep_link_sub1'
  • Clés : ['page_id']
  • Remplacer les valeurs : {page12 : 'new_page12'}
  • Valeur par défaut : "page1".
 
referrerSkipList
List of the strings in the HTTP referrer for a particular click (for example Twitter or Meta ads) that if found, cause the Smart Script to return null. This can be useful for SRNs like Twitter and Meta ads, for which clicks are already reported.  
urlSkipList Liste des chaînes dans l'URL pour un clic précis ( exemple : af_r) qui, s'il est trouvé, renvoie le script intelligent null. Est utile si vous utilisez un lien d'attribution AppsFlyer avec af_r pour rediriger les utilisateurs vers votre site web mobile, et que vous voulez éviter que les données du clic initial soient perdues.  
webReferrer This argument defines a key in the outgoing URL, which its value will be a copy of the HTTP document.referrer. The referrer is saved in the first page the user lands in, and may be used in any consecutive page in this domain which runs Smart Script with this argument.  

Objet de configuration

Le script intelligent OneLink utilise des arguments pour générer une URL sortante en fonction des paramètres de l'URL entrante et des arguments définis dans le script. La structure de l'argument afParameters est composée de plusieurs autres arguments (paramètres) utilisés pour l'attribution et le deep linking, chacun d'entre eux contient un objet de configuration qui inclut des clés, des valeurs prioritaires et une valeur par défaut, comme décrit dans le tableau qui suit.

Argument Description Exemple
keys
  • Liste des chaînes de caractères
  • Liste du ou des paramètres possibles contenus dans l'URL entrante que le script recherche, et dont la valeur sera la valeur de l'URL sortante.
  • Le script recherche de gauche à droite et s'arrête à la première correspondance.
  • Exemple : ['in_channel', 'utm_channel']
  • Pour le paramètre de canal du script, le script recherche le lien entrant pour in_channel et utilise la valeur comme valeur pour le canal.

overrideValues

  • Dictionary {string: string}
  • Pour les valeurs que vous souhaitez modifier dans le lien sortant, indiquez les valeurs et leurs valeurs de remplacement dans l'URL entrante.
  • Le script remplace les valeurs de paramètre de l'URL entrante par les valeurs que vous définissez. 

Exemple : {'video' : 'video_new'}

Pour le paramètre du canal dans le script, chaque fois que la valeur entrante est « video », le script la change en « video_new » dans le lien sortant.

defaultValue
  • Chaîne
  • Indiquez votre valeur de secours.
  • Si un paramètre n'est pas trouvé dans votre liste de clés, la valeur par défaut (defaultValue) est utilisée dans l'URL sortante.
  • Vous pouvez forcer une valeur par défaut en transmettant une liste de clés vides.

Exemple : ['web_video']

Pour le paramètre de canal dans le script, si le paramètre in_channel n'est pas trouvé, web_video est utilisé comme valeur du canal.

Exemples

Basic attribution

Voir cet exemple de conversion de base d’une URL entrante en URL OneLink sortante, avec une même clé pour media_source et la campagne

Multiple keys

Voir cet exemple de conversion d’une URL entrante en URL OneLink sortante, avec plusieurs clés pour media_source et pour la campagne.

UTM parameters

Voir cet exemple de conversion d’une URL entrante en URL OneLink sortante, avec des paramètres UTM pour media_source et pour la campagne.

Override values

Cet exemple montre la conversion d'une URL entrante en URL OneLink sortante, en remplaçant la valeur media_source entrante.

Default values

Cet exemple montre la conversion d'une URL entrante en URL OneLink sortante, en utilisant la valeur par défaut dans le cas où aucune valeur media_source entrante n'est trouvée.

Forced default values

Cet exemple montre la conversion d'une URL entrante en URL OneLink sortante, en utilisant la valeur par défaut même lorsqu'une valeur media_source entrante est trouvée.

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

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.

Set attribution and OneLink parameters

Cet exemple illustre la conversion d'une URL entrante en URL OneLink sortante avec l'attribution AppsFlyer et les paramètres OneLink.

Set additional custom parameters

Cet exemple illustre la conversion d'une URL entrante en URL OneLink sortante avec des paramètres personnalisés supplémentaires (y compris le paramètre af_prt pour les agences).

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

Consultez cet exemple pour découvrir comment désactiver le Smart Script pour une certaine chaîne de l’URL (comme af_r) en créant une liste d'exclusion. Si l'une des chaînes de la liste d'exclusion apparaît dans l'URL du clic, le smart script renvoie alors null.

Smart Script set up with Google Tag Manager

Cet exemple illustre la conversion d'une URL entrante en URL OneLink sortante à l'aide du script intelligent OneLink configuré à l'aide du gestionnaire de balises Google.

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