Отслеживание конверсий и ремаркетинг в приложениях – спецификации запроса/ответа

Агент пользователя приложения

В рамках борьбы со спамом мы разработали стандартную спецификацию для заголовка User-Agent, который отправляется продуктом для аналитики или рекламы от имени пользователя приложения. Агент пользователя приложения можно получить из нативного кода, чтобы соблюдать следующие требования:

name version (os_and_version; locale; device; build; Proxy)

Ниже приведено описание этих полей.

Компоненты агента пользователя
name

Название продукта для аналитики или рекламы. (Google AdMob)

Обратите внимание, что если строка user agent создается на стороне клиента, то вместо name должен быть указан идентификатор пакета клиентского приложения.

Android
// Specified by API consumer.
iOS
// Specified by API consumer.
version

Версия продукта для аналитики или рекламы. (7.10.1)

Android
// Specified by API consumer.
iOS
// Specified by API consumer.
os_and_version

Операционная система и ее версия, на которой работает приложение. (Android 6.0 )

Android
String osAndVersion =
    "Android " + Build.VERSION.RELEASE;
iOS
UIDevice *uid =
  [UIDevice currentDevice];
NSString *osAndVersion =
  [NSString
    stringWithFormat:@"%@ %@",
    [uid systemName],
    [uid systemVersion]];
locale

Тег языка IETF для устройства, состоящий из двухбуквенного кода языка и кода страны, разделенных символом подчеркивания. (en_US)

Android
String locale = Locale.getDefault();
iOS
NSString *locale =
  [[NSLocale currentLocale]
    localeIdentifier]
device

Название физического устройства, на котором работает продукт для аналитики или рекламы. (iPhone9,1)

Android
String device = Build.MODEL;
iOS
@import Darwin.sys.sysctl;

NSString *device(void) {
  size_t bufferSize = 64;
  NSMutableData *buffer =
    [[NSMutableData alloc]
      initWithLength:bufferSize];
  int status =
    sysctlbyname("hw.machine",
      buffer.mutableBytes,
      &bufferSize, NULL, 0);
  if (status != 0) {
    return nil;
  }
  return [[NSString alloc]
    initWithCString:buffer.mutableBytes
    encoding:NSUTF8StringEncoding];
}
build

"Build/" с номером сборки операционной системы. (Build/13D15)

Android
String build = "Build/" + Build.ID;
iOS
@import Darwin.sys.sysctl;

NSString *build(void) {
  size_t bufferSize = 64;
  NSMutableData *buffer =
    [[NSMutableData alloc]
      initWithLength:bufferSize];
  int status =
    sysctlbyname("kern.osversion",
      buffer.mutableBytes,
      &bufferSize, NULL, 0);
  if (status != 0) {
    return nil;
  }
  return [[NSString alloc]
    initWithCString:buffer.mutableBytes
    encoding:NSUTF8StringEncoding];
}

Включайте ; Proxy только в конец строки User-Agent приложения при создании строки User-Agent приложения на стороне сервера. Если агент пользователя приложения полностью создается на стороне клиента, исключите ; Proxy. Таким образом, строка User-Agent приложения может выглядеть следующим образом:

  • Android: AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M; Proxy)
  • iOS: AdMob/7.10.1 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)

Руководство по запросам отслеживания конверсий

Запросы на отслеживание конверсий нужны, чтобы уведомлять Google Рекламу о событиях в приложении, которые следует отслеживать как конверсии и/или использовать для заполнения списка ремаркетинга, а также получать метаданные, описывающие клик, который предшествовал событию.

Все вызовы API выполняются в домене www.googleadservices.com. Запросы конверсий – это запросы POST, отправляемые по протоколу HTTPS по следующему пути: 

/pagead/conversion/app/version
, где version – нужная версия API отслеживания конверсий.

Стандартный запрос конверсии в приложении будет содержать следующие параметры для App Conversion API версии 1.1:

Запрос на отслеживание конверсий
dev_token

Обязательно

Местоположение: запрос

Уникальный статический токен разработчика, выданный потребителю API.

Z_eErE4DkvcKjDM1OVE4c4
link_id

Обязательно

Местоположение: запрос

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

31FF8D67E5BB5DD5029DCC2734C2F884
app_event_type

Обязательно

Местоположение: запрос

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

 • first_open
 • session_start
 • in_app_purchase
 • view_item_list
 • view_item
 • view_search_results
 • add_to_cart
 • ecommerce_purchase
 • custom

