Макросы обратного вызова

Макросы — это заполнители для значений, которые динамически изменяются в серверном запросе URL-адреса. Эти макросы предварительно настроены для сетей, интегрированных с Tenjin, однако понимание принципа их работы может пригодиться при добавлении любых пользовательских каналов.

---

Зачем нужны макросы? #

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

Чтобы разобраться в этом, мы расскажем, как в системе Attribution работают URL-адреса, параметры, значения и динамически изменяющиеся значения.

---

URL-адреса и параметры #

Давайте рассмотрим стандартный URL-адрес: https://track.tenjin.com?param1=value1. В этом URL-адресе вы можете увидеть адрес сервера track.tenjin.io и один параметр param1, значение которого установлено на value1. Когда этот URL поступает на сервер track.tenjin.io, сервер Tenjin считывает его и анализирует параметр и значение. В данном случае param1 имеет значение value1.

В качестве более реалистичного примера, касающегося параметров и значений атрибутов, рассмотрим следующий URL с двумя параметрами (рекламный идентификатор и страна) и два значения: https://track.tenjin.com?advertising_id=xyz123&country=US. Когда этот запрос поступает на сервер Tenjin по адресу track.tenjin.com, мы знаем, что рекламный идентификатор устройство, которое подключилось к серверу xyz123 с страна из США.

---

Динамические значения параметров #

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

Чтобы Tenjin мог соотнести пользователя с кликом или показом, при каждом клике или показе Tenjin собирает информацию об устройстве и его свойствах. Эти свойства используются для сопоставления со свойствами, собранными при установке приложения на устройство.

URL-адрес для отслеживания Tenjin генерируется при каждом создании кампании для сети, не входящей в SAN, или для пользовательского канала. Этот URL-адрес для отслеживания содержит “макросы”, которые динамически адаптируются к изменяющимся значениям, связанным с кликом или показом. Макросы используются в качестве заполнителей для значений, которые изменяются в конкретном URL-адресе.

Предположим, вы хотите запустить рекламную кампанию в сети, не входящей в SAN. Вы создаете ссылку для отслеживания через панель управления Tenjin и передаете её своей рекламной сети.

Вот как может выглядеть отслеживающая ссылка от Tenjin:

https://track.tenjin.com?advertising_id={idfa}&country={country}

В данном случае {idfa} и {country} — это макросы. Когда устройство использует эту ссылку, рекламная сеть заполняет эти макросы фактическими значениями, характерными для данного устройства. Если взять предыдущий пример, {idfa} и {country} будет вводить значения с помощью xyz123 и США соответственно.

После заполнения рекламная сеть или канал отправят запрос на сервер Tenjin по следующему URL-адресу:

https://track.tenjin.com?advertising_id=xyz123&country=US

В качестве альтернативы, если устройство пользователя изменилось и у него advertising_id равен abc234, а country — CA, URL изменится на:

https://track.tenjin.com?advertising_id=abc234&country=CA

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

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

Каждая рекламная сеть имеет собственный набор макросов для подсчёта кликов и показов по следующим характеристикам устройств:

• Рекламный идентификатор
• IP-адрес
• Идентификатор комплекта
• Страна
• Идентификатор клика
• Сайт
• Платформа ОС
• Ограничить отслеживание рекламы
• Творчество

Если рекламная сеть предварительно настроена и интегрирована с Tenjin, каждый из макросов рекламной сети будет автоматически отображаться в каждом URL-адресе клика или ссылке для отслеживания показов для каждой кампании.

Например:

• Макрос Axon от AppLovin advertising_id выглядит следующим образом: {IDFA}
• Макрос Tapjoy advertising_id выглядит следующим образом: TAPJOY_ADVERTISING_ID

В результате URL-адреса кликов для Axon от AppLovin и Tapjoy могут выглядеть примерно так:

