Wysyłaj wydarzenia

Dzięki temu krótkiemu wprowadzeniu dowiesz się, jak wysyłać dane o zdarzeniach.

Używaj interfejsu Data Manager API w tych przypadkach:

  • Wysyłaj konwersje tagu Google Ads lub zdarzenia purchase Google Analytics jako dodatkowe źródło danych dla konwersji tagu, aby zmaksymalizować sygnały interakcji z reklamą i wzmocnić dane oraz ogólną skuteczność.

    Ta funkcja jest dostępna na wszystkich kontach Google Ads, ale tylko w przypadku usług Google Analytics znajdujących się na liście dozwolonych. Jeśli chcesz dodać usługę w Google Analytics do listy dozwolonych, wypełnij formularz.

  • Wysyłaj dane o zdarzeniach dotyczące konwersji offline lub konwersji rozszerzonych dotyczących potencjalnych klientów w Google Ads.

Wybierz wersję przewodnika, którą chcesz wyświetlić:

W tym krótkim wprowadzeniu wykonasz te czynności:

  1. Przygotuj Destination do odbierania danych zdarzenia.
  2. Przygotuj dane zdarzenia do wysłania.
  3. Utwórz żądanie IngestionService dotyczące zdarzeń.
  4. Wyślij żądanie za pomocą narzędzia Google APIs Explorer.
  5. Poznaj odpowiedzi o sukcesie i niepowodzeniu.

Przygotowywanie miejsc docelowych

Zanim wyślesz dane, musisz przygotować co najmniej 1 Destination. Oto przykładowy Destination, którego możesz użyć:

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

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

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

Oto pola Destination. Więcej informacji i przykłady miejsc docelowych w różnych scenariuszach znajdziesz w artykule Konfigurowanie miejsc docelowych.

operatingAccount

Konto, na które są przesyłane zdarzenia.

W przypadku zdarzeń przesyłanych jako dodatkowe źródło danych konto obsługujące może być kontem Google Ads lub usługą w Google Analytics.

Jeśli wartość parametru accountType to GOOGLE_ANALYTICS_PROPERTY, dane logowania w żądaniu muszą należeć do użytkownika Google Analytics, który ma rolę edytującego lub administratora w usłudze.

W przypadku konwersji offline i konwersji rozszerzonych dotyczących potencjalnych klientów konto operacyjne musi być kontem Google Ads.

loginAccount
Konto, na którym konto Google powiązane z danymi logowania jest użytkownikiem.
productDestinationId

Identyfikator elementu w operatingAccount, który otrzymuje zdarzenia.

W przypadku zdarzeń wysyłanych jako dodatkowe źródło danych productDestinationIdmusi być jednym z tych elementów:

  1. Identyfikator konwersji Google Ads, w której parametr type ma wartość WEBPAGE. W interfejsie Google Ads źródłem konwersji dla działania powodującego konwersję WEBPAGE jest Witryna.

  2. Identyfikator pomiaru strumienia danych z sieci w Google Analytics. Nie możesz wysyłać zdarzeń jako dodatkowego źródła danych do strumienia danych z aplikacji na iOS lub Androida w Google Analytics.

W przypadku konwersji offline lub konwersji rozszerzonych dotyczących potencjalnych klientów element productDestinationId musi być identyfikatorem działania powodującego konwersję w Google Ads, w którym parametr type ma wartość UPLOAD_CLICKS. W interfejsie Google Ads źródłem konwersji w przypadku działania powodującego konwersję UPLOAD_CLICKS jest Witryna (importowanie z kliknięć).

Przykład w tym przewodniku pokazuje, jak utworzyć żądanie, które wysyła każde zdarzenie do tego samego miejsca docelowego. Jeśli chcesz wysyłać zdarzenia do wielu miejsc docelowych w tym samym żądaniu, przeczytaj artykuł Wysyłanie zdarzeń do wielu miejsc docelowych.

Przygotowywanie danych zdarzenia

Rozważmy te dane zdarzenia. Każda tabela odpowiada jednemu zdarzeniu konwersji. Każde zdarzenie konwersji ma znacznik czasu zdarzenia, działanie powodujące konwersję i wartość konwersji.

Każde zdarzenie może zawierać identyfikatory reklam, np. gclid, lub identyfikatory użytkowników, np. adresy e-mail, numery telefonów i informacje o adresie. Wydarzenie może też mieć:

Oto dane wydarzenia:

Zdarzenie 1

Wydarzenie 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 30.03
currency USD
gclid GCLID_1
emails
given_name John
family_name Smith-Jones
region_code us
postal_code 94045
customer_type NEW
customer_value_bucket HIGH
client_id 1234567890.1761581763
user_id user_ABC12345
ad_unit_name Banner_01
event_name purchase
Produkty w koszyku
item_id SKU_12345
item_name Stan and Friends Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 2.22
item_index 0
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 10.01
item_quantity 3

Zdarzenie 2

Wydarzenie 2
conversion_time June 10, 2025 11:42:33PM America/New_York
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 42.02
currency eur
gclid GCLID_2
emails

zoe@EXAMPLE.COM

cloudy.sanfrancisco@gmail.com
given_name zoë
family_name pérez
region_code PT
postal_code 1229-076
customer_type RETURNING
client_id 9876543210.1761582117
user_id user_DEF9876
ad_unit_name Banner_02
event_name purchase
Produkty w koszyku
item_id SKU_12346
item_name Google Grey Women's Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 3.33
item_index 1
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 21.01
item_quantity 2

Formatowanie danych

Sformatuj pola zgodnie z informacjami podanymi w przewodniku po formatowaniu. Oto dane zdarzenia po sformatowaniu:

Zdarzenie 1

Wydarzenie 1
conversion_time 2025-06-10T15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 30.03
currency USD
gclid GCLID_1
emails
given_name john
family_name smith-jones
region_code US
postal_code 94045
customer_type NEW
customer_value_bucket HIGH
client_id 1234567890.1761581763
user_id user_ABC12345
ad_unit_name Banner_01
event_name purchase
Produkty w koszyku
item_id SKU_12345
item_name Stan and Friends Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 2.22
item_index 0
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 10.01
item_quantity 3

Zdarzenie 2

Wydarzenie 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 42.02
currency EUR
gclid GCLID_2
emails

zoe@example.com

cloudysanfrancisco@gmail.com
given_name zoë
family_name pérez
region_code PT
postal_code 1229-076
customer_type RETURNING
client_id 9876543210.1761582117
user_id user_DEF9876
ad_unit_name Banner_02
event_name purchase
Produkty w koszyku
item_id SKU_12346
item_name Google Grey Women's Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 3.33
item_index 1
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 21.01
item_quantity 2

Zaszyfruj i zakoduj dane.

Dodatkowo sformatowane adresy e-mail, imiona i nazwiska muszą być zahaszowane za pomocą algorytmu SHA-256 i zakodowane przy użyciu kodowania szesnastkowego lub Base64. Oto dane zdarzenia po sformatowaniu, zaszyfrowaniu i zakodowaniu za pomocą kodowania szesnastkowego:

Zdarzenie 1

Wydarzenie 1
conversion_time 2025-06-10T15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 30.03
currency USD
gclid GCLID_1
emails
given_name 96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A
family_name DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081
region_code US
postal_code 94045
customer_type NEW
customer_value_bucket HIGH
client_id 1234567890.1761581763
user_id user_ABC12345
ad_unit_name Banner_01
event_name purchase
Produkty w koszyku
item_id SKU_12345
item_name Stan and Friends Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 2.22
item_index 0
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 10.01
item_quantity 3

Zdarzenie 2

Wydarzenie 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 42.02
currency EUR
gclid GCLID_2
emails

3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250

223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4
given_name 2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450
family_name 6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F
region_code PT
postal_code 1229-076
customer_type RETURNING
client_id 9876543210.1761582117
user_id user_DEF9876
ad_unit_name Banner_02
event_name purchase
Produkty w koszyku
item_id SKU_12346
item_name Google Grey Women's Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 3.33
item_index 1
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 21.01
item_quantity 2

Konwertowanie danych na obiekty Event

Przekształć sformatowane i zaszyfrowane dane każdego zdarzenia w Event. Wypełnij te pola zgodnie z instrukcjami:

  1. Ustaw eventTimestamp na czas wystąpienia zdarzenia.

    Zdarzenia w Google Analytics muszą mieć wartość eventTimestamp w ciągu ostatnich 72 godzin.

  2. Ustaw wymagane pola dla swojego przypadku użycia.

    Przypadek użycia Identyfikatory transactionId eventSource
    Konwersje offline lub konwersje rozszerzone dotyczące potencjalnych klientów Wymagany. Ustaw co najmniej jedną z tych opcji: Opcjonalny Wymagany. Ustaw na jedną z wartości wyliczeniowych dla EventSource.
    Zdarzenia wysyłane jako dodatkowe źródło danych do miejsca docelowego Google Ads Wymagany. Ustaw co najmniej jedną z tych opcji: Wymagany Opcjonalnie. Jeśli jest ustawiona, musi mieć wartość WEB.
    Zdarzenia wysyłane jako dodatkowe źródło danych do miejsca docelowego w Google Analytics Wymagany. Ustaw co najmniej jedną z tych opcji: Wymagany Opcjonalnie. Jeśli jest ustawiona, musi mieć wartość WEB.

  3. Jeśli wysyłasz zdarzenia jako dodatkowe źródło danych do miejsca docelowego Google Ads, zapoznaj się z artykułem Jak Google obsługuje dane z dodatkowego źródła danych.

  4. Wypełnij pozostałe pola, w których masz wartość zdarzenia. Pełną listę dostępnych pól znajdziesz w Event dokumentacji.

Jak Google postępuje z danymi z dodatkowego źródła danych

W ramach tego samego działania powodującego konwersję Google używa parametru transactionId do usuwania zduplikowanych zdarzeń konwersji wysyłanych z różnych źródeł (np. z tagu witryny i z żądań przesyłania danych z interfejsu Data Manager API). W tabeli poniżej wyjaśniono, jak przetwarzane są dane z Twoich żądań dotyczących przesyłania danych.

Scenariusz Pole danych Sposób postępowania
transactionId PASUJE do istniejącego zdarzenia zarejestrowanego przez tag conversionValue (z: currencyCode)

Zaktualizowano. Wartość conversionValue (z currencyCode) z Event zastępuje pierwotną wartość zarejestrowaną przez tag.

Uwaga: w początkowym 14-dniowym okresie próbnym obejmującym działania powodujące konwersję aktualizacje wartości są wyłączone. Wartość zarejestrowana przez tag nie zostanie zastąpiona w raportach Google Ads do czasu zakończenia okresu próbnego.

transactionId PASUJE do istniejącego zdarzenia zarejestrowanego przez tag Inne pola z wyjątkiem conversionValue lub currencyCode (np. adIdentifiers.gclid) Ignorowane. Wartości innych pól z dodatkowego źródła danych nie zastąpią wartości w polach pierwotnie zarejestrowanych przez tag Google w przypadku dopasowanych transakcji.
transactionId NIE pasuje do żadnego istniejącego zdarzenia Wszystkie podane dane (np. userData,conversionValue, currencyCode)

Zostaje utworzone nowe zdarzenie konwersji. Google spróbuje następnie przypisać tę nową konwersję do kliknięcia reklamy z wykorzystaniem podanych przez Ciebie identyfikatorów (np. adIdentifiers.gclid lub userData).

Uwaga: w początkowym 14-dniowym okresie próbnym nowo utworzone konwersje będą widoczne w raportach, ale nie będą używane do określania stawek. Po zakończeniu okresu próbnego te konwersje staną się automatycznie dostępne na potrzeby określania stawek.

Dodawanie atrybutów sesji

Jeśli wysyłasz konwersje offline lub konwersje rozszerzone dotyczące potencjalnych klientów, dodaj atrybuty sesji, gdy inne identyfikatory reklamowe, takie jak identyfikator kliknięcia Google lub WBRAID, są niedostępne. Oprócz innych identyfikatorów reklam możesz też uwzględnić atrybuty sesji.

Atrybuty sesji zawierają dodatkowe informacje o kontekście i sygnałach dotyczących interakcji użytkownika z Twoją witryną. Pozwalają one zwiększyć dokładność pomiaru konwersji, raportowania i określania stawek.

W interfejsie Data Manager API możesz używać 2 sposobów przesyłania atrybutów sesji:

  1. Zalecane: ustaw pole sessionAttributes parametru adIdentifiers na ciąg atrybutów sesji zakodowany w formacie Base64. Aby zmodyfikować strony przesyłania formularza i rejestrować zakodowany ciąg znaków, postępuj zgodnie z instrukcjami w artykule Jak rejestrować parametr session_attributes.

  2. Jeśli nie możesz użyć JavaScriptu, zarejestruj poszczególne pola atrybutów sesji i dodaj je do listy experimentalFields jako osobne elementy:ExperimentalField

    • gad_campaignid
    • session_start_time_usec
    • gad_source
    • landing_page_url
    • landing_page_referrer

    Jeśli masz wartość atrybutu sesji landing_page_user_agent, wyślij ją w polu userAgent elementu adIdentifiers.landingPageDeviceInfo.

    Oto sprawdzone metody przesyłania poszczególnych par klucz-wartość:

    • Regularnie wysyłaj gad_campaignid i session_start_time_usec. Te pola są kluczowe dla dokładnej atrybucji.
    • Nie podawaj niedokładnej lub częściowej wartości landing_page_url, np. ciągu zastępczego, ścieżki aplikacji wewnętrznej lub niekompletnego adresu URL. Jeśli nie masz dokładnego, pełnego adresu URL, pomiń znak landing_page_url.

    Oto fragment przykładowego zdarzenia z wpisami w polach experimentalFields dla gad_campaignid i session_start_time_usec oraz klientem użytkownika w polu landingPageDeviceInfo:

    {
  ...,
  "experimentalFields": [
    {
      "field": "gad_campaignid",
      "value": "21288051566"
    },
    {
      "field": "session_start_time_usec",
      "value": "1767711548052000"
    }
  ],
  "adIdentifiers": {
    "landingPageDeviceInfo": {
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
    }
  }
}

Dodawanie informacji o Google Analytics

Jeśli miejsca docelowe zdarzenia wysłanego jako dodatkowe źródło danych obejmują usługę w Google Analytics, wypełnij te pola w podany sposób:

eventName

Wymagany. Nazwa zdarzenia w Google Analytics.

transactionId

Wymagany Unikalny identyfikator zdarzenia.

Co najmniej 1 identyfikator

Musisz ustawić wartość w co najmniej 1 polu z tej listy:

destinationReferences

Wymagany, jeśli lista destinations na poziomie żądania zawiera więcej niż 1 usługę Google Analytics Destination. Dodaj wpis do destinationReferences, aby określić, które miejsce docelowe w Google Analytics ma otrzymywać zdarzenie. Więcej informacji o odwołaniach do usług docelowych znajdziesz w artykule wysyłanie zdarzeń do wielu usług docelowych.

Jeśli parametr destinationReferences nie jest ustawiony lub zawiera wiele wpisów odnoszących się do miejsc docelowych Google Analytics, interfejs Data Manager API odrzuca zdarzenie z błędem MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT.

userId

Opcjonalnie. Identyfikator użytkownika.

additionalEventParameters

Opcjonalny, ale zalecany. Wypełnij tę listę dowolnymi parametrami zdarzeń Google Analytics, które nie są rejestrowane w innych polach Event. Parametry mogą obejmować dodatkowe zalecane parametry z purchasezdarzenia lub inne parametry, które chcesz rejestrować. Użyj nazwy parametru Google Analytics dla parameterName elementu EventParameter.

Jeśli na przykład masz podatki powiązane z transakcją, dodaj wpis do additionalEventParameters z atrybutem parameterName ustawionym na tax i atrybutem value ustawionym na koszt podatku.

Nie zalecamy dodawania wpisów dla parametrów zdarzeń transactionId, currency ani value Google Analytics. Zamiast tego wypełnij pola transactionId, currency i conversionValue w Event, które mają pierwszeństwo przed wszystkimi wpisami w additionalEventParameters.

Dodawanie danych koszyka do zdarzeń zakupu

Wypełnij pole cartData w obiekcie Event informacjami o zakupionych produktach. W przypadku każdego zakupionego produktu dodaj obiekt Item do listy items w obiekcie CartData i wypełnij te pola:

itemId
Wymagany. Unikalny identyfikator produktu.
unitPrice

Wymagany. Cena jednostkowa bez podatku, dostawy i rabatów w zakresie zdarzenia (na poziomie transakcji).

Jeśli produkt ma zniżkę ograniczoną do produktu, użyj obniżonej ceny jednostkowej. Jeśli na przykład produkt ma cenę jednostkową 27.67 i rabat jednostkowy 6.66, ustaw wartość unitPrice na 21.01.

quantity

Wymagany. Liczba zakupionych sztuk tego produktu.

additionalItemParameters

Wypełnij tę listę dowolnymi parametrami o zakresie obejmującym produkt, które nie są rejestrowane w innych polach Item. Użyj nazwy parametru zdarzenia w Google Analytics jako parameterName w przypadku ItemParameter.

Jeśli np. masz markę i kategorię produktu, dodaj wpis do additionalItemParameters produktu z parameterName ustawionym na item_brand i value ustawionym na nazwę marki, a także kolejny wpis z parameterName ustawionym na item_category i value ustawionym na kategorię produktu.

Nie zalecamy dodawania wpisów dla parametrów elementu quantity, price ani item_idGoogle Analytics. Zamiast tego wypełnij pola itemId, unitPrice i quantity w Item, które mają pierwszeństwo przed wszystkimi wpisami w additionalItemParameters.

Oto przykładowy Event sformatowanych, zaszyfrowanych i zakodowanych danych z drugiego zdarzenia, z dodatkowymi danymi dla 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"
          }
        ]
      }
    ]
  }
}

Tworzenie treści żądania

Połącz Destination i Events w treści żądania:

{
  "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. Zastąp symbole zastępcze w treści, np. OPERATING_ACCOUNT_ID i PRODUCT_DESTINATION_ID, wartościami dla Twojego konta i miejsca docelowego.
  2. Ustaw wartość validateOnly na true, aby zweryfikować prośbę bez stosowania zmian. Gdy zechcesz zastosować zmiany, ustaw validateOnly na false.
  3. Pamiętaj, że w tym przykładzie nie używamy szyfrowania.

Wysyłanie żądania

  1. Skopiuj treść żądania, korzystając z przycisku kopiowania w prawym górnym rogu przykładu.
  2. Na pasku narzędzi kliknij przycisk API.
  3. Wklej skopiowaną treść żądania do pola Treść żądania.
  4. Kliknij przycisk Wykonaj, postępuj zgodnie z wyświetlanymi instrukcjami autoryzacji i sprawdź odpowiedź.

Odpowiedzi o sukcesie

Żądanie zakończone pomyślnie zwraca odpowiedź z obiektem zawierającym requestId.

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

Zapisz zwrócony requestId, aby móc pobrać diagnostykę w miarę przetwarzania każdego miejsca docelowego w żądaniu.

Odpowiedzi o błędach

Nieudane żądanie powoduje zwrócenie kodu stanu odpowiedzi o błędzie, np. 400 Bad Request, oraz odpowiedzi ze szczegółami błędu.

Na przykład emailAddress zawierający ciąg tekstowy zamiast wartości zakodowanej w formacie szesnastkowym generuje tę odpowiedź:

{
  "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, który nie jest haszowany i jest tylko zakodowany w formacie szesnastkowym, generuje następującą odpowiedź:

{
  "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"
          }
        ]
      }
    ]
  }
}

Wysyłanie zdarzeń do wielu miejsc docelowych

Jeśli dane zawierają zdarzenia dotyczące różnych miejsc docelowych, możesz wysłać je w tym samym żądaniu, używając odwołań do miejsc docelowych.

Jeśli na przykład masz zdarzenie dla identyfikatora działania powodującego konwersję 123456789 i inne zdarzenie dla identyfikatora działania powodującego konwersję 777111122, wyślij oba zdarzenia w jednym żądaniu, ustawiając parametr reference każdego elementu Destination. Wartość reference jest zdefiniowana przez użytkownika. Jedynym wymaganiem jest to, aby każdy Destination miał unikalny reference. Oto zmodyfikowana lista destinations w przypadku żądania:

  "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"
    }
  ]

Ustaw destinationReferences każdego elementu Event, aby wysłać go do co najmniej jednego określonego miejsca docelowego. Oto na przykład Event, który dotyczy tylko pierwszego Destination, więc jego lista destinationReferences zawiera tylko reference pierwszego Destination:

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

Pole destinationReferences to lista, więc możesz określić wiele miejsc docelowych zdarzenia. Jeśli nie ustawisz parametru destinationReferences w przypadku parametru Event, interfejs Data Manager API wyśle zdarzenie do wszystkich miejsc docelowych w żądaniu.

Jeśli zdarzenie ma wiele miejsc docelowych, interfejs Data Manager API wysyła odpowiednie pola do każdego z nich. Jeśli np. zdarzenie ma miejsce docelowe w Google Ads i w Google Analytics, interfejs API zawiera pola Google Analytics, takie jak clientId lub eventName, gdy wysyła zdarzenie do miejsca docelowego w Google Analytics, oraz pola Google Ads, takie jak customVariables, gdy wysyła zdarzenie do miejsca docelowego w Google Ads.

Dalsze kroki

Wstecz
Przegląd zdarzeń