Событие first_open всегда должно отправляться для атрибуции установок, а событие session_start – для реатрибуции сеансов. Используйте in_app_purchase для покупок, совершенных через встроенный магазин приложений, и ecommerce_purchase для всех остальных покупок.
app_event_name

Обязательно при определенных условиях

Местоположение: запрос

Название любого специального события приложения, которое не принимается в поле app_event_type. Это поле должно содержать от 1 до 64 символов Юникода (в кодировке UTF-8). Это поле обязательно, если app_event_type является специальным.

level_achieved
Level Achieved

Это поле не должно содержать значений, зарезервированных для app_event_type. Если используется зарезервированное название события, API возвращает ошибку APP_EVENT_NAME_RESERVED_VALUE.
app_event_data

Необязательно

Местоположение: тело

Передавайте любые дополнительные данные о событии в виде простого объекта JSON, сопоставляющего строковые ключи со значениями. Допустимые значения – строки и массивы строк.

{"level": 5, "attempts": 20}
odm_info

Обязательно при использовании интегрированного отслеживания конверсий в iOS

Местоположение: запрос

Значение параметра запроса info, полученное при установке или переустановке приложения для iOS с помощью SDK для отслеживания на устройстве (ODM) от Google: данных о событиях. Это поле позволяет включить интегрированное отслеживание конверсий в кампаниях для приложений iOS.

XYZr_AB8C-_zGtKjUhqtzPLeQ8lbJB5dADVR0tpZ9f-28sN5qN9GTZ_FztjL0OL
FzgxUJDhZr8w6lwGxAwPcxSwR5orjWepZiVP7sRRoCiaHerR-1TP17eJKtazgeSg
_CVEs13LllDTfrhVM8uWISqlg8dXobsLzmj8C7WrOlktHA5P_E23
id_type

Обязательно

Тип идентификатора, переданного в поле rdid.

Android

advertisingid
 
appsetid

iOS

idfa
 
idfv
rdid

Обязательно

Местоположение: запрос

Действительная строка UUID, представляющая необработанный идентификатор устройства.

f10e1de2-e237-4f50-b6aa-843c45cc63d6

Если идентификатор устройства отсутствует, например если пользователь не дал согласия ATT, укажите нулевое значение.

00000000-0000-0000-0000-000000000000
ctry_c

Обязательно

Местоположение: запрос

Двухбуквенный код страны ISO, указывающий, откуда было совершено конверсия.

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

US, IN
eea

Обязательно при определенных условиях

Местоположение: запрос

Область действия ЕЭЗ.

0 – европейские регламенты не применяются к этому пользователю и конверсии.

1 – европейские регламенты применяются к этому пользователю и конверсии. Например, если пользователь находится в ЕЭЗ, к нему применяются европейские регламенты. 

*Required to be sent when the value is known.
ad_personalization

Обязательно при определенных условиях

Местоположение: запрос

Флаги для персонализированной рекламы:

0 – конечный пользователь не дал согласия на персонализацию рекламы.

1 – конечный пользователь дал согласие на персонализацию рекламы. 

*Required to be sent when the value is known.
ad_user_data

Обязательно при определенных условиях

Местоположение: запрос

Флаг согласия на использование пользовательских данных в рекламных целях.

0 – пользователь не дал согласия на передачу данных на уровне пользователя в Google в рекламных целях.

1 – пользователь дал согласие на передачу данных на уровне пользователя в Google в рекламных целях. 

*Required to be sent when the value is known.
lat

Обязательно

Местоположение: запрос

Статус ограничения отслеживания рекламы для устройства.

  • 0: пользователь не ограничил отслеживание рекламы;
  • 1 – пользователь ограничил отслеживание рекламы.
app_version

Обязательно

Местоположение: запрос

Текущая версия приложения. Она должна быть указана в следующем формате:

Android

packageManager.getPackageInfo(packageName(),
  PackageManager.GET_META_DATA).versionName

iOS

[[[NSBundle mainBundle] infoDictionary]
  objectForKey:@"CFBundleShortVersionString"]
 
1.2.4
os_version

Обязательно

Местоположение: запрос

Текущая версия ОС, на которой работает приложение. Стандартный формат:

Android

android.os.Build.VERSION.RELEASE

iOS

