OneLink Smart Script V2

Sekilas : Sesuaikan OneLinks yang dibuat dan disematkan secara otomatis di balik tombol atau spanduk di situs web merek Anda.

Tentang OneLink Smart Script

OneLink Smart Script menggunakan URL masuk yang mengarah ke halaman web untuk secara otomatis menghasilkan URL OneLink keluar unik yang mengarah ke app store.

URL keluar dihasilkan menggunakan argumen yang Anda terima dari pemasar dan dimasukkan ke dalam skrip. Catatan: afParameters argumen memiliki struktur yang terdiri dari beberapa argumen (parameter) lain, masing-masing berisi objek konfigurasi yang memiliki kode, nilai penimpaan, dan nilai default.

Langkah-langkah implementasi

Untuk menyiapkan Smart Script, Anda dapat:

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.

Gunakan kode yang dihasilkan oleh generator Smart Script

  1. Dapatkan file dari pemasar yang menyertakan skrip, kode inisialisasi, dan argumen.
  2. Test the script on the Smart Script test page. Ensure the correct outgoing URL is generated.
  3. Ikuti tes dan gunakan instruksi hasil Smart Script.

Lihat contoh integrasi di Github

Konfigurasikan skrip secara manual:

  1. Unduh skrip .
  2. Dapatkan argumen untuk memanggil skrip yang memetakan parameter masuk ke parameter keluar dari pemasar.
  3. Inisialisasi argumen Smart Script dan objek konfigurasi.
  4. buat URL dengan memanggil skrip di web/halaman arahan HTML menggunakan metode berikut:
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters,
  referrerSkipList, // optional
  urlSkipList // optional
})
  1. Ikuti tes dan gunakan instruksi hasil Smart Script.

Periksa dan gunakan hasil Smart Script

  1. Periksa nilai pengembalian di result. Nilai pengembalian yang mungkin adalah:
    • 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. Jika skrip kembali null, terapkan alur kesalahan yang Anda inginkan. Misalnya: URL yang ada di web/laman arahan tidak diubah.
      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

Untuk menyiapkan Smart Script di Pengelola Google Tag:

  1. Confirm that the marketer followed their instructions and placed the Smart Script code into GTM.
  2. Periksa nilai pengembalian di AF_SMART_SCRIPT_RESULT. Nilai pengembalian yang mungkin adalah:
    • URL Onelink keluar. Gunakan nilai hasil sesuai kebutuhan. Misalnya, untuk menempatkannya sebagai tautan di bawah CTA di situs web Anda.
    • null. Jika skrip kembali null, terapkan alur kesalahan yang Anda inginkan. Misalnya: URL yang ada di web/laman arahan tidak diubah.
      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

Untuk membuat kode QR :

  1. Buat tag div dengan ID tertentu di halaman HTML situs Anda untuk meng-hosting kode QR.
    Anda dapat membuat model tag div sesuai keinginan Anda.
  2. After you run the Smart Script and generate a OneLink URL, call the following method displayQrCode

displayQrCode


Signature metode

const qrOptions = {
  logo,
  colorCode
}

window.AF_SMART_SCRIPT.displayQrCode(divId, qrOptions)

Argumen input

JenisWajibNamaDeskripsiComment
StringYadivIDA div tag with a specific ID in your site's HTML page to host the QR code
ObjectTidakqrOptionsConfiguration 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

JenisWajibNamaDeskripsiComment
StringTidaklogoA valid image URL or an image data-URIIf the value is invalid, the QR code will be generated without the logo
StringTidakcolorCodeHex 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.

Prasyarat: Smart Script V2.1+

Untuk mengaktifkan tayangan :

  1. Ikuti petunjuk untuk menjalankan Smart Script dan menghasilkan URL klik.
  2. Pastikan hasilnya valid (dan bukan null).
  3. Jalankan fungsi tayangan berikut:

🚧

A must-do workaround

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

Argumen

Argumen Catatan Contoh
oneLinkURL [wajib]
  • Berikan domain template OneLink + ID template. Catatan: Bukan URL tautan khusus OneLink!
  • yourbrand.onelink.me/A1b2
  • Contoh domain bermerek: click.yourbrand.com/A1b2

afParameters

(wajib)

 

 

 


mediaSource

(wajib)