• Axon от AppLovin: https://track.tenjin.com/v0/id?advertising_id={IDFA}
• Tapjoy: https://track.tenjin.com/v0/id?advertising_id=TAPJOY_ADVERTISING_ID

Повторим: у каждой рекламной сети будет свой собственный формат макросов. Если сеть уже предварительно интегрирована с Tenjin, вам не нужно об этом беспокоиться. Это просто для того, чтобы вы знали, как строятся URL-адреса кликов и показов.

При настройке обратного вызова Tenjin к другому сервису можно использовать макросы для представления динамически изменяющихся значений данных, которые необходимо отправить на другие серверы/сервисы. Это и есть то, что мы называем “маршрутизацией”.

Tenjin позволяет “направлять” данные о текущих событиях на другие серверы в режиме реального времени.

Ниже приведён список доступных макросов обратного вызова, которые можно настроить при отправке данных в другие сервисы.

Макросы, связанные с приложением #

Макро	Пояснение
{{app_version}}	Версия приложения (1.0.3)
{{bundle_id}}	Идентификатор пакета приложения (com.tenjin.wordfinder)
{{lowercase_bundle_id}}	Идентификатор пакета приложения в нижнем регистре (com.tenjin.wordfinder)
{{platform}}	Платформа приложения (iOS)
{{user_agent}}	Агент пользователя
{{sdk_version}}	Версия Tenjin SDK у пользователя
{{store_id}}	Идентификатор приложения в App Store (887212194)

Макросы, связанные с указанием авторства #

Макро	Пояснение
{{acquired_at_s}}	Временная метка события «Установка» в секундах
{{acquired_at_ms}}	Временная метка события «Установка» в миллисекундах
{{engaged_at_s}}	Временная метка события клика или показа в секундах
{{engaged_at_ms}}	Временная метка события клика или показа в миллисекундах
{{ad_network}}	Название канала, к которому отнесен пользователь
{{campaign_id}}	То же самое, что {{remote_campaign_id}}
{{campaign_name}}	Название кампании «Тэндзин», к которой отнесен пользователь
{{campaign_name_encoded}}	Кодовое название кампании «Тэндзин», к которой отнесен пользователь
{{click_id}}	Идентификатор клика канала, если пользователь отнесен к платным каналам
{{creative_name}}	Креативное название
{{deeplink_url}}	URL-адрес диплинка
{{is_conversion_integer}}	1 — при первом запуске приложения, 0 — при других событиях
{{is_impression}}	1 => атрибуция по просмотрам, 0 => атрибуция по кликам
{{is_install_or_landing}}	При первом запуске приложения — “Установка”, при последующих запусках — “Стартовая страница”
{{ip_address}}	IP-адрес пользователя
{{ip_address_click}}	IP-адрес для события «клик» или «показ»
{{remote_campaign_id}}	Идентификатор кампании канала, к которой относится пользователь
{{site_id}}	Идентификатор сайта канала, к которому отнесен пользователь
{{site_id_encoded}}	Идентификатор сайта (Site ID) зашифрованного канала, к которому отнесен пользователь
{{ad_network_short_id_match_type}}	Если пользователь перешел с устройства, атрибуция определяется по вероятности или рефереру. ad_network_short_id — эта часть идентификатора различается для каждой рекламной сети; для получения подробной информации обратитесь к нам.
{{is_organic}}	‘1’ — пользователь отнесен к органическому каналу, ‘0’ — пользователь отнесен к неорганическому каналу
{{tenjin_campaign_id}}	Идентификатор кампании «Тэндзин», к которой отнесен пользователь
{{tenjin_parameter_0}}	С помощью макроса «Pass through» можно передать URL-адрес при нажатии кнопки
{{tenjin_parameter_1}}	С помощью макроса «Pass through» можно передать URL-адрес при нажатии кнопки
{{tenjin_parameter_2}}	С помощью макроса «Pass through» можно передать URL-адрес при нажатии кнопки
{{tenjin_parameter_3}}	С помощью макроса «Pass through» можно передать URL-адрес при нажатии кнопки
{{tenjin_parameter_4}}	С помощью макроса «Pass through» можно передать URL-адрес при нажатии кнопки
{{tenjin_parameter_5}}	С помощью макроса «Pass through» можно передать URL-адрес при нажатии кнопки