[[UIDevice currentDevice] systemVersion]
sdk_version

Обязательно

Местоположение: запрос

Версия SDK, которая зарегистрировала событие. Поскольку эта информация в основном используется для отладки, она должна точно соответствовать конечной версии, опубликованной вместе с вашими выпусками SDK. Если приложение не использует SDK, передайте то же значение, что и в параметре app_version.

1.9.5r6
timestamp

Обязательно

Местоположение: запрос

Временная метка UNIX, показывающая время события-конверсии в секундах с точностью до микросекунд.

1432681913.123456
fot

Обязательно

Местоположение: запрос

Временная метка UNIX из соответствующего параметра first_open в секундах с точностью до микросекунд для всех последующих сеансов и событий после установки.

1432681913.123456
value

Необязательно

Местоположение: запрос

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

1.99
currency_code

Обязательно при определенных условиях

Местоположение: запрос

Код валюты по стандарту ISO 4217 для параметра value. Это поле обязательно, если параметр value указан и не пуст.

USD
gclid

Обязательно при определенных условиях

Местоположение: запрос

Значение параметра запроса gclid из URL ссылки на контент, по которой было открыто приложение.

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

Обязательно при определенных условиях

Местоположение: запрос

Значение параметра запроса gclid из URL ссылки на контент, полученное из значения install_referrer с помощью Play Install Referrer API.

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

Обязательно при определенных условиях

Местоположение: запрос

Идентификатор для атрибуции на основе gclid в случаях, когда rdid (advertisingid) not недоступен или все zeroes ИЛИ gclid, ИЛИ market_referrer_gclid присутствуют.

1
gbraid

Обязательно при определенных условиях

Местоположение: запрос

Значение параметра "Последний просмотр" gbraid, переданное через URL ссылки на контент, по которой было открыто приложение. Обратите внимание, что это значение должно быть сохранено в кеше приложения, чтобы его можно было передавать с будущими конверсиями, совершенными в приложении.

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
app_open_source

Обязательно при определенных условиях

Местоположение: запрос

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

ad_click or organic
User-Agent

Обязательно

Заголовок "Местоположение"

Агент пользователя приложения, как описано в предыдущем разделе.

AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M)
X-Forwarded-For

Обязательно

Заголовок "Местоположение"

Общедоступный адрес IPv4 или IPv6 устройства, на котором было зарегистрировано событие.

216.58.194.174

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

Обратите внимание, что если тело запроса пустое (в случаях, когда в полезной нагрузке app_event_data не передаются данные о расширенном событии), наш сервер требует, чтобы вы явно задали заголовок Content-Length: 0 в своем запросе.

Кодировка данных о событиях

Для параметра app_event_data используйте следующие соглашения для примитивных типов данных:

  • Float

    • Использовать точку в качестве десятичного разделителя независимо от локализации приложения
    • Для денежных значений используйте десятичные дроби с двумя знаками после запятой, например 2.99.
    • Не используйте экспоненциальную запись, например 2E+9.
    • Не используйте запятую для разделения групп цифр, например: 1 000 000
    • Примеры допустимых значений:
      • -0.5
      • 2.99
      • 1000000.123

  • Целое число

    • Отправляйте только целые числа без десятичных знаков.
    • Не используйте запятую для разделения групп цифр, например 1,000,000.
    • Примеры допустимых значений:
      • 1000
      • -11
      • 0

  • Дата

    • Формат даты: ГГГГ-ММ-ДД.
      • yyyy – год (четыре цифры), например 2016.
      • mm – месяц в виде двух цифр, например 09 для сентября;
      • dd – день месяца в виде двузначного числа, например 23 для 23-го числа месяца.
    • Всегда указывайте количество цифр, приведенное выше. Например, если вы отправляете значение для dd для пятого дня месяца, укажите 05.
    • Примеры допустимых значений:
      • "2016-09-23"
      • "1990-12-31"

  • Временная метка

    • Формат времени: Unix-время в секундах, определенное в часовом поясе UTC с точностью до микросекунд.
    • Примеры допустимых значений:
      • 1478713087 для Wed, 09 Nov 2016 17:38:07 GMT
      • 1073513982.123000 для среды, 7 января 2004 г., 22:19:42.123 GMT

  • Массивы

    • Отправлять только массивы примитивных значений (строк, чисел и логических значений).
    • Примеры допустимых значений:
      • [123, 456, 789]
      • ["abc"]

