Отправка событий

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

Используйте API диспетчера данных в любом из следующих сценариев:

• Отправляйте конверсии тегов Google Ads или ключевые события Google Analytics в качестве дополнительного источника данных для конверсий тегов, чтобы максимизировать сигналы взаимодействия с рекламой и улучшить ваши данные и общую эффективность.

  Эта функция доступна только для аккаунтов из списка разрешённых. Заполните форму, если хотите добавить свой аккаунт Google Рекламы или ресурс Google Analytics.

• Отправка данных о событиях для офлайн-конверсий Google Ads или расширенных конверсий для лидов .

Выберите версию руководства, которую вы хотите увидеть:

Партнер по данным рекламодателя

В этом кратком руководстве вы выполните следующие шаги:

1. Подготовьте пункт Destination для получения данных о событиях.
2. Подготовьте данные о событии для отправки.
3. Создайте запрос IngestionService для событий.
4. Отправьте запрос с помощью Google APIs Explorer.
5. Понимание успешных и неудачных реакций.

Подготовка пунктов назначения

Прежде чем отправлять данные, необходимо подготовить хотя бы одно Destination для этих данных. Вот пример Destination , которое вы можете использовать:

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

Вот поля Destination :

operatingAccount

Учетная запись, которая получает события.

Для событий, отправляемых в качестве дополнительного источника данных, действующий аккаунт может быть аккаунтом Google Ads или ресурсом Google Analytics. Установите для accountType значение GOOGLE_ADS или GOOGLE_ANALYTICS_PROPERTY , а для параметра accountId — идентификатор клиента Google Ads или идентификатор ресурса Google Analytics. Если для accountType задано значение GOOGLE_ANALYTICS_PROPERTY , учётные данные запроса должны быть предоставлены пользователю Google Analytics с ролью редактора или администратора для ресурса.

Для офлайн-конверсий и расширенных конверсий для лидов действующая учетная запись должна быть учетной записью Google Ads, поэтому установите для accountType значение GOOGLE_ADS , а для accountId укажите идентификатор клиента Google Ads.

loginAccount

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

Если ваши учётные данные OAuth предназначены для пользователя с доступом к управляющему аккаунту Google Ads , в котором operatingAccount является одним из дочерних аккаунтов, необходимо указать loginAccount . В качестве accountId loginAccount укажите идентификатор управляющего аккаунта, а в качестве accountType loginAccount — GOOGLE_ADS .

Если ваши учётные данные OAuth предназначены для пользователя с прямым доступом к operatingAccount , вам не нужно настраивать loginAccount , и по умолчанию будет использоваться учётная запись operatingAccount . Однако мы рекомендуем установить для loginAccount те же accountId и accountType что и для operatingAccount . Это поможет избежать проблем при изменении набора учётных записей, к которым пользователь имеет доступ.

productDestinationId

Идентификатор объекта в operatingAccount , который получает события.

Для событий, отправляемых в качестве дополнительного источника данных, productDestinationId должен быть идентификатором конверсии Google Рекламы с type WEBPAGE или идентификатором измерения веб-потока Google Analytics. События нельзя отправлять в качестве дополнительного источника данных в поток приложения Google Analytics для iOS или Android.

Для офлайн-конверсий или расширенных конверсий для лидов productDestinationId должен быть идентификатором действия конверсии Google Ads с type UPLOAD_CLICKS .

Пример в этом руководстве показывает, как создать запрос, отправляющий все события в один и тот же пункт назначения. Если вы хотите отправить события в несколько пунктов назначения в одном запросе, см. раздел «Отправка событий в несколько пунктов назначения» .

Подготовка данных о событиях

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

Каждое событие может иметь идентификаторы рекламы, например gclid , или идентификаторы пользователей, например адреса электронной почты, номера телефонов и адресную информацию . Событие также может иметь:

• Информация о пользователе, оцениваемая во время события , например, ценность клиента или то, является ли он новым, вернувшимся или повторно привлеченным клиентом.
• Данные корзины покупок.
• Дополнительные параметры событий или свойства пользователя для пункта назначения, такие как client_id или user_id для Google Analytics.

Вот данные о событии:

Форматировать данные

Отформатируйте поля в соответствии с руководством по форматированию . Вот данные события после форматирования:

Хешировать и кодировать данные

