Внедрение кода смарт-баннеров на сайт (для разработчиков)

Для:

разработчиков

Последнее обновление: 11/07/2023 14:33

Краткий обзор. Добавьте на сайт SDK для смарт-баннеров, чтобы маркетологи могли конвертировать посетителей сайта в пользователей мобильного приложения.

Материалы по теме

Чтобы получить полное представление о работе со Смарт-баннерами, ознакомьтесь со следующими статьями:

Смарт-баннеры: mobile web-to-app (для маркетологов)
Внедрение кода смарт-баннеров на сайт (для маркетологов)
Внедрение кода смарт-баннеров на сайт (для разработчиков) [эта статья]
Решения для атрибуции mobile web-to-app
Интеграция PBA со смарт-баннерами

Примечание

С 1 октября 2023 г. веб-SDK для смарт-баннеров AppsFlyer v1 будет считаться устаревшим. Узнать больше

Обзор

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

Поэтому SDK для смарт-баннеров должен быть доступен со всех страниц, на которых отображаются ваши мобильные баннеры.

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

Фрагмент кода

Примечание

С 1 января 2020 года SDK для смарт-баннеров позволяет использовать на сайте и смарт-баннеры, и атрибуцию People-Based. Ниже приведены два примера фрагментов кода SDK:

Если у вас уже есть отдельный веб-SDK PBA, удалите его и замените на веб-SDK как для смарт-баннеров, так и для атрибуции People-based; не добавляйте отдельный веб-SDK для смарт-баннеров.

Включите этот фрагмент кода в тег <head> каждой страницы, на которой отображаются ваши мобильные баннеры.

Веб-SDK AppsFlyer только для смарт-баннеров

Вместо заполнителя YOUR_WEB_KEY укажите в скрипте свой веб-ключ. Этот веб-ключ формируется при создании новой рабочей области сайта.
Вставьте этот фрагмент кода в тег head сайта. В теге 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.appsflyer.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","banners",{banners: {key: "YOUR_WEB_KEY"}});

// Для смарт-баннеров по умолчанию задается максимальное значение z-index, чтобы их не перекрывали другие элементы сайта. Это можно изменить, если вы хотите, чтобы некоторые компоненты сайта отображались поверх баннера.
 
AF('banners', 'showBanner', { bannerZIndex: 1000, additionalParams: { p1: "v1", p2: "v2"}});

</script>

Веб-SDK AppsFlyer для смарт-баннеров и атрибуции People-Based

Вместо заполнителя YOUR_WEB_KEY укажите в скрипте свой веб-ключ. Этот веб-ключ формируется при создании новой рабочей области сайта.
Вместо заполнителя YOUR_PBA_KEY укажите в скрипте свой веб-ключ разработчика. Этот веб-ключ формируется при создании пакета брендов.
Вставьте этот фрагмент кода в тег head сайта. В теге 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.appsflyer.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,banners",{pba: {webAppId: "YOUR_PBA_KEY"}, banners: {key: "YOUR_WEB_KEY"}});

// Для смарт-баннеров по умолчанию задается максимальное значение z-index, чтобы их не перекрывали другие элементы сайта. Это можно изменить, если вы хотите, чтобы некоторые компоненты сайта отображались поверх баннера.

AF('banners', 'showBanner', { bannerZIndex: 1000, additionalParams: { p1: "v1", p2: "v2"}});

</script>

        <script>
          !function(e,n,t){!function(e,n,t,r,a){
          var s=(e[n]=e[n]||{})[t]=function(){(s._q=s._q||[]).push(Array.prototype.slice.call(arguments))};
          s.webkey=a;
          for(var i=0;i<r.length;i++)
          s[r[i]]=function(n)
          {return function()
          {var e=Array.prototype.slice.call(arguments);
          return e.unshift(n),(s._q=s._q||[]).push(e),s}}
          (r[i])}(e,"AF","Banner",["showBanner","hideBanner","disableBanners","disableTracking","setAdditionalParams"],t),
          function(e,n,t){var r=e.createElement("script");
          r.type="text/javascript",r.async=!0,r.src=n+(t?"?webkey="+t:"");
          var a=e.getElementsByTagName("script")[0];
          a.parentNode.insertBefore(r,a)}(n,"https://cdn.appsflyer.com/web-sdk/banner/latest/sdk.min.js",t)}(window,document,"YOUR-BANNER-KEY");
          // Для смарт-баннеров по умолчанию задается максимальное значение z-index, чтобы их не перекрывали другие элементы сайта. Это можно изменить, если вы хотите, чтобы некоторые компоненты сайта отображались поверх баннера.
 
          showBanner({ bannerZIndex: 1000, additionalParams: { p1: "v1", p2: "v2"...}});

          </script>

Функции SDK

showBanner

Назначение:

Начинает показ смарт-баннера в соответствии с ключом баннера, указанным во фрагменте кода.

