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

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

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

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

Определение этих полей следующее:

// Specified by API consumer.

// Specified by API consumer.

// Specified by API consumer.

// Specified by API consumer.

String osAndVersion =
    "Android " + Build.VERSION.RELEASE;

UIDevice *uid =
  [UIDevice currentDevice];
NSString *osAndVersion =
  [NSString
    stringWithFormat:@"%@ %@",
    [uid systemName],
    [uid systemVersion]];

String locale = Locale.getDefault();

NSString *locale =
  [[NSLocale currentLocale]
    localeIdentifier]

String device = Build.MODEL;

@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];
}

String build = "Build/" + Build.ID;

@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 приложения полностью создан на стороне клиента, исключить ; 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

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

Z_eErE4DkvcKjDM1OVE4c4

31FF8D67E5BB5DD5029DCC2734C2F884

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

level_achieved
Level Achieved

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

f10e1de2-e237-4f50-b6aa-843c45cc63d6

00000000-0000-0000-0000-000000000000

advertisingid

idfa

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

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

1.2.4

android.os.Build.VERSION.RELEASE

[[UIDevice currentDevice] systemVersion]

1.9.5r6

1432681913.123456

1.99

USD

Cj0KEQjw0dy4BRCuuL_e5M

BX3QojHp4mY5MrJtFM_d1u

1

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

ad_click or organic

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

216.58.194.174

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

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

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

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

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &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
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.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &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
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.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &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
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.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &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
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
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 используйте следующие соглашения для примитивных типов данных:

• Плавать

  • Используйте символ точки в качестве десятичного разделителя независимо от локализации приложения.
  • Используйте двузначную десятичную точность для представления денежных значений. например 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 по Гринвичу
    • 1073513982.123000 для среды, 07 января 2004 г., 22:19:42.123 по Гринвичу

• Массивы

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

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

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

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

И массивы ad_events, и массивы ошибок могут быть пустыми.

Мы ожидаем, что ошибки будут машиночитаемыми кодами ошибок, например, invalid_timestamp .

Рекламные события являются основными объектами атрибуции приложений и будут содержать следующие свойства.

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ

conversion

1432681913.123456

ACI
ACE
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

123456789

Occasional Gamers (Video)

ClickToDownload

AppDeepLink

AppDeepLinkContinue

Unknown

123456789

Search
Display
YouTube

GoogleSearch

SearchPartners

mGDN

Google AdMob

YouTubeVideos

YouTubeSearch

VideoPartners

dQw4w9WgXcQ

+food +delivery

e

p

b

mobileapp::1-343200656

123456789

My App AdGroup

123456789

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

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

{
  "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": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true
}

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

{
  "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",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true
}

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

{
  "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",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true
}

Пример положительного ответа на отслеживание конверсий для кампании на 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",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true
}

Межсетевой запрос атрибуции

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

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

/pagead/conversion/app/1.0/cross_network

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

Пример допустимого межсетевого запроса атрибуции:

POST /pagead/conversion/app/1.0/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 без тела ответа.