Примеры запросов

Пример запроса первого открытия с SDK для отслеживания конверсий на устройствах: данные о событиях:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &odm_info=abcdEfadGdaf
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Пример запроса на первое открытие без On Device Measurement: Event Data SDK for Integrated Conversion Measurement:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Пример запроса после установки с On Device Measurement: Event Data SDK для интегрированного отслеживания конверсий:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &odm_info=abcdEfadGdaf
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &&fot=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Пример запроса при первом открытии без On Device Measurement: Event Data SDK:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Пример запроса на первый запуск для недетерминированной конверсии Android в ACAPI версии 1.1:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=appsetid
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &ctry_c=IN
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (android 11; en-GB; RMX2040; Build/_; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Пример действительного запроса на отслеживание конверсий с нестандартным типом события и информацией о доходе:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=0
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
 
{"app_event_data":{"item_id":["Crayons","Markers"]}}

Пример действительного запроса отслеживания конверсий с нестандартным типом события и информацией о доходе, в котором недоступен rdid (advertisingid):

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; Android,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
 
{"app_event_data":{"item_id":["Crayons","Markers"]}}

Пример действительного запроса начала сеанса:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Пример действительного запроса session start reattribution для сеанса, начавшегося по ссылке на контент example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Пример действительного запроса на отслеживание конверсий для пользователя из ЕЭЗ, который дал согласие на использование данных о пользователе в рекламе, но отказался от персонализации рекламы:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=1
       &ad_personalization=0
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Руководство по отслеживанию конверсий

Ответ для отслеживания конверсий имеет следующий формат:

{
  "ad_events": [<ad event objects>],
  "errors": [<error strings>],
  "attributed": true|false
}

Оба массива, ad_events и errors, могут быть пустыми.

Ошибки будут представлены в виде машиночитаемых кодов, например invalid_timestamp.

Коды ошибок

  • invalid_timestamp – в запросе не было действительной временной метки.

  • eea_missing_or_invalid – в запросе не было поля eea или оно было недействительным.

  • ad_user_data_missing – поле запроса ad_user_data не задано. Поле ad_user_data обязательно для всех запросов, относящихся к зонам DMA.

  • ad_user_data_invalid – недопустимое значение запроса ad_user_data. Поле ad_user_data обязательно для всех запросов, относящихся к зонам DMA.

  • ad_personalization_missing_or_invalid – в запросе не было поля ad_personalization или оно было недействительным. Поле ad_personalization обязательно для всех запросов DMA.

События объявлений – это основные объекты атрибуции приложений, которые содержат следующие свойства:

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

Если конверсия включает определенные сервисы Google, для которых пользователь предоставил согласие на перекрестное использование, но не включает другие, Google Реклама будет отвечать одним последним кликом для сервисов, для которых предоставлено согласие на перекрестное использование, и несколькими последними кликами для сервисов, для которых такое согласие не предоставлено.

Ответ отслеживания конверсий
ad_event_id

Присутствует всегда

string

ad_event_id – уникальный идентификатор событий, связанных с рекламой. Он используется в запросе на атрибуцию для нескольких сетей, поэтому его следует регистрировать и сохранять для отладки.

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

Присутствует всегда

string

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

conversion
timestamp

Присутствует всегда

число

Временная метка UNIX, показывающая время события объявления в секундах с точностью до микросекунд. Это значение следует использовать для атрибуции по последнему клику.

1432681913.123456
campaign_type

Присутствует всегда

string

В этом поле указывается тип кампании, в которой произошло событие объявления. Возможные значения:

ACI
ACE
ACPRE
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI – это аббревиатура, обозначающая кампанию, ориентированную на установку приложений. ACE – это аббревиатура, обозначающая кампании, ориентированные на взаимодействие с приложением.
campaign_id

Присутствует всегда

число

Числовой идентификатор кампании, в которой произошло событие объявления. Это значение гарантированно уникально.

123456789
campaign_name

Присутствует всегда

string

Название кампании, заданной рекламодателем, в которой произошло событие, связанное с объявлением. Уникальность этого значения не гарантируется.

Occasional Gamers (Video)
ad_type

Присутствует всегда

string

Тип объявления, которое привело к событию объявления. Это значение можно использовать, чтобы различать разные типы инвентаря.

Продвижение приложений 
ClickToDownload
 Взаимодействие с приложением 
AppDeepLink
 Вовлечение пользователей в приложение – установка и продолжение 
AppDeepLinkContinue
 Другие значения 
Unknown
external_customer_id

Присутствует всегда

число

Идентификатор рекламодателя, которому принадлежит кампания, вызвавшая событие. Это значение можно использовать для различения аккаунтов Google Рекламы.

123456789
location

Присутствует всегда

число

Идентификатор местоположения для географического местоположения события объявления. Чтобы понять, что означают коды местоположений, ознакомьтесь с справочной документацией по Google Ads API.
network_type

Присутствует всегда

string

В этом поле указывается рекламная сеть Google Рекламы, в которой произошло событие объявления. Возможные значения:

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

Значение null будет присвоено, если campaign_type имеет значение ACI или ACE, а network_type – Display.

string

В этом поле указывается подтип рекламной сети Google Рекламы, в которой произошло событие объявления. Возможные значения зависят от основного типа сети.

Обычный поиск Google 
GoogleSearch
 Сайты поисковых партнеров Google 
SearchPartners

Экран

Издатели мобильных сайтов 
mGDN
 Издатели приложений 
Google AdMob

YouTube

Сеть видео YouTube 
YouTubeVideos
 Поиск на YouTube 
YouTubeSearch
 Партнерские видеоресурсы 
VideoPartners

GoogleTv

Сеть видео Google TV 
GoogleTvVideos

межсетевой

Кампании с максимальной эффективностью в нескольких сетях 
cross-network
video_id

Предоставляется только в том случае, если network_type имеет значение YouTube, а campaign_type – не ACI и ACE.

string

Идентификатор видео YouTube, связанного с событием объявления.

dQw4w9WgXcQ
keyword

Предоставляется только в том случае, если network_type имеет значение Search, а campaign_type – не ACI и ACE.

string

Ключевое слово, связанное с событием.

+food +delivery
match_type

Предоставляется только в том случае, если network_type имеет значение Search, а campaign_type – не ACI и ACE.

string

Тип соответствия ключевых слов для поисковой сети.

Точное 
e
 Фраза 
p
Широкое 
b
placement

Предоставляется только в том случае, если network_type имеет значение Display, а campaign_type – не ACI и ACE.

string

Место размещения, связанное с событием объявления.

mobileapp::1-343200656
ad_group_id

Предоставляется только в том случае, если campaign_type не равно Performance_Max.

число

Числовой идентификатор группы объявлений, связанной с событием. Это значение гарантированно уникально.

Это поле не предоставляется для событий рекламы, атрибуция которых выполнена с помощью gbraid и является детерминированной (is_deterministic – true), например для атрибуции ссылок на контент.

123456789
ad_group_name

Предоставляется только в том случае, если для параметра campaign_type задано значение ACI, ACE или ACPRE.

string

Название группы объявлений, заданной рекламодателем, в которой было создано объявление, вызвавшее событие. Уникальность этого значения не гарантируется.

Это поле не предоставляется для событий рекламы, атрибуция которых выполнена с помощью gbraid и является детерминированной (is_deterministic – true), например для атрибуции ссылок на контент.

My App AdGroup
asset_group_id

Предоставляется только в том случае, если campaign_type имеет значение Performance_Max.

число

Числовой идентификатор группы объектов, которая создала событие объявления. Это уникальное значение.

123456789
creative_id

Указывается только в том случае, если значение campaign_type не равно ACI, ACE, ACPRE или Performance_Max.

число

Числовой идентификатор рекламного блока, связанного с событием объявления. Это значение гарантированно уникально.

123456789
interaction_type

В этом поле всегда будет указано "Вовлеченность".

string
is_deterministic

Указывает, является ли метод атрибуции детерминированным.

Логическое значение

true, false
device_model

Модель устройства, на котором произошло событие, связанное с объявлением.

Строка

sm-s936w, sm-3936w
os_version

Основная версия ОС, в которой произошло событие объявления.

Строка

14, 12
country

Двухбуквенный код страны, в которой произошло событие, связанное с объявлением.

Строка

CA, US
city

Город, в котором произошло событие, связанное с объявлением.

Строка

san jose, london
region

Штат или провинция, в которых произошло событие, связанное с объявлением.

Строка

california, british columbia

Примеры ответов

Пример ответа для детерминированной конверсии:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "network_type": null,
    "network_subtype": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "is_deterministic": true,
    "timestamp": 1234567.898765
  }],
  "errors": [],
  "attributed": true
}