Макросы, связанные с идентификатором устройства #

Макро	Пояснение
{{advertising_id}}	Рекламный идентификатор устройства
{{analytics_installation_id}}	Идентификатор, уникальный для установки приложения. Записывается строчными буквами, без дефиса.
{{developer_device_id}}	Идентификатор поставщика (IDFV) или идентификатор устройства разработчика
{{formatted_advertising_id}}	Формат рекламного идентификатора устройства: 00000000-0000-0000-0000-000000000000 в случае, если поле пусто
{{imei}}	IMEI
{{md5_advertising_id}}	MD5-хаш рекламного идентификатора
{{lowercase_advertising_id}}	Регистр (строчные буквы) рекламного идентификатора устройства
{{md5_imei}}	MD5-сумма IMEI
{{md5_oaid}}	MD5-хаш OAID
{{oaid}}	OAID
{{customer_user_id}}	Идентификатор пользователя из приложения, заданный методом setCustomerUserId SDK

Макросы, связанные со свойствами устройства #

Макро	Пояснение
{{allow_ad_tracking}}	Устройство позволяет отслеживать рекламу? (да, нет)
{{allow_ad_tracking_integer}}	Устройство позволяет отслеживать рекламу? (1, 0)
{{carrier}}	Держатель устройства
{{connection_type}}	Тип подключения
{{country}}	Код страны устройства пользователя
{{device}}	Устройство пользователя
{{device_brand}}	Марка устройства
{{device_model}}	Модель устройства
{{language}}	Языковые настройки пользователя
{{limit_ad_tracking}}	Устройство ограничивает отслеживание рекламы? (да, нет)
{{limit_ad_tracking_integer}}	Устройство ограничивает отслеживание рекламы? (1, 0)
{{locale}}	Языковая настройка устройства
{{os_version}}	Версия ОС пользователя
{{os_version_release}}	Версия ОС пользователя
{{referrer}}	Рефералер Android
{{timezone}}	Часовой пояс устройства
{{tracking_status}}	Целое число, характеризующее состояние ATT устройства iOS. 0 => не определено, 1 => ограничено, 2 => отклонено, 3 => разрешено

Макросы, связанные с событиями #

Макро	Пояснение
{{currency}}	3-значный код валюты покупки
{{event}}	Название мероприятия
{{time_in_seconds}}	Время запроса в секундах
{{time_in_ms}}	Время обработки запроса в миллисекундах
{{time_iso8601}}	Время запроса в формате ISO 8601
{{revenue}}	Валовая выручка от покупки в исходной валюте
{{revenue_usd_net}}	Чистая выручка в долларах США от одной покупки
{{revenue_usd_gross}}	Валовая выручка в долларах США за одну покупку
{{value}}	Пользовательское значение события
{{value_micro}}	Значение пользовательского события, деленное на 1 000 000. Этот макрос используется для отправки десятичного значения через функцию обратного вызова: для этого через пользовательское событие отправляется фактическое значение, умноженное на 1 000 000.

Макросы, связанные с показами рекламы #

• AppLovin

Макро	Пояснение
{{ilrd::ad_unit_id}}	Идентификатор рекламного блока, указанный сетью-победителем
{{ilrd::currency}}	Доходы от рекламы в валюте отражаются в
{{ilrd::ad_format}}	Формат рекламного блока
{{ilrd::mediation_country}}	Страна, в которой зарегистрирован посредник
{{ilrd::network_name}}	Сеть, в которой была показана реклама
{{ilrd::ad_revenue}}	Выручка, заявленная рекламной сетью
{{ilrd::network_placement}}	Размещение, определяемое сетью
{{ilrd::placement}}	Размещение рекламного блока
{{ilrd::creative_id}}	Идентификатор рекламного блока
{{ilrd::precision}}	Точность расчета выручки

