The Data Manager API is in closed beta. To express interest in joining the closed beta, fill out this form.

Ta strona została przetłumaczona przez Cloud Translation API.

Wysyłaj wydarzenia

Aby dowiedzieć się więcej o wysyłaniu danych zdarzeń, zapoznaj się z tym przewodnikiem.

Dane o zdarzeniach to dodatkowe źródło danych o konwersjach tagu, które służy do maksymalizowania sygnałów interakcji z reklamą oraz wzmacniania danych i ogólnej skuteczności.

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

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

Przygotuj Destination, aby otrzymywać dane zdarzenia.
Przygotuj dane zdarzenia do wysłania.
Utwórz żądanie IngestionService dotyczące zdarzeń.
Wyślij żądanie za pomocą narzędzia Google APIs Explorer.
Poznaj odpowiedzi na powodzenie i niepowodzenie.

Przygotowanie miejsca docelowego

Zanim wyślesz dane, musisz przygotować miejsce docelowe. Oto przykładowa Destination:

    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

Ustaw accountId tagu operatingAccount na identyfikator konta Google Ads, które będzie otrzymywać dane zdarzenia. Wartość product w elementach operatingAccount musi wynosić GOOGLE_ADS.
Ustaw wartość parametru productDestinationId na identyfikator działania powodującego konwersję odpowiadający zdarzeniom. Działanie powodujące konwersję musi być działaniem powodującym konwersję Google Ads z ustawionym parametrem type na wartość WEBPAGE.

Z tego przewodnika dowiesz się, jak utworzyć żądanie, które wysyła każde zdarzenie do tego samego działania powodującego konwersję. Jeśli chcesz wysyłać zdarzenia dotyczące wielu działań powodujących konwersję w tym samym żądaniu, zapoznaj się z artykułem Wiele miejsc docelowych.

Przygotowywanie danych zdarzenia

Rozważ 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 mieć identyfikatory reklam, np. gclid, lub identyfikatory użytkowników, np. adresy e-mail, numery telefonów i informacje o adresie.

Oto dane pierwszego zdarzenia:

Zdarzenie 1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`last_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`

Oto dane drugiego zdarzenia:

Zdarzenie 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`zoe@EXAMPLE.COM` `cloudy.sanfrancisco@gmail.com`
`given_name`	`zoë`
`last_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`

Formatowanie danych

Sformatuj pola zgodnie z instrukcjami. Oto dane pierwszego zdarzenia po sformatowaniu:

Zdarzenie 1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`last_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`

Oto dane drugiego zdarzenia po sformatowaniu:

Zdarzenie 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`zoe@example.com` `cloudysanfrancisco@gmail.com`
`given_name`	`zoë`
`last_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`

zaszyfrować i zakodować dane;

Dodatkowo sformatowane adresy e-mail, imiona i nazwiska muszą zostać zaszyfrowane za pomocą algorytmu SHA-256 oraz zakodowane w formacie szesnastkowym lub Base64. Oto dane pierwszego zdarzenia po sformatowaniu, zaszyfrowaniu i zakodowaniu za pomocą kodowania szesnastkowego:

Zdarzenie 1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`last_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`

Oto dane drugiego zdarzenia po sformatowaniu, zaszyfrowaniu i zakodowaniu za pomocą kodowania szesnastkowego:

Zdarzenie 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`last_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`

Przekształcanie danych na `Event`

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

timestamp: czas wystąpienia zdarzenia.
transaction_id: unikalny identyfikator zdarzenia.
event_source: źródło zdarzenia. Jeśli wartość została określona, musi być równa EVENT_SOURCE_WEB.
ad_identifiers lub user_data: zdarzenie musi zawierać identyfikator reklamy lub dane użytkownika. Wyślij oba, jeśli masz oba.

Pełną listę dostępnych pól znajdziesz w dokumentacji Event. Wypełnij dowolne pole, w którym masz wartość zdarzenia.

Oto przykładowy Event z sformatowanymi, zaszyfrowanymi i zakodowanymi danymi z drugiego zdarzenia:

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "timestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "EVENT_SOURCE_WEB",
   "userData": {
      "userIdentifiers": [
         {
            "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
         },
         {
            "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
         },
         {
            "address": {
              "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
              "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
              "regionCode": "PT",
              "postalCode": "1229-076"
            }
         }
      ]
   }
}

Tworzenie treści żądania

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

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "timestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "lastName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "timestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "lastName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

Zaktualizuj symbole zastępcze w treści, np. OPERATING_ACCOUNT_ID i CONVERSION_ACTION_1_ID, zastępując je wartościami z Twojego konta i miejsca docelowego.
Aby zweryfikować żądanie bez stosowania zmian, ustaw wartość validateOnly na true. Gdy chcesz zastosować zmiany, ustaw wartość validateOnly na false.
Pamiętaj, że ta prośba nie używa szyfrowania.

Wysyłanie żądania

Skopiuj treść prośby, klikając przycisk kopiowania w prawym górnym rogu przykładu.
Otwórz stronę events.ingest.
Kliknij przycisk API po prawej stronie, a następnie w rozszerzonej sekcji kliknij przycisk Wypróbuj.
Wklej skopiowany tekst żądania do pola Treść żądania.
Kliknij przycisk Wykonaj, wypełnij prośby o autoryzację i sprawdź odpowiedź.

Odpowiedzi na pytania dotyczące powodzenia

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

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

Odpowiedzi na błąd

Nieudane żądanie powoduje zwrócenie kodu stanu odpowiedzi zawierającego błąd, np. 400 Bad Request, oraz odpowiedzi z szczegółami błędu.

Na przykład email_address zawierający ciąg tekstowy zamiast wartości zakodowanej szesnastkowo powoduje wyświetlenie tej odpowiedzi:

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

Wartość email_address, która nie jest zaszyfrowana i ma tylko kodowanie szesnastkowe, powoduje 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 Twoje dane zawierają zdarzenia dotyczące różnych miejsc docelowych, możesz je wysyłać w tym samym żądaniu, używając odwołań do miejsc docelowych.

Jeśli np. masz zdarzenie o identyfikatorze działania powodującego konwersję 123456789 i inne zdarzenie o identyfikatorze działania powodującego konwersję 777111122, prześlij oba zdarzenia w jednym żądaniu, ustawiając wartość reference dla każdego z tych Destination. reference jest zdefiniowany przez użytkownika – jedynym wymaganiem jest to, aby każdy element Destination miał unikalny reference. Oto zmodyfikowana lista destinations dla żądania:

  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122"
      "reference": "conversion_action_2"
    }
  ]

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

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

Pole destination_references jest listą, więc możesz określić wiele miejsc docelowych dla zdarzenia. Jeśli nie ustawisz parametru destination_references w Event, interfejs API menedżera danych wyśle zdarzenie do wszystkich miejsc docelowych w żądaniu.

Dalsze kroki

Skonfiguruj uwierzytelnianie i skonfiguruj środowisko za pomocą biblioteki klienta.
Dowiedz się więcej o wymaganiach dotyczących formatowania, szyfrowania i kodowania w przypadku poszczególnych typów danych.
Dowiedz się, jak szyfrować dane użytkowników.
Poznaj sprawdzone metody.
Dowiedz się więcej o limitach i kwotach.

Wysyłaj wydarzenia Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.