Руководство по интеграции веб-SDK PBA

<script>
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" } };
  window.AF.plugins = {};

  // Inject SDK
  var o = document.createElement("script"),
      p = document.getElementsByTagName("script")[0];
  o.async = 1;
  o.src = "https://websdk.appsflyersdk.com?" + "st=pba&af_id=WEB_DEV_KEY";
  p.parentNode.insertBefore(o, p);
</script>

<script>
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" }, banners: { key: "YOUR_BANNER_KEY" } };
  window.AF.plugins = {};

  // Inject SDK
  var o = document.createElement("script"),
      p = document.getElementsByTagName("script")[0];
  o.async = 1;
  o.src = "https://websdk.appsflyersdk.com?" + "st=pba,banners&af_id=WEB_DEV_KEY";
  p.parentNode.insertBefore(o, p);
  AF('banners', 'showBanner');
</script>

<script>
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" } };
  window.AF.plugins = {};

  // Manifest loader config
  window.AF_LOADER_CONFIG = {
    baseUrl: "https://websdk.appsflyersdk.com",
    plugins: ["pba"]
  };

  // Inject manifest loader
  var loaderScript = document.createElement("script");
  loaderScript.src = "https://websdk.appsflyersdk.com/manifestLoader.v1.js";
  loaderScript.integrity = "sha384-Uncl2YwvjFpFz0PwEfl3bL/0JsOQcDFEpwXHzcN0MBavn9vvFEx5pZxADTq8h+CV";
  loaderScript.crossOrigin = "anonymous";
  loaderScript.async = true;
  document.head.appendChild(loaderScript);
</script>

<script>
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" }, banners: { key: "YOUR_BANNER_KEY" } };
  window.AF.plugins = {};

  // Manifest loader config
  window.AF_LOADER_CONFIG = {
    baseUrl: "https://websdk.appsflyersdk.com",
    plugins: ["banners", "pba"]
  };

  // Inject manifest loader
  var loaderScript = document.createElement("script");
  loaderScript.src = "https://websdk.appsflyersdk.com/manifestLoader.v1.js";
  loaderScript.integrity = "sha384-Uncl2YwvjFpFz0PwEfl3bL/0JsOQcDFEpwXHzcN0MBavn9vvFEx5pZxADTq8h+CV";
  loaderScript.crossOrigin = "anonymous";
  loaderScript.async = true;
  document.head.appendChild(loaderScript);
</script>

Соображения и необходимые действия

Прежде чем начать:

• Уточните у маркетолога, что он создал пакет бренда. 
• Дополнительные указания см. в руководстве по интеграции PBA.
• Обратите внимание: Если у вас уже установлен автономный Web-SDK Smart Banners, удалите его и замените Web-SDK, который поддерживает и Smart Banners, и People-based Attribution (PBA); не добавляйте отдельный Web-SDK только для PBA. 

Выполните следующие действия:

• Получите веб-ключ разработчика для веб-SDK. Примечание! Это не тот же ключ, который используется мобильными приложениями.
  • Чтобы получить веб-ключ разработчика: 
    1. В AppsFlyer в верхнем меню выберите вкладку Мои приложения.
    2. Нажмите Просмотреть пакет бренда.
    3. Скопируйте необходимый веб-ключ разработчика. (WEB_DEV_KEY)
• Если вы используете смарт-баннеры, получите ключ смарт-баннера. 
  • Чтобы получить ключ смарт-баннера:
    1. В AppsFlyer в боковом меню перейдите в раздел Вовлечение > Web to App > Smart Banners.
    2. Скопируйте необходимый ключ смарт-баннеров.  
• Разрешения на добавление скриптов в теги head на сайте.
• Если вы используете Google Менеджер тегов, он должен быть интегрирован в сайт.

Перейдите к интеграции веб-SDK с помощью одного из следующих вариантов. 

После установки проверьте, что веб-SDK AppsFlyer вызывается браузером посетителя и что сообщения отправляются. Это делается путем проверки сообщения о сетевом соединении, о котором сообщается в браузере.

Чтобы убедиться, что пакет SDK загружается и работает:

1. Перейдите на сайт.

2. Откройте инструменты разработчика в браузере.

   

3. Перейдите на вкладку (A) Сеть.  
4. Обновите страницу.
5. Отфильтруйте по (B) wa.appsflyer.
6. Выберите (C) сообщение о событиях.
7. На вкладке Headers (D):
   • URL-адрес запроса — wa.appsflyer.com/events.
   • site_id query parameter= WEB_DEV_KEY.
   • (E) код статуса 200.
8. Убедитесь, что значение site_id равно значению WEB_DEV_KEY в настройках пакета бренда:
   1. В AppsFlyer в боковом меню выберите Настройки > Пакеты бренда.
   2. Нажмите на веб-ключ разработчика, чтобы скопировать его.
   3. Вставьте ключ в любое место (новая вкладка браузера, блокнот), чтобы отобразить ключ.
   4. Убедитесь, что site_id и WEB_DEV_KEY совпадают. 
9. Убедитесь, что пакет SDK загружается только один раз. Многократная загрузка SDK может привести к тому, что SDK перестанет работать.

Веб-SDK отправляет данные о событиях посетителей в AppsFlyer. Вы можете управлять, останавливать или запускать отправку событий, как описано в этом разделе. 

Обратите внимание:

• Настройка начального состояния SDK: Определяет, отправляет ли SDK события при первоначальной загрузке страницы или должен ждать, пока вы не дадите явную команду, чтобы начать отправку событий. Настройка содержится в веб-фрагменте.
• Явный контроль: Используется, чтобы остановить или начать отправку событий. Например, если вы реализуете баннеры согласия/отказа предоставления данных (также известные как баннеры согласия на использование файлов cookie), интегрируйте явные команды в элементы управления баннером, чтобы запускать и останавливать отправку событий. Явный контроль имеет приоритет над настройкой начального состояния SDK и использует постоянные файлы cookie первой стороны со следующими характеристиками:
  • Устанавливается на домене сайта.
  • Срок действия истекает по истечении периода, установленного веб-SDK или определенного браузером. После истечения срока действия файлов cookie веб-SDK возвращается к исходным настройкам состояния.
  • Файл cookie Web-SDK не вмешивается в настройки файлов cookie, задаваемые в браузере, и всегда подчиняется им.
     

Настройка начального состояния SDK

Явный контроль

Если вашему сайту требуются строгие протоколы безопасности или конфиденциальности данных, используйте следующие механизмы, чтобы настроить взаимодействие Web-SDK с вашей средой и данными.

Политика безопасности контента (CSP)

Если ваш сайт требует, чтобы JavaScript был защищен CSP, Web SDK поддерживает два подхода в зависимости от вашей конфигурации CSP.

• CSP с директивой self Добавьте https://websdk.appsflyersdk.com в ваш script-src белый список. Это работает как для Стандартного Web SDK, так и для Расширенной проверки SDK.
• CSP с использованием nonce: Если ваша политика использует script-src 'nonce-...', вы можете использовать вариант расширенной проверки SDK с nonce. Это передает nonce всем трем тегам скриптов, необходимым для процесса проверки. Замените {{CSP_NONCE}} на сгенерированное сервером уникальное значение nonce для каждого запроса.

Таблица ниже показывает, какие политики CSP совместимы с вариантом с расширенным nonce.

Расширенная проверка SDK с фрагментами CSP nonce

<script nonce="{{CSP_NONCE}}">
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" } };
  window.AF.plugins = {};

  // Manifest loader config — nonce forwarded to the injected SDK <script> tag
  window.AF_LOADER_CONFIG = {
    baseUrl: "https://websdk.appsflyersdk.com",
    plugins: ["pba"],
    nonce: "{{CSP_NONCE}}"
  };

  // Inject manifest loader
  var loaderScript = document.createElement("script");
  loaderScript.src = "https://websdk.appsflyersdk.com/manifestLoader.v1.js";
  loaderScript.integrity = "sha384-Uncl2YwvjFpFz0PwEfl3bL/0JsOQcDFEpwXHzcN0MBavn9vvFEx5pZxADTq8h+CV";
  loaderScript.crossOrigin = "anonymous";
  loaderScript.nonce = "{{CSP_NONCE}}";
  loaderScript.async = true;
  document.head.appendChild(loaderScript);
</script>

<script nonce="{{CSP_NONCE}}">
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" }, banners: { key: "YOUR_BANNER_KEY" } };
  window.AF.plugins = {};

  // Manifest loader config — nonce forwarded to the injected SDK <script> tag
  window.AF_LOADER_CONFIG = {
    baseUrl: "https://websdk.appsflyersdk.com",
    plugins: ["banners", "pba"],
    nonce: "{{CSP_NONCE}}"
  };

  // Inject manifest loader
  var loaderScript = document.createElement("script");
  loaderScript.src = "https://websdk.appsflyersdk.com/manifestLoader.v1.js";
  loaderScript.integrity = "sha384-Uncl2YwvjFpFz0PwEfl3bL/0JsOQcDFEpwXHzcN0MBavn9vvFEx5pZxADTq8h+CV";
  loaderScript.crossOrigin = "anonymous";
  loaderScript.nonce = "{{CSP_NONCE}}";
  loaderScript.async = true;
  document.head.appendChild(loaderScript);
</script>

Если параметры запроса содержат данные, которые AppsFlyer не должен для вас регистрировать, вы можете указать платформе AppsFlyer отбрасывать некоторые или все параметры запроса. В таком случае они недоступны ни в сырых данных, ни в отчетах.  

Вы можете реализовать описанные методы в отношении url, рефереров и header_referer.

Параметры сброса запросов

• Пользовательские события записываются SDK, который отправляет событие на платформу AppsFlyer.
• Используя список событий конверсии, заданный маркетологом, AppsFlyer разбивает события на стандартные и события конверсии.
• Данные о событиях конверсии доступны на дэшбордах PBA.
• Данные о конверсиях и стандартных событиях доступны в отчетах по сырым данным.

События конверсии

• События конверсии дают представление о ваших маркетинговых и бизнес-усилиях. К событиям конверсии относятся покупки, загрузки, регистрации и подписки.
• PBA атрибутирует события конверсии к медиа-источнику, который побудил пользователя посетить веб-сайт.
• Определив атрибутированный медиа-источник, вы можете измерить и дифференцировать качество пользователей, привлеченных разными медиа-источниками.
• События конверсии используются для учета дохода и расчета ROI.
• Используйте их для сравнения бюджета рекламы для конкретных медиа-источников с доходом, полученным от пользователей, которые приходят из этих медиа-источников.

Стандартные события

• Стандартные события используются для проверки пути пользователя и воронок, которые приводят к конверсиям.
• Используйте их для измерения активности пользователей и выделения медиа-источников, которые привлекают вовлеченных пользователей.
• Записывайте действия пользователей, чтобы помечать их для кампаний по повторному вовлечению.

Запись событий

Запускайте веб-SDK для записи событий при выполнении определенных условий, например, при загрузке целевой страницы или при взаимодействии пользователей с элементами сайта. Смотрите примеры записи событий.

• Веб-пользователи идентифицируются в AppsFlyer с помощью уникального CUID, который вы им выделяете. Как правило, CUID управляется внутренними серверами. 
• Используйте то же значение CUID, которое вы используете в мобильной среде. Это позволяет получить целостное представление об активности пользователей на нескольких платформах. Функция в мобильном SDK – это функция setCustomerUserId (iOS, Android, Unity).
• Чтобы задать CUID в веб-SDK:
  • Установите CUID в самой ранней точке, когда у вас есть к нему доступ. В большинстве случаев это означает, что вам нужно подождать, пока пользователь пройдет идентификацию через вход или регистрацию.
  • Запустите вызов JavaScript для setCustomerUserId(), как показано в следующем примере.
    Примечание! Отправляйте CUID в виде строки, даже если это число. Сделайте это, заключив его в кавычки.
• Если вы реализуете веб-S2S, учтите, что вам может потребоваться уведомить PBA, когда вы связываете CUID с идентификатором веб-посетителя в вашем бэкенде.
• CUID не должен содержать персональную информацию, позволяющую установить личность, такую как номер телефона или адрес электронной почты.

Пример: задайте CUID

// Associate all current user web events to distinct ID 663274 
AF('pba', 'setCustomerUserId' , '663274')

Пример события

// purchase event of shoes with associated revenue
AF('pba', 'event', {eventType: 'EVENT', eventName: 'purchase', eventRevenue: 12, eventValue: {"key1": 123, "key2": "name"}});

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

Интернет-магазин

Предположим, вы управляете интернет-магазином. Вот некоторые стандартные события, которые вы, возможно, захотите записать: 

• Поиск: стандартное событие
• Добавить в корзину: стандартное событие
• Удалить из корзины: стандартное событие
• Покупка: событие конверсии

Новостное издание

Предположим, вы управляете новым новостным изданием. Вот некоторые события, которые вы можете записать:

• Регистрация: событие конверсии
• Покупка подписки: событие конверсии

Эта часть предназначена для веб-разработчиков.

Тестирование интеграции веб-SDK для PBA: просмотрите тестовые события в режиме реального времени.

Чтобы убедиться, что события отправляются в AppsFlyer:

1. Откройте веб-сайт.
2. Откройте инструменты разработчика браузера.
   • Как открыть инструменты разработчика в Chrome
   • Как открыть инструменты разработчика в Safari
3. Перейдите на вкладку Network (Сеть).
4. Запустите событие.

5. Фильтр по сообщениям.

   

6. Найдите сетевой запрос, начинающийся с wa.appsflyer.com (см. скриншот ниже).
7. Убедитесь, что:
   1. Код состояния — 200.
   2. Полезные данные запроса согласуются с параметрами события.

Приведенный код носит иллюстративный характер. Не используйте этот код как есть. 

• Предположения: Веб-SDK уже загружен страницей к моменту отправки события.
• Примеры сценариев содержат код для записи событий в следующих случаях: 
  • Загружается целевая страница.
  • Пользователи взаимодействуют с веб-сайтом.

<html>
    <head>
        <!-- Assume that the server returns a response with details about the newly subscribed user -->
        <!-- Alternatively, you can extract data from localStorage or cookies,
            in case data was set in either of them during the subscription process
        -->
        <script>window.onload = function(){
            AF('pba', 'event', {eventType: 'EVENT', eventValue: {'category': 'holiday_promotion', eventValue: {'label' : 'newspaper'}, eventName: 'subscription',}); } </script> </head> <body> <h1>Thank You for Subscribing to Our Newsletter</h1> </body> </html>

<html>
<head>
    <!-- Assume that data about products in the shopping cart
    is stored in localStorage -->
    <script>
        window.onload = function () {
            document.getElementById('checkout').addEventListener('click', function () {
                AF('pba', 'event', {eventType: 'EVENT', eventValue: {'category' : 'holiday_promotion'}, eventName: 'checkout'});
            });
        }
    </script>
</head>
<body>
    <h1>Shopping Cart</h1>
    <h2>Shirt</h2>
    <p>
        <ul>
            <li>Color: Blue</li>
            <li>Quantity: 2</li>
            <li>Price: $20</li>
        </ul>
    </p>
    <h2>Pants</h2>
    <p>
        <ul>
            <li>Color: Black</li>
            <li>Quantity: 3</li>
            <li>Price: $15</li>
        </ul>
    </p>
    <button id='checkout'>Checkout</button>
</body>
</html>

• Убедитесь, что тег функций веб-SDK загружен перед запуском события.
• Не отправляйте специальные символы в значениях событий, например символы валюты в значении дохода.
• Строки значений должны быть короче 50 символов.

Код, приведенный в этих примерах, приведен только для справки. Не используйте этот код как есть. Если вы не знаете, как использовать этот код, проконсультируйтесь со своим веб-разработчиком. 

Предположение: Веб-SDK загружается страницей перед отправкой события; не загружайте SDK повторно.

Сценарий пользователя:

• Пользователь регистрируется на вашем сайте.
• Код сайта собирает данные о пользователе и отправляет их на ваш сервер.
• Сервер генерирует уникальный CUID для пользователя.
• На странице благодарности после регистрации вы запрашиваете у сервера новый CUID.
• Используя ответ сервера, вы устанавливаете CUID AppsFlyer с помощью метода веб-SDK setCustomerUserId().

<html>
<head>
    <!-- The Web SDK script loads first -->
    <script>
!function(t,e,n,s,a,c,i,o,p){t.AppsFlyerSdkObject=a,t.AF=t.AF||function(){
(t.AF.q=t.AF.q||[]).push([Date.now()].concat(Array.prototype.slice.call(arguments)))},
t.AF.id=t.AF.id||i,t.AF.plugins={},o=e.createElement(n),p=e.getElementsByTagName(n)[0],o.async=1,
o.src="https://websdk.appsflyersdk.com?"+(c.length>0?"st="+c.split(",").sort().join(",")+"&":"")+(i.length>0?"af_id="+i:""),
p.parentNode.insertBefore(o,p)}(window,document,"script",0,"AF","pba",{pba: {webAppId: "WEB_DEV_KEY"}})
    </script>
    <script>
        };
    // This function stores the user email sent to the server after the user reaches the thank you page
    // The response from the server is a unique CUID that should be set using the web SDK setCustomerUserId method
        function storeUserEmail (){
            var userEmail = document.getElementById('email').value;
            localStorage.setItem('user_email', userEmail);
        }
    </script>
</head>
<body>
    <h1>Sign Up</h1>
    <form onsubmit="storeUserEmail()" action="/signup" method="post">
        <div><label>Name</label>
            <input type="text" name="name" id="name"></div>
        <br />
        <div> <label>Email</label>
            <input type="email" name="email" id="email"></div>
        <br />
        <input type="submit" id="submit">
    </form>
</body>
</html>

<html>
<head>
    <script>
!function(t,e,n,s,a,c,i,o,p){t.AppsFlyerSdkObject=a,t.AF=t.AF||function(){
(t.AF.q=t.AF.q||[]).push([Date.now()].concat(Array.prototype.slice.call(arguments)))},
t.AF.id=t.AF.id||i,t.AF.plugins={},o=e.createElement(n),p=e.getElementsByTagName(n)[0],o.async=1,
o.src="https://websdk.appsflyersdk.com?"+(c.length>0?"st="+c.split(",").sort().join(",")+"&":"")+(i.length>0?"af_id="+i:""),
p.parentNode.insertBefore(o,p)}(window,document,"script",0,"AF","pba",{pba: {webAppId: "WEB_DEV_KEY"}})
    </script>
    <script>
        // Using the fetch API to send the user email to the server
        // and get the unique user id in return	
        window.onload = function () {
            var userEmail = localStorage.getItem('user_email');
            fetch('users/' + userEmail).then(function (res) {
                   res.text().then(function (id) {
                    console.log(id);
                    AF('pba', 'setCustomerUserId', id);
                });
            });
        }  </script> 
     </head> 
     <body> 
        <h1>Thank You for Signing Up!</h1> 
     </body> 
</html>

Функция setCustomerUserId может быть отправлена на любом этапе пользовательского потока, например, после входа и регистрации пользователя. AppsFlyer использует самый последний отправленный CUID, чтобы обновить для текущего наблюдаемого пользователя прошлые или будущие точки взаимодействия и события.

Используйте то же значение CUID, что и в функции setCustomerUserd в мобильном приложении (см. мобильный setCustomerUserId для: iOS, Android, Unity).

Файлы cookie, перечисленные в следующей таблице, устанавливаются или используются в веб-SDK на вашем сайте.  

В таблице используются следующие сокращения:

• AMP: Технология ускоренных мобильных страниц (Accelerated Mobile Pages) 
• CDN: Сеть доставки контента (Content Delivery Network)
• 3PC: Сторонние файлы cookie (Third-party Cookies)

• Уведомление о прекращении поддержки предупреждает о нашем намерении прекратить поддержку функции или метода. Функция или метод продолжает работать до даты деактивации.
• Рассматривайте уведомления о прекращении поддержки как возможность внести изменения в код.