• Unity LevelPlay

Макро	Пояснение
{{ilrd::ab_test}}	Значение A/B-теста
{{ilrd::ad_format}}	Формат рекламного блока
{{ilrd::ad_revenue}}	Выручка, заявленная рекламной сетью
{{ilrd::auction_id}}	Идентификатор аукциона из системы посредничества Ironsource
{{ilrd::ecpm}}	eCPM от медиации Ironsource
{{ilrd::instance_id}}	Идентификатор экземпляра из медиации Ironsource
{{ilrd::instance_name}}	Название экземпляра из медиации Ironsource
{{ilrd::mediation_country}}	(не используется, будет использоваться макрос «Tenjin country»)
{{ilrd::mediation_ltv}}	Общий доход за весь период от медиации Ironsource
{{ilrd::network_name}}	Сеть, в которой была показана реклама
{{ilrd::placement}}	Размещение рекламного блока
{{ilrd::precision}}	Точность расчета доходов
{{ilrd::segment}}	Название сегмента из медиации Ironsource

• AdMob

Макро	Пояснение
{{ilrd::precision}}	Тип «Precision», определённый AdMob
{{ilrd::ad_unit_id}}	Идентификатор рекламного блока, заданный AdMob
{{ilrd::currency}}	Код валюты из AdMob
{{ilrd::adapter_class}}	Класс-адаптер рекламной сети
{{ilrd::response_id}}	Идентификатор ответа, предоставленный AdMob
{{ilrd::ad_revenue_micro}}	Доход от рекламы в микроцентах, предоставленный AdMob

• Топон

Макро	Пояснение
{{ilrd::mediation_country}}	Страна, в которой зарегистрирован посредник
{{ilrd::ad_network_type}}	Тип сети, перекрестное продвижение или обмен
{{ilrd::adsource_index}}	Сортировка текущего источника рекламы в «водопаде»

Сведения об авторстве SAN #

• Мета

Макро	Пояснение
{{meta::account_id}}	Рекламный аккаунт, использованный для создания объявления
{{meta::ad_id}}	Уникальный идентификатор объявления, по которому был сделан клик или которое было просмотрено до конверсии
{{meta::ad_objective_name}}	Цель, выбранная при создании кампании (например, MOBILE_APP_INSTALLS, CONVERSIONS)
{{meta::adgroup_id}}	Идентификатор рекламы Meta
{{meta::adgroup_name}}	Название мета-рекламы
{{meta::campaign_group_id}}	Идентификатор метакампании
{{meta::campaign_group_name}}	Название метакампании
{{meta::campaign_id}}	Идентификатор набора рекламных объявлений Meta
{{meta::campaign_name}}	Название мета-набора рекламных объявлений
{{meta::click_time}}	Время последнего клика по рекламе до определения атрибуции
{{meta::engagement_type}}	Тип взаимодействия для атрибуции (например, engaged_view)
{{meta::is_fb}}	Была ли установка выполнена через Meta
{{meta::is_modeled}}	Является ли атрибуция моделируемой или детерминированной
{{meta::is_paid}}	Была ли установка осуществлена через платный канал на Meta
{{meta::is_view_through}}	Была ли атрибуция основана на просмотрах или на кликах
{{meta::platform_position}}	Формат рекламы, отображаемый на платформе
{{meta::publisher_platform}}	Платформа, на которой была показана реклама (например, AUDIENCE_NETWORK, INSTAGRAM, MESSENGER, FACEBOOK)
{{meta::view_time}}	Время последнего просмотра рекламы перед атрибуцией

Подробнее о маршрутизации и использовании этих макросов можно прочитать в разделе «Настройка обратного вызова».