Пример ответа для недетерминированной конверсии в iOS:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "network_type": null,
    "network_subtype": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "is_deterministic": false,
    },
    "device_info": {
        "device_model": "iphone12,3",
        "os_version": "14"
    },
    "timestamp": 1432681918.123456
    }],
  "errors": [],
  "attributed": true
}

Пример ответа для недетерминированной конверсии на устройстве Android:

{
  "ad_events": [
    {
      "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
      "conversion_metric": "conversion",
      "interaction_type": "click",
      "campaign_type": "ACI",
      "campaign_id": 123456789,
      "campaign_name": "My App Campaign",
      "network_type": null,
      "network_subtype": null,
      "ad_group_id": 123456789,
      "ad_group_name": "My App AdGroup",
      "asset_group_id": null,
      "is_deterministic": false,
      "geo_info": {
        "city": "san jose",
        "country": "US",
        "region": "california"
      },
      "device_info": {
          "device_model": "sm-s926u",
          "os_version": "14"
      },
      "timestamp": 1432681918.123456
    },
    ],
    "errors": [],
    "warnings": []
  }

Пример ответа для конверсии в iOS/Android, атрибуция которой выполнена по gbraid:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "interaction_type": "engagement",
    "network_type": null,
    "ad_group_id": null,
    "ad_group_name": null,
    "asset_group_id": null,
    "is_deterministic": true,
    "timestamp": 0.000000
  }],
  "errors": [],
  "attributed": true,
  "warnings": [],
}