Objek konfigurasi untuk sumber media

  • Kode: ['incoming_mediasource'' 'utm_source']
  • Nilai penimpaan: {twitter: 'twitter_int', orig_src: 'new_src'}
  • Nilai default: ['any_source']

campaign

Objek konfigurasi untuk kampanye

  • Kode: ['incoming_campaign', 'utm_campaign']
  • Nilai penimpaan: {campaign_name: 'new_campaign_name'}
  • Nilai default: ['any_campaign_name']

channel

Objek konfigurasi untuk saluran

  • Kode: ['saluran_masuk', 'saluran_utm']
  • Nilai penimpaan: {video: 'new_video'}
  • Nilai default: ['any_video']

ad

Objek konfigurasi untuk iklan

  • Kode: ['incoming_ad', 'utm_ad']
  • Nilai penimpaan: {ad_name: 'new_ad_name'}
  • Nilai default: ['any_ad_name']
adSet

Objek konfigurasi untuk adset

  • Kode: ['incoming_adset', 'utm_adset']
  • Nilai penimpaan: {'adset_name': 'new_adset_name'}
  • Nilai default: ['any_adset_name']
deepLinkValue

Objek konfigurasi untuk deep_link_value

  • Kode: ['product_id', 'page_name']
  • Nilai override: {twenty_percent_off: 'thirty_percent_off'}
  • Nilai default: 'new_offers_page'
afSub1-5

Objek konfigurasi untuk af_sub[1-5]

 
googleClickIdKey

Smart Script automatically maps the incoming GCLID parameter value to the outgoing GCLID parameter: gclid={gclid}.
Note! To display in AppsFlyer raw data reports, the param must be one of af_sub[1-5].

 
Parameter kueri (khusus) lainnya
  • Daftar parameter lain yang ingin Anda sertakan dalam URL OneLink keluar untuk atribusi atau deep linking, bersama dengan objek konfigurasinya.
  • Nama parameter khusus dicantumkan oleh pengembang sebagai paramKey di objek konfigurasi.
  • paramKey: 'deep_link_sub1'
  • Kode: ['page_id']
  • Nilai override: {page12: 'new_page12'}
  • Nilai default: 'halaman1'
 
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 Daftar string dalam URL untuk klik tertentu (misalnya af_r) yang jika ditemukan, menyebabkan Smart Script mengembalikan null. Ini dapat berguna jika Anda menggunakan tautan atribusi AppsFlyer dengan af_r untuk mengarahkan pengguna ke situs web seluler, dan tidak ingin data dari klik aslinya hilang.  
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.  

Objek konfigurasi

OneLink Smart Script menggunakan argumen untuk menghasilkan URL keluar berdasarkan parameter URL masuk dan argumen yang ditentukan dalam skrip. Argumen afParameters memiliki struktur yang terdiri dari beberapa argumen (parameter) lain yang digunakan untuk atribusi dan deep linking, yang masing-masing berisi objek konfigurasi yang memiliki kode, nilai penimpaan (override), dan nilai default, seperti yang dijelaskan dalam tabel berikut.

Argumen Deskripsi Contoh
keys
  • Daftar string
  • Daftar kemungkinan parameter di URL masuk yang dicari skrip, yang nilainya ditempatkan sebagai nilai di URL keluar.
  • Script mencari dari kiri ke kanan dan berhenti pada kecocokan yang pertama.
  • Contoh: ['in_channel', 'utm_channel']
  • Untuk parameter saluran dalam skrip, skrip mencari tautan masuk untuk in_channel dan menggunakan nilai sebagai nilai untuk saluran.

overrideValues

  • Dictionary {string: string}
  • Untuk nilai yang ingin Anda ubah di tautan keluar, buat daftar nilai di URL masuk, selain apa yang Anda inginkan untuk menggantinya.
  • Skrip menggantikan nilai parameter dari URL yang masuk dengan nilai yang Anda tentukan. 

Contoh: {'video': 'video_new'}

Untuk parameter saluran dalam skrip, setiap kali nilai yang masuk adalah video, skrip mengubahnya menjadi video_new pada tautan keluar.

defaultValue
  • String
  • Nyatakan nilai "fallback" yang Anda inginkan.
  • Jika parameter tidak ditemukan dari daftar kode Anda, nilai defaultValue digunakan di URL keluar.
  • Anda dapat memaksa nilai default dengan memberikan daftar kode kosong.

Contoh: ['web_video']

Untuk parameter saluran dalam skrip, jika parameter in_channel tidak ditemukan, web_video digunakan sebagai nilai saluran.

Contoh

Basic attribution

Lihat contoh konversi dasar URL masuk ke URL OneLink keluar, dengan satu kode untuk media_source dan kampanye

Multiple keys

Lihat contoh konversi URL masuk ke URL OneLink keluar, dengan beberapa kode untuk media_source dan kampanye.

UTM parameters

Lihat contoh konversi URL masuk ke URL OneLink keluar, dengan parameter UTM untuk media_source dan kampanye.

Override values

Lihat contoh konversi URL masuk ke URL OneLink keluar, menggantikan nilai media_source masuk.

Default values

Lihat contoh konversi URL masuk ke URL OneLink keluar, menggunakan nilai default saat nilai media_source masuk tidak ditemukan.

Forced default values

Lihat contoh konversi URL masuk ke URL OneLink keluar, menggunakan nilai default bahkan ketika nilai media_source masuk ditemukan.

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

Lihat contoh dari konversi URL masuk ke URL OneLink keluar dengan atribusi AppsFlyer dan parameter OneLink.

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

Lihat contoh dari bagaimana Anda dapat menonaktifkan Smart Script untuk string tertentu di URL (contoh, af_r) dengan membuat daftar lewati. Jika salah satu string dalam daftar lewati muncul di URL klik, Smart Script kembali null.

Smart Script set up with Google Tag Manager

Lihat contoh konversi URL masuk ke URL OneLink keluar menggunakan OneLink Smart Script yang disiapkan menggunakan 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 dengan 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 dengan 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.