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

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

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

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

Определение этих полей выглядит следующим образом:

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

Название аналитического/рекламного продукта. ( Google AdMob )

Обратите внимание, что если пользовательский агент создается на стороне клиента, то в качестве 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 Ads о событии в приложении, которое следует отслеживать как конверсию и/или использовать для заполнения списка ремаркетинга, а также получить метаданные, описывающие любой клик, предшествовавший этому событию.

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

/pagead/conversion/app/version
где version — это предполагаемая версия API отслеживания конверсий.

Стандартный запрос на конвертацию приложения будет содержать следующие параметры для 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 символов Unicode (с использованием кодировки UTF-8). Это поле обязательно, если app_event_type имеет значение custom . 

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-приложения из Google On Device Measurement (ODM): Event Data SDK. Это поле включает интегрированное измерение конверсий для кампаний 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 через API Play Install Referrer .

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 используйте следующие соглашения для примитивных типов данных:

  • Плавать

    • Используйте точку в качестве десятичного разделителя независимо от локализации приложения.
    • Для представления денежных значений используйте двухзначную десятичную дробь. Например, 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 для 5-го дня месяца, отправьте 05 .
    • Допустимые примеры:
      • "2016-09-23"
      • "1990-12-31"

  • Отметка времени

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

  • Массивы

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

Образцы запросов

Примером первого открытого запроса к пакету SDK для измерения событий на устройстве (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
       &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 для интегрированного измерения конверсии является: 

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

Примером первого открытого запроса без 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 v1.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

Примером допустимого запроса на переатрибуцию начала сессии для сессии, которая началась с прямой ссылки 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 Ads ответит одним последним кликом по всем своим конверсиям. Если пользователь не дал согласия на использование данных в других контекстах в своих настройках Google, Google Ads ответит несколькими последними кликами для каждой конверсии отдельно.

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

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

Всегда присутствует

нить

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

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

Всегда присутствует

нить

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

conversion
timestamp

Всегда присутствует

число

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

1432681913.123456
campaign_type

Всегда присутствует

нить

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

ACI
ACE
ACPre
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI — это аббревиатура от App Campaign for Install (кампания по установке приложений). ACE — это аббревиатура от App Campaigns for Engagement (кампании по вовлечению пользователей в приложения).

campaign_id

Всегда присутствует

число

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

123456789
campaign_name

Всегда присутствует

нить

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

Occasional Gamers (Video)
ad_type

Всегда присутствует

нить

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

Продвижение приложения
ClickToDownload
 Вовлеченность в приложение
AppDeepLink
 Взаимодействие с приложением — процесс установки и продолжения использования.
AppDeepLinkContinue
 Обобщенный список для других значений 
Unknown
external_customer_id

Всегда присутствует

число

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

123456789
location

Всегда присутствует

число

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

network_type

Всегда присутствует

нить

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

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

Значение будет null , если campaign_type имеет значение ACI или ACE , а network_type — Display .

нить

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

Обычный поиск Google
GoogleSearch
 Партнеры Google по поиску 
SearchPartners

Отображать

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

YouTube

Сеть видеороликов YouTube
YouTubeVideos
 Поисковая сеть YouTube
YouTubeSearch
 Видеопартнеры 
VideoPartners

Google ТВ

Сеть GoogleTV Videos 
GoogleTvVideos

межсетевой

Performance Max в сети 
cross-network
video_id

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

нить

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

dQw4w9WgXcQ
keyword

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

нить

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

+food +delivery
match_type

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

нить

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

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

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

нить

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

mobileapp::1-343200656
ad_group_id

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

число

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

123456789
ad_group_name

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

нить

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

My App AdGroup
asset_group_id

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

число

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

123456789
creative_id

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

число

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

123456789
interaction_type

В этой сфере всегда будет важна вовлеченность.

нить

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": null,
    "ad_group_name": null,
    "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": null,
    "ad_group_name": null,
    "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": null,
      "ad_group_name": null,
      "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",
    "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": null,
    "ad_group_name": "",
    "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": "My App AdGroup",
    "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": "My App AdGroup",
    "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": "My App AdGroup",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "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": null,
    "ad_group_name": "",
    "asset_group_id": null,
    "creative_id": null,
    "timestamp": 1432681913.123456
  }
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}


Запрос на межсетевую атрибуцию

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

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

/pagead/conversion/app/1.1/cross_network

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

Запрос на межсетевую атрибуцию
ad_event_id

Необходимый

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

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

attributed

Необходимый

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

Получил ли Google Ads вознаграждение за конверсию от пользователя 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 без тела ответа.