Примечание. Не используйте эту функцию, если смарт-баннеры реализуются в приложении-обертке или в гибридном приложении для загрузки страницы баннера из приложения (а не из браузера), поскольку при использовании showBanner баннер будет отображаться в приложении. Если вы все же используете showBanner для приложения-обертки или гибридного приложения, применяйте hideBanner для загрузки мобильного приложения.

Параметры (необязательно):

bannerContainerQuery
Если параметр передан, SDK пытается найти элемент на странице с помощью этого запроса и считает его начальной точкой для размещения баннера. В противном случае, используется параметр document.body.
bannerZIndex
Смарт-баннеры по умолчанию настроены с максимальным значением z-index, чтобы их не закрывали элементы сайта. Это можно изменить, если вы хотите, чтобы некоторые элементы сайта были размещены поверх баннера.
additionalParams
Если эти параметры (напр., deep_link_value) переданы, они добавляются как параметры запроса в URL-адрес OneLink.

Пример:

AF('banners', 'showBanner', { bannerContainerQuery: "#container-id",
              bannerZIndex: 1000,              
              additionalParams: { p1: "v1", p2: "v2"...}});

showBanner({ bannerContainerQuery: "#container-id",
              bannerZIndex: 1000,
              additionalParams: { p1: "v1", p2: "v2"...}});

updateParams

Цель

Программное добавление до 10 параметров (напр., deep_link_value) в URL-адрес OneLink, назначенный кнопке с призывом к действию (CTA), после отображения баннера.

Входные данные — это объект с ключами и значениями параметров.

Ключ не может иметь пустое значение.
Ключ нельзя назвать undefined, null, NaN или arg
Недопустимые символы:
- В ключе: /, \, *, !, @, #, ?, $, %, ^, &, ~, `, =, +, ', ", ;, :, >, <
- В значении: = \, ;, $, >, <, ^, #, `

Пример

AF ("banners", "updateParams", {p1: "v1", p2: "v2"...})

Факторы, которые необходимо учитывать

Параметры добавляются как параметры запроса в URL-адрес OneLink.
Когда для добавления параметров вы используете updateParams, URL-адрес показа отличается от URL-адреса клика.
Добавленные параметры не заменяют параметры в исходном URL-адресе OneLink. Если добавляемый параметр уже присутствует в URL-адресе OneLink, он не изменяется.
Если updateParams вызывается более одного раза, к URL-адресу добавляются только параметры из последнего вызова.
Этот метод не работает с устаревшим веб-SDK смарт-баннеров.

hideBanner

Цель

Программно удаляет со страницы любой отображаемый баннер (например, после показа в течение X секунд).

AF('banners', 'hideBanner')

disableBanners (устарела)

Цель

Эта функция доступна только в старом SDK для смарт-баннеров, ее поддержка будет прекращена.

Отключает в веб-SDK показ баннеров и обмен данными с серверами AppsFlyer.

disableTracking (устарела)

Цель

Эта функция доступна только в старом SDK для смарт-баннеров, ее поддержка будет прекращена.

Отключает веб-SDK и удаляет собранную информацию из браузера (например, объекты local-storage, файлы сookie и т. д.)

setAdditionalParams (устарела)

Цель

Эта функция доступна только в старом SDK для смарт-баннеров, ее поддержка будет прекращена.

Задает additionalParams в ссылке OneLink перед вызовом showBanner. Эти параметры добавляются в конец URL-адреса OneLink за баннером.

Параметры

Params
Карта параметров ключ/значение, которые могут переопределять любые ранее существовавшие параметры ссылки атрибуции (помимо значения pid).

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

Требуется провести различие между лэндингами с помощью определенных параметров. Для этого можно добавить к используемой в баннере ссылке OneLink дополнительные параметры. Когда пользователь устанавливает приложение после клика по баннеру, в сырых данных появляются параметры OneLink, и вы можете их проанализировать. В приведенном ниже примере кода используется параметр af_sub1.

// вызывайте этот метод до вызова showBanner()
setAdditionalParameters('af_sub': 'custom_paramter_value')

Окончательная ссылка OneLink будет иметь следующий формат: subdomain.onelink.me/onelink-id?pid=af_banner&c=campaign&af_sub1=custom_paramter_value.

Поддомен и идентификатор OneLink берутся из шаблона OneLink.

For example: ab12.onelink.me/xyz1?pid=af_banner&c=summer_campaign&af_sub1=uk_landing_page.

Вы можете использовать любой допустимый параметр. Подробные сведения о параметрах ссылок атрибуции см. здесь. Убедитесь, что параметры pid и c не переопределены, потому что они уже существуют в используемой баннером ссылке атрибуции.

getAdditionalParams (устарела)

Цель

Эта функция доступна только в старом SDK для смарт-баннеров, ее поддержка будет прекращена.

Позволяет получить текущий объект additionalParams.

Ограничения и особенности

Специфика Примечания

Одностраничное приложение (SPA)

Смарт-баннеры по умолчанию отображаются только один раз, даже если пользователи перемещаются между страницами.

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