Кроме того, отформатированные адреса электронной почты, имена и фамилии должны быть хешированы с помощью алгоритма SHA-256 и закодированы в шестнадцатеричном формате или формате Base64. Вот данные о событиях после форматирования, хеширования и кодирования в шестнадцатеричном формате:

Преобразовать данные в объекты Event

Преобразуйте форматированные и хешированные данные каждого события в Event . Заполните следующие поля, как указано:

1. Установите eventTimestamp на время, когда произошло событие.

   События для Google Analytics должны иметь eventTimestamp в течение последних 72 часов.

2. Задайте обязательные поля для вашего варианта использования.

   Вариант использования	Идентификаторы	transactionId	eventSource
   Офлайн-конверсии или улучшенные конверсии для лидов	Обязательно . Установите хотя бы один из следующих параметров: adIdentifiers с установленным хотя бы одним из атрибутов gclid , gbraid , wbraid или sessionAttributes userData	Необязательный	Обязательно . Установите одно из значений перечисления для EventSource .
   События, отправленные в качестве дополнительного источника данных в пункт назначения Google Ads	Обязательно . Установите хотя бы один из следующих параметров: adIdentifiers с установленным по крайней мере одним из следующих атрибутов: gclid , gbraid или wbraid userData	Необходимый	Необязательно. Если установлено, должно быть WEB .
   События, отправляемые как дополнительный источник данных в пункт назначения Google Analytics	Обязательно . Установите хотя бы один из следующих параметров: clientId adIdentifiers с набором gclid userData	Необходимый	Необязательно. Если установлено, должно быть WEB .

3. Заполните все остальные поля, содержащие значение для события. Полный список доступных полей см. в справочной документации Event .

Добавить информацию Google Analytics

Если пункты назначения события, отправленного в качестве дополнительного источника данных, включают свойство Google Analytics, заполните следующие поля, как указано:

eventName

Обязательно . Имя события Google Analytics.

transactionId

Обязательно . Уникальный идентификатор события.

По крайней мере один идентификатор

Необходимо заполнить хотя бы одно из следующих полей:

• clientId : уникальный идентификатор пользовательского экземпляра веб-клиента. См. раздел «Отправка события в протокол измерений» .

• adIdentifiers.gclid : идентификатор клика Google .

• userData : Идентификаторы пользователя, такие как адреса электронной почты, номера телефонов или адресная информация .

destinationReferences

Обязательно , если список destinations на уровне запроса содержит более одного Destination Google Analytics. Добавьте запись в destinationReferences , чтобы указать, какой пункт назначения Google Analytics должен получать событие. Подробнее о ссылках на пункты назначения см . в разделе «Отправка событий в несколько пунктов назначения» .

Если destinationReferences не задан или имеет несколько записей, ссылающихся на пункты назначения Google Analytics, API диспетчера данных отклоняет событие с ошибкой MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT .

userId

Необязательно. Идентификатор пользователя .

additionalEventParameters

Необязательно, но рекомендуется. Заполните этот список любыми параметрами событий Google Analytics, которые не учитываются в других полях Event . Параметры могут включать дополнительные рекомендуемые параметры из события purchase или другие параметры, которые вы хотите отслеживать. Используйте имя параметра Google Analytics в качестве parameterName для EventParameter .

Например, если с транзакцией связаны налоги, добавьте запись в additionalEventParameters , задав для parameterName значение tax , а для value — стоимость налога.

Мы не рекомендуем добавлять записи для параметров событий Google Analytics transactionId , currency или value . Вместо этого заполните transactionId , currency и conversionValue Event , которые имеют приоритет над любыми записями в additionalEventParameters .

Добавить данные корзины для событий покупки

Заполните поле cartData Event информацией о купленных товарах. Для каждого купленного товара добавьте объект Item в список items CartData и заполните следующие поля, как указано:

itemId

Обязательно . Уникальный идентификатор элемента.

unitPrice

Обязательно . Цена за единицу товара без учета налогов, стоимости доставки и скидок , связанных с определенными событиями (на уровне транзакции).

Если на товар распространяется скидка, используйте цену за единицу со скидкой . Например, если цена за единицу товара составляет 27.67 , а скидка за единицу — 6.66 , установите unitPrice равным 21.01 .

quantity

Обязательно . Количество единиц, купленных для этого конкретного товара.

additionalItemParameters

Заполните этот список любыми параметрами, относящимися к области элемента , которые не учитываются в других полях Item . Используйте имя параметра элемента Google Analytics в качестве parameterName для ItemParameter .

Например, если у вас есть марка и категория для элемента, добавьте запись в additionalItemParameters элемента с parameterName установленным на item_brand , и value равным названию бренда, а также еще одну запись с parameterName установленным на item_category , и value , равным категории элемента.

Мы не рекомендуем добавлять записи для параметров товара Google Analytics quantity , price или item_id . Вместо этого заполните itemId , unitPrice и quantity для Item , которые имеют приоритет над любыми записями в additionalItemParameters .

Вот пример Event для форматированных, хешированных и закодированных данных из второго события с дополнительными данными для Google Analytics:

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "currency": "EUR",
  "eventTimestamp": "2025-06-10T23:42:33-05:00",
  "transactionId": "DEF999911111",
  "eventSource": "WEB",
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
      },
      {
        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
      },
      {
        "address": {
          "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
          "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
          "regionCode": "PT",
          "postalCode": "1229-076"
        }
      }
    ],
  },
  "userProperties": {
    "customerType": "RETURNING"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

Создайте тело запроса

Объедините пункт Destination и Events в теле запроса:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 30.03,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       },
       "eventName": "purchase",
       "clientId": "1234567890.1761581763",
       "userId": "user_ABC12345",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_01"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12345",
             "quantity": 3,
             "unitPrice": 10.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Stan and Friends Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "2.22"
               },
               {
                 "parameterName": "index",
                 "value": "0"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]

       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 42.02,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       },
       "eventName": "purchase",
       "clientId": "9876543210.1761582117",
       "userId": "user_DEF9876",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_02"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12346",
             "quantity": 2,
             "unitPrice": 21.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Google Grey Women's Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "3.33"
               },
               {
                 "parameterName": "index",
                 "value": "1"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

1. Обновите заполнители в теле, такие как OPERATING_ACCOUNT_ID и PRODUCT_DESTINATION_ID значениями для вашей учетной записи и пункта назначения.
2. Установите validateOnly в true , чтобы проверить запрос без применения изменений. Когда будете готовы применить изменения, установите значение validateOnly в false .
3. Обратите внимание, что в этом примере шифрование не используется.

Отправить запрос

1. Скопируйте тело запроса с помощью кнопки «Копировать» в правом верхнем углу образца.
2. Нажмите кнопку API на панели инструментов.
3. Вставьте скопированное тело запроса в поле Текст запроса .
4. Нажмите кнопку «Выполнить» , заполните поля авторизации и просмотрите ответ.

Успешные ответы

Успешный запрос возвращает ответ с объектом, содержащим requestId .

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

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

Реакции на неудачи

Неудачный запрос приводит к появлению кода статуса ответа об ошибке, например 400 Bad Request , и ответа с подробными сведениями об ошибке.

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

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

emailAddress , который не хеширован и представлен только в шестнадцатеричном формате, возвращает следующий ответ:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Отправка событий по нескольким направлениям

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

Например, если у вас есть событие для действия-конверсии с идентификатором 123456789 и другое событие для действия-конверсии с идентификатором 777111122 , отправьте оба события в одном запросе, указав reference для каждого Destination . reference определяется пользователем. Единственное требование — чтобы у каждого Destination был уникальный reference . Вот изменённый список destinations для запроса:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

Настройте destinationReferences каждого Event , чтобы отправить его на один или несколько конкретных пунктов назначения. Например, вот Event , которое предназначено только для первого Destination , поэтому его список destinationReferences содержит только reference на первый Destination :

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "destination_a"
   ]
}

Поле destinationReferences представляет собой список, поэтому вы можете указать несколько пунктов назначения для события. Если вы не укажете destinationReferences для Event , API диспетчера данных отправит событие во все пункты назначения в запросе.

Если у события несколько пунктов назначения, API диспетчера данных отправляет соответствующие поля в каждый из них. Например, если у события есть пункт назначения Google Ads и пункт назначения Google Analytics, API включает поля Google Analytics, такие как clientId или eventName при отправке события в пункт назначения Google Analytics, а также поля Google Ads, такие как customVariables при отправке события в пункт назначения Google Ads.

Следующие шаги

• Настройте аутентификацию и настройте свою среду с помощью клиентской библиотеки.
• Узнайте о требованиях к форматированию, хешированию и кодированию для каждого типа данных.
• Узнайте, как шифровать данные пользователя .
• Узнайте, как получить диагностику по вашим запросам.
• Узнайте о передовом опыте .
• Узнайте о лимитах и ​​квотах .