Tập lệnh Thông minh OneLink V2

Khát quát: Tùy chỉnh OneLink được tự động tạo và nhúng sau một nút hoặc biểu ngữ trên trang web thương hiệu của bạn.

Giới thiệu về Tập lệnh Thông minh OneLink

Tập lệnh Thông minh OneLink sử dụng các URL gửi đến đưa đến trang web để tự động tạo các URL OneLink gửi đi duy nhất đưa đến cửa hàng ứng dụng.

Các URL gửi đi được tạo bằng cách sử dụng các đối số bạn nhận được từ nhà tiếp thị và nhập vào tập lệnh. Lưu ý: Đối số afParameters có cấu trúc được tạo từ nhiều đối số (thông số) khác, mỗi đối số chứa một đối tượng cấu hình có mã khóa, giá trị ghi đè và giá trị mặc định.

Các bước thực hiện

Để thiết lập Tập lệnh Thông minh, bạn có thể:

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.

Sử dụng mã do trình tạo Tập lệnh Thông minh tạo ra

  1. Nhận tệp tin từ nhà tiếp thị bao gồm tập lệnh, mã khởi tạo và đối số.
  2. Test the script on the Smart Script test page. Ensure the correct outgoing URL is generated.
  3. Làm theo hướng dẫn thử nghiệm và sử dụng kết quả Tập lệnh Thông minh.

Xem ví dụ tích hợp trên Github

Cấu hình tập lệnh theo cách thủ công

  1. Tải xuống tập lệnh.
  2. Nhận các đối số để gọi tập lệnh ánh xạ các thông số gửi đến với các thông số gửi đi từ nhà tiếp thị.
  3. Khởi tạo đối số Tập lệnh Thông minh và đối tượng cấu hình.
  4. tạo URL bằng cách gọi tập lệnh trong HTML web/trang đích bằng phương thức sau:
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters,
  referrerSkipList, // optional
  urlSkipList // optional
})
  1. Làm theo hướng dẫn thử nghiệm và sử dụng kết quả Tập lệnh Thông minh.

Kiểm tra và sử dụng kết quả Tập lệnh Thông minh

  1. Kiểm tra giá trị trả về trong result. Giá trị trả về có thể là:
    • 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. Nếu tập lệnh trả về null, hãy triển khai luồng quy trình mong muốn. Ví dụ: URL hiện tại của web/trang đích không được thay đổi.
      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

Để thiết lập Tập lệnh Thông minh trong Trình quản lý Thẻ của Google:

  1. Confirm that the marketer followed their instructions and placed the Smart Script code into GTM.
  2. Kiểm tra giá trị trả về trong AF_SMART_SCRIPT_RESULT. Giá trị trả về có thể là:
    • URL Onelink gửi đi. Sử dụng giá trị kết quả nếu cần. Ví dụ, để đặt giá trị này dưới dạng liên kết trong CTA trên trang web của bạn.
    • null. Nếu tập lệnh trả về null, hãy triển khai luồng quy trình mong muốn. Ví dụ: URL hiện tại của web/trang đích không được thay đổi.
      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

Để tạo mã QR:

  1. Tạo thẻ div với ID cụ thể trong trang HTML của trang web để lưu trữ mã QR.
    Bạn có thể tạo kiểu cho thẻ div theo cách mong muốn.
  2. After you run the Smart Script and generate a OneLink URL, call the following method displayQrCode

displayQrCode


Chữ ký phương thức

const qrOptions = {
  logo,
  colorCode
}

window.AF_SMART_SCRIPT.displayQrCode(divId, qrOptions)

Đối số đầu vào

LoạiBắt buộcTênMô tảComment
StringdivIDA div tag with a specific ID in your site's HTML page to host the QR code
ObjectKhôngqrOptionsConfiguration 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

LoạiBắt buộcTênMô tảComment
StringKhônglogoA valid image URL or an image data-URIIf the value is invalid, the QR code will be generated without the logo
StringKhôngcolorCodeHex 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.

Điều kiện tiên quyết: Tập lệnh Thông minh V2.2+

Để kích hoạt lượt hiển thị:

  1. Làm theo hướng dẫn để chạy Tập lệnh Thông minh và tạo URL lượt nhấp.
  2. Đảm bảo rằng kết quả là hợp lệ (và không phải null).
  3. Chạy chức năng hiển thị sau:

🚧

A must-do workaround

Please wrap the call to fireImpressionsLink với 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

Đối số

Đối số Nhận xét Ví dụ:
oneLinkURL (bắt buộc)
  • Cung cấp tên miền mẫu OneLink + ID mẫu. Lưu ý: Không phải là URL liên kết tùy chỉnh OneLink!
  • yourbrand.onelink.me/A1b2
  • Ví dụ về tên miền có gắn thương hiệu: click.yourbrand.com/A1b2

afParameters

(bắt buộc)

 

 

 


mediaSource

(bắt buộc)

Đối tượng cấu hình cho nguồn truyền thông

  • Mã khóa: ['incoming_mediasource’' 'utm_source']
  • Giá trị ghi đè: {twitter: 'twitter_int', orig_src: 'new_src'}
  • Giá trị mặc định: ['any_source']

campaign

Đối tượng cấu hình cho chiến dịch

  • Mã khóa: ['incoming_campaign', 'utm_campaign']
  • Giá trị ghi đè: {campaign_name: 'new_campaign_name'}
  • Giá trị mặc định: ['any_campaign_name']

channel

Đối tượng cấu hình cho kênh

  • Mã khóa: ['incoming_channel', 'utm_channel']
  • Giá trị ghi đè: {video: 'new_video'}
  • Giá trị mặc định: ['any_video']

ad

Đối tượng cấu hình cho quảng cáo

  • Mã khóa: ['incoming_ad', 'utm_ad']
  • Giá trị ghi đè: {ad_name: 'new_ad_name'}
  • Giá trị mặc định: ['any_ad_name']
adSet

Đối tượng cấu hình cho bộ quảng cáo

  • Mã khóa: ['incoming_adset', 'utm_adset']
  • Giá trị ghi đè: {'adset_name': 'new_adset_name'}
  • Giá trị mặc định: ['any_adset_name']
deepLinkValue

Đối tượng cấu hình cho deep_link_value

  • Mã khóa: ['product_id', 'page_name']
  • Giá trị ghi đè: {twenty_percent_off: 'thirty_percent_off'}
  • Giá trị mặc định: 'new_offers_page'
afSub1-5

Đối tượng cấu hình cho af_sub[1-5]

 
googleClickIdKey

Nêu rõ cần gọi thông số chứa GCLID là gì.
Lưu ý! Để hiển thị trong báo cáo dữ liệu thô của AppsFlyer, thông số phải là một trong số af_sub[1-5].

 
Các thông số truy vấn (tùy chỉnh) khác
  • Danh sách bất kỳ thông số nào khác mà bạn muốn được đưa vào URL OneLink gửi đi để phân bổ hoặc liên kết sâu, cùng với các đối tượng cấu hình của chúng.
  • Tên của thông số tùy chỉnh được nhà phát triển liệt kê là paramKey trong đối tượng cấu hình.
  • paramKey: 'deep_link_sub1'
  • Mã khóa: ['page_id']
  • Giá trị ghi đè: {page12: 'new_page12'}
  • Giá trị mặc định: '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 Danh sách các chuỗi trong URL cho một lượt nhấp cụ thể (ví dụ: af_r) mà nếu được tìm thấy, sẽ khiến tập lệnh Thông minh trả về null. Điều này có thể hữu ích nếu bạn sử dụng đường dẫn phân bổ của AppsFlyer với af_r để chuyển hướng người dùng đến trang web trên điện thoại di động của bạn và không muốn bị mất dữ liệu từ lượt nhấp ban đầu.  
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.  

Đối tượng cấu hình

Tập lệnh Thông minh OneLink sử dụng các đối số để tạo URL gửi đi dựa trên các thông số của URL gửi đến và các đối số được xác định trong tập lệnh. Đối số afParameters có cấu trúc được tạo thành từ nhiều đối số (thông số) khác được sử dụng để phân bổ và liên kết sâu, mỗi đối số chứa một đối tượng cấu hình có mã khóa, giá trị ghi đè và giá trị mặc định, như được mô tả trong bảng sau.

Đối số Mô tả Ví dụ:
keys
  • Danh sách chuỗi
  • Danh sách các thông số có thể có trong URL gửi đến mà tập lệnh tìm kiếm, giá trị của thông số này được đặt làm giá trị trong URL gửi đi.
  • Tập lệnh tìm kiếm từ trái sang phải và dừng lại ở kết quả khớp đầu tiên.
  • Ví dụ: ['in_channel', 'utm_channel']
  • Đối với thông số kênh trong tập lệnh, tập lệnh tìm kiếm in_channel trong liên kết gửi đến và sử dụng giá trị đó làm giá trị cho kênh.

overrideValues

  • Dictionary {string: string}
  • Đối với các giá trị bạn muốn thay đổi trong liên kết gửi đi, hãy liệt kê các giá trị trong URL gửi đến, cùng với những giá trị bạn muốn thay thế.
  • Tập lệnh thay thế các giá trị thông số của URL gửi đến bằng các giá trị bạn xác định. 

Ví dụ: {'video': 'video_new'}

Đối với thông số kênh trong tập lệnh, bất cứ lúc nào giá trị gửi đến là video, thì tập lệnh sẽ thay đổi giá trị đó thành video_new trên liên kết gửi đi.

defaultValue
  • chuỗi
  • Nêu rõ bạn muốn giá trị "dự phòng" của mình là gì.
  • Nếu một thông số không được tìm thấy từ danh sách mã khóa của bạn, thì giá trị defaultValue sẽ được sử dụng trong URL gửi đi.
  • Bạn có thể áp đặt một giá trị mặc định bằng cách chuyển một danh sách các mã khóa trống.

Ví dụ: ['web_video']

Đối với thông số kênh trong tập lệnh, nếu bạn không tìm thấy thông số in_channel, thì web_video sẽ được sử dụng làm giá trị kênh.

Ví dụ:

Basic attribution

Xem ví dụ về việc chuyển đổi cơ bản một URL gửi đến thành một URL OneLink gửi đi, với một mã khóa duy nhất cho media_source và campaign

Multiple keys

Xem ví dụ về chuyển đổi một URL gửi đến thành một URL OneLink gửi đi, với nhiều mã khóa cho media_source và campaign.

UTM parameters

Xem ví dụ về việc chuyển đổi một URL gửi đến thành một URL OneLink gửi đi, với các thông số UTM cho media_source và campaign.

Override values

Xem ví dụ về việc chuyển đổi một URL gửi đến thành một URL OneLink gửi đi, thay thế giá trị media_source gửi đến.

Default values

Xem ví dụ về việc chuyển đổi một URL gửi đến thành một URL OneLink gửi đi, sử dụng giá trị mặc định khi không tìm thấy giá trị media_source gửi đến.

Forced default values

Xem ví dụ về việc chuyển đổi một URL gửi đến thành một URL OneLink gửi đi, sử dụng giá trị mặc định ngay cả khi tìm thấy giá trị media_source gửi đến.

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

Xem ví dụ về việc chuyển đổi một URL gửi đến thành một URL OneLink gửi đi với phân bổ AppsFlyer và các thông số OneLink.

Set additional custom parameters

Xem ví dụ về việc chuyển đổi một URL gửi đến thành một URL OneLink gửi đi với các thông số tùy chỉnh bổ sung (bao gồm cả thông số af_prt đối với đại lý).

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

Xem ví dụ về cách bạn có thể tắt Tập lệnh Thông minh cho một chuỗi cụ thể trong URL (ví dụ: af_r) bằng cách tạo danh sách bỏ qua. Nếu có bất kỳ chuỗi nào trong danh sách bỏ qua xuất hiện trong URL của lượt nhấp, thì Tập lệnh Thông minh sẽ trả về null.

Smart Script set up with Google Tag Manager

Xem ví dụ về việc chuyển đổi một URL gửi đến thành một URL OneLink gửi đi bằng Tập lệnh Thông minh OneLink được thiết lập bằng Trình quản lý Thẻ của 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 với 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 với 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.