Пример ответа системы отслеживания конверсий, если в запросе были ошибки:

{
  "ad_events": [],
  "errors": ["INVALID_CURRENCY_CODE"],
  "attributed": false
}

Пример отрицательного ответа при отслеживании конверсий:

{
  "ad_events": [],
  "errors": [],
  "attributed": false
}

Ответы на запросы отслеживания конверсий будут возвращаться для всех запросов.

Пример положительного ответа на запрос об отслеживании конверсий для пользователя не из ЕЭЗ в универсальной кампании для приложений:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "GoogleSearch",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Пример положительного ответа на запрос об отслеживании конверсий для пользователя не из ЕЭЗ в поисковой кампании:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Search",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "GoogleSearch",
    "video_id": null,
    "keyword": "+space +birds",
    "match_type": "b",
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": null,
    "asset_group_id": null,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Пример положительного ответа отслеживания конверсий для пользователя не из ЕЭЗ в медийной кампании:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Display",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "mGDN",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": "mobile-app::2-343200656",
    "ad_group_id": 123456789,
    "ad_group_name": null,
    "asset_group_id": null,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Пример положительного ответа на запрос об отслеживании конверсий для пользователя не из ЕЭЗ в кампании на YouTube:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Video",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "YouTube",
    "network_subtype": "YouTubeVideos",
    "video_id": "dQw4w9WgXcQ",
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": null,
    "asset_group_id": null,
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  {
    "ad_event_id": "I8YUwWqxvOyqcwOcqBAkYZBMaOONSd",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  {
    "ad_event_id": "I8YUwWqxvOyqcwOcqBAkYZBMaOONSd",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "YouTube",
    "network_subtype": "YouTubeVideos",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}


Запрос на атрибуцию для нескольких сетей

Если Google Реклама положительно отвечает на запрос отслеживания конверсий, потребитель API должен уведомить Google Рекламу о своем решении по многоканальной атрибуции после определения последнего клика.

Межсетевой запрос атрибуции идентичен исходному запросу на отслеживание конверсий, но имеет следующий путь:

/pagead/conversion/app/1.1/cross_network

и добавление двух обязательных параметров:

Запрос на атрибуцию для нескольких сетей
ad_event_id

Обязательно

Местоположение: запрос

Идентификатор ad_event_id из события объявления, связанного с атрибуцией в предыдущем запросе.
attributed

Обязательно

Местоположение: запрос

Получила ли Google Реклама ценность конверсии от потребителя API. 0 или 1.

Пример действительного запроса атрибуции для нескольких сетей:

POST /pagead/conversion/app/1.1/cross_network
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=custom
       &app_event_name=level_achieved
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &ad_event_id=Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
       &attributed=1
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

На действительный запрос атрибуции между сетями всегда приходит общий ответ 200 без тела.