OneLink Smart Script V2

Краткий обзор. Настраивайте ссылки OneLink, которые автоматически создаются и встраиваются в кнопку или баннер на сайте бренда.

Описание OneLink Smart Script

OneLink Smart Script использует входящие ссылки, ведущие на веб-страницу, для автоматического создания уникальных исходящих ссылок OneLink, ведущих в магазин приложений.

Исходящие URL-адреса генерируются на основе аргументов, которые вы, получив от маркетолога, указали в скрипте. Примечание. Аргумент afParameters состоит из нескольких аргументов (параметров), каждый из которых содержит объект конфигурации с ключами, значениями переопределения и значением по умолчанию.

Шаги реализации

Настроить Smart Script можно следующими способами:

Embed the script in your website

Инициализация и вызов кода Smart Script могут быть либо получены из генератора Smart Script на дэшборде AppsFlyer (рекомендуется), либо импортированы и вызваны разработчиком вручную.

📘

Сохранение параметров входящего URL

Для сопоставления параметров входящего URL со сгенерированной ссылкой OneLink рекомендуется импортировать Smart Script в каждую страницу сайта, независимо от того, сгенерирована ли на странице ссылка OneLink или нет.

Доступно, начиная с версии 2.5.0.

Более подробную информацию и полный пример см. здесь.

Используйте код, сгенерированный Smart Script

  1. Получите от маркетолога файл, содержащий скрипт, код инициализации и аргументы.
  2. Test the script on the Smart Script test page. Ensure the correct outgoing URL is generated.
  3. Следуйте инструкциям по тестированию и использованию результатов Smart Script.

Смотрите пример интеграции на Github

Вручную настройте скрипт

  1. Скачайте скрипт.
  2. Получите аргументы для вызова скрипта, которые сопоставляют входящие параметры с исходящими, от маркетолога.
  3. Инициализируйте аргументы и объекты конфигурации Smart Script.
  4. Сгенерируйте ссылки, вызвав скрипт в коде HTML веб-страницы / лендинга с помощью следующего метода:
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters,
  referrerSkipList, // optional
  urlSkipList // optional
})
  1. Следуйте инструкциям по тестированию и использованию результатов Smart Script.

Проверьте и используйте результат Smart Script

  1. Проверьте возвращаемое значение в result. Возможные возвращаемые значения:
    • 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. Если скрипт возвращает null, реализуйте желаемый поток для ошибки. Например: текущий URL-адрес веб-страницы/лендинга не изменяется.
      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

Чтобы настроить Smart Script в Google Tag Manager:

  1. Confirm that the marketer followed their instructions and placed the Smart Script code into GTM.
  2. Проверьте возвращаемое значение в AF_SMART_SCRIPT_RESULT. Возможные возвращаемые значения:
    • Исходящий URL Onelink. Используйте полученное значение по мере необходимости. Например, чтобы разместить его в виде ссылки в кнопке CTA на вашем сайте.
    • null. Если скрипт возвращает null, реализуйте желаемый поток для ошибки. Например: текущий URL-адрес веб-страницы/лендинга не изменяется.
      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

Необходимое условие: Smart Script версии 2.6+

📘

Практические рекомендации

  • Настройте QR-код в соответствии с брендом вашего приложения, используя логотип в центре и соответствующий цвет кода
  • QR-код надо показывать, когда пользователи просматривают страницу на настольном компьютере, а когда пользователи используют мобильное устройство, надо показать кнопку со ссылкой.

Чтобы создать QR-код:

  1. Создайте тег div с определенным идентификатором на HTML-странице вашего сайта для размещения QR-кода.
    Вы можете стилизовать тег div по желанию.
  2. После запуска Smart Script и создания URL-адреса OneLink вызовите следующий метод displayQrCode

displayQrCode


Сигнатура метода

const qrOptions = {
  logo,
  colorCode
}

window.AF_SMART_SCRIPT.displayQrCode(divId, qrOptions)

Входные аргументы

ТипОбязательно/Не обязательноИмяОписаниеКомментарий
StringДаdivIDA div с определенным идентификатором на HTML-странице вашего сайта для размещения QR-кода.
ObjectНетqrOptionsОбъект настройки (см. подробности в таблице ниже)Если объект отсутствует, QR-код будет создан без логотипа в цвете по умолчанию

qrOptions object

ТипОбязательно/Не обязательноИмяОписаниеКомментарий
StringНетlogoДействительный URL-адрес изображения или схема URI для данных изображенияЕсли значение недействительно, QR-код будет создан без логотипа
StringНетcolorCodeЦвет QR-кода по шестнадцатеричной системеЕсли значение недействительно, цвет кода будет сброшен на черный цвет по умолчанию

Примеры использования:

  • QR-код без логотипа и без индивидуально настраиваемого цвета Пример Github
  • QR-код с логотипом и индивидуально настраиваемым цветом кода Пример Github

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.

Необходимое условие: Smart Script V2.2+

Чтобы инициировать показ:

  1. Следуйте инструкциям, чтобы запустить Smart Script и сгенерировать URL-адрес клика.
  2. Убедитесь, что результат действителен (а не null).
  3. Запустите следующую функцию показа:

🚧

Обязательное обходное решение

Упакуйте вызов в fireImpressionsLink с setTimeout чтобы убедиться, что есть хотя бы 1 секунда задержки между вызовом 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

Аргументы

Аргумент Примечания Пример
oneLinkURL (обязательно)
  • Предоставьте домен шаблона OneLink + идентификатор шаблона. Внимание! Не URL-адрес настраиваемой ссылки OneLink.
  • yourbrand.onelink.me/A1b2
  • Пример с фирменным доменом: click.yourbrand.com/A1b2

afParameters

(обязательно)

 

 

 


mediaSource

(обязательно)

Объект конфигурации для медиа-источника

  • Ключи: ['incoming_mediasource’' 'utm_source']
  • Значения переопределения: {twitter: 'twitter_int', orig_src: 'new_src'}
  • Значение по умолчанию: ['any_source']

campaign

Объект конфигурации для кампании

  • Ключи: ['incoming_campaign', 'utm_campaign']
  • Значения переопределения: {campaign_name: 'new_campaign_name'}
  • Значение по умолчанию: ['any_campaign_name']

channel

Объект конфигурации для канала

  • Ключи: ['incoming_channel', 'utm_channel']
  • Значения переопределения: {video: 'new_video'}
  • Значение по умолчанию: ['any_video']

ad

Объект конфигурации для объявления

  • Ключи: ['incoming_ad', 'utm_ad']
  • Значения переопределения: {ad_name: 'new_ad_name'}
  • Значение по умолчанию: ['any_ad_name']
adSet

Объект конфигурации для группы объявлений

  • Ключи: ['incoming_adset', 'utm_adset']
  • Значения переопределения: {'adset_name': 'new_adset_name'}
  • Значение по умолчанию: ['any_adset_name']
deepLinkValue

Объект конфигурации для deep_link_value

  • Ключи: ['product_id', 'page_name']
  • Значения переопределения: {twenty_percent_off: 'thirty_percent_off'}
  • Значение по умолчанию: 'new_offers_page'
afSub1-5

Объект конфигурации для 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].

 
Другие (настраиваемые) параметры запроса
  • Перечислите любые другие параметры, которые требуется включить в исходящую ссылку OneLink для атрибуции или диплинкинга, а также объекты конфигурации.
  • Имя настраиваемого параметра указывается разработчиком как paramKey в объекте конфигурации.
  • paramKey: 'deep_link_sub1'
  • Ключи: ['page_id']
  • Значения переопределения: {page12: 'new_page12'}
  • Значение по умолчанию: 'page1'
 
referrerSkipList
Список строк в реферере HTTP для определенного клика (например, Twitter или Meta Ads), при обнаружении которых Smart Script возвращает null. Это может быть полезно для SRN, таких как Twitter и Meta Ads, клики по которым уже регистрируются.  
urlSkipList Список строк в URL-адресе определенного клика (например, af_r), при обнаружении которых Smart Script возвращает null. Может быть полезен, если вы используете ссылку атрибуции AppsFlyer с параметром af_r для перенаправления пользователей на свой мобильный сайт и не хотите потерять данные исходного клика.  
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.  

Объект конфигурации

С помощью аргументов OneLink Smart Script создает исходящую ссылку на основе параметров входящей ссылки и аргументов, определенных в скрипте. Аргумент afParameters состоит из нескольких аргументов (параметров) для атрибуции и диплинкинга, каждый из которых содержит объект конфигурации с ключами, значениями переопределения и значением по умолчанию. Они описаны в следующей таблице.

Аргумент Описание Пример
keys
  • Список строк
  • Список возможных параметров входящей ссылки, которые ищет скрипт для передачи значений в соответствующие параметры исходящей ссылки.
  • Скрипт выполняет поиск слева направо и останавливается при первом совпадении.
  • Пример: ['in_channel', 'utm_channel']
  • Для своего параметра channel скрипт ищет во входящей ссылке значение параметра in_channel.

overrideValues

  • Dictionary {string: string}
  • Для значений, которые требуется изменить в исходящей ссылке, укажите значения из входящей ссылки и то, на что их нужно заменить.
  • Скрипт заменяет значения параметров из входящей ссылки на значения, определенные вами. 

Пример: {'video': 'video_new'}

Найдя во входящей ссылке значение "video" для своего параметра channel, в исходящей ссылке скрипт изменяет его на "video_new".

defaultValue
  • Строка
  • Задайте «резервное» значение.
  • Если параметр из списка ключей не найден, в исходящей ссылке используется значение по умолчанию (defaultValue).
  • Чтобы значение по умолчанию использовалось принудительно, передайте пустой список ключей.

Пример: ['web_video']

Если параметр in_channel не найден, для параметра channel в скрипте будет использоваться значение "web_video".

Примеры

Basic attribution

В следующем примере показано базовое преобразование входящей ссылки в исходящую ссылку OneLink с использованием одного ключа для медиа-источника (media_source) и кампании (campaign).

Multiple keys

В следующем примере показано преобразование входящей ссылки в исходящую ссылку OneLink с использованием нескольких ключей для медиа-источника (media_source) и кампании (campaign).

UTM parameters

В следующем примере показано преобразование входящей ссылки в исходящую ссылку OneLink с использованием параметров UTM для медиа-источника (media_source) и кампании (campaign).

Override values

В следующем примере показано преобразование входящей ссылки в исходящую ссылку OneLink с заменой входящего значения медиа-источника (media_source).

Default values

В следующем примере показано преобразование входящей ссылки в исходящую ссылку OneLink с использованием значения по умолчанию, когда не найдено входящее значение медиа-источника (media_source).

Forced default values

В следующем примере показано преобразование входящей ссылки в исходящую ссылку OneLink с использованием значения по умолчанию, даже когда найдено входящее значение медиа-источника (media_source).

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 .

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 .

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

В следующем примере показано преобразование входящей ссылки в исходящую ссылку OneLink c параметрами атрибуции AppsFlyer и параметрами 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

Смотрите пример, в котором показано, как отключить срабатывание Smart Script для определенных кликов (например, из Twitter или Meta Ads), создав список пропуска. Если какие-либо строки из этого списка появляются в реферере HTTP, Smart Script возвращает значение null.

URL skip list

Смотрите пример, в котором показано, как отключить срабатывание Smart Script для URL-адресов с определенной строкой (например, af_r), создав список пропуска. Если в URL-адресе клика есть какие-либо строки из этого списка, Smart Script возвращает значение null.

Smart Script set up with Google Tag Manager

В следующем примере показано преобразование входящей ссылки в исходящую ссылку OneLink с использованием OneLink Smart Script, настроенного с помощью 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.

🚧

Обязательное обходное решение

Упакуйте вызов в fireImpressionsLink с setTimeout чтобы убедиться, что есть хотя бы 1 секунда задержки между вызовом 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

🚧

Обязательное обходное решение

Упакуйте вызов в fireImpressionsLink с setTimeout чтобы убедиться, что есть хотя бы 1 секунда задержки между вызовом generateOneLinkURL and fireImpressionsLink

Preserve incoming URL parameters across pages

📘

Доступно, начиная с версии 2.5.0.

Входящие параметры (например, utm_source) с целевой страницы не передаются на другие страницы сайта по умолчанию.
Импорт Smart Script в каждую страницу сайта сохраняет параметры входящего URL и позволяет Smart Script использовать их на других страницах.

Здесь можно найти пример использования.

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.