Wysyłaj wydarzenia

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

Użyj interfejsu Data Manager API w jednym z tych przypadków:

• Zdarzenia online: wysyłaj dane o zdarzeniach jako dodatkowe źródło danych o konwersjach tagu, aby maksymalizować sygnały interakcji z reklamą oraz wzmacniać dane i ogólną skuteczność.

• Zdarzenia offline: wysyłaj dane o zdarzeniach dotyczące konwersji offline lub konwersji rozszerzonych dotyczących potencjalnych klientów.

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

Reklamodawca Partner danych

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 miejsca docelowego

Zanim wyślesz dane, musisz przygotować miejsce docelowe, do którego chcesz je przesłać. Oto przykładowy kod Destination, którego możesz użyć:

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

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

• Ustaw accountId parametru operatingAccount na identyfikator konta Google Ads, na które będą przesyłane dane o zdarzeniach. Wartość accountType elementu operatingAccount musi wynosić GOOGLE_ADS.

• Ustaw wartość productDestinationId na identyfikator działania powodującego konwersję w przypadku zdarzeń. W przypadku wydarzeń online działanie powodujące konwersję musi być działaniem powodującym konwersję Google Ads, w którym parametr type ma wartość WEBPAGE. W przypadku wydarzeń offline działanie powodujące konwersję musi być działaniem powodującym konwersję w Google Ads, w którym parametr type ma wartość UPLOAD_CLICKS.

  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 informacjami o wielu miejscach 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. Zdarzenie może też zawierać informacje o użytkowniku oceniane w momencie zdarzenia, takie jak wartość klienta lub to, czy jest on nowym, powracającym czy ponownie zaangażowanym klientem.

Oto dane pierwszego zdarzenia:

Oto dane drugiego wydarzenia:

Formatowanie danych

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

Oto dane drugiego wydarzenia po sformatowaniu:

Zaszyfruj i zakoduj dane.

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

Oto dane drugiego zdarzenia po sformatowaniu, utworzeniu skrótu i zakodowaniu przy użyciu kodowania szesnastkowego:

Przekształć dane w Event.

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

• event_timestamp: czas wystąpienia zdarzenia.
• event_source: źródło zdarzenia. Wymagany w przypadku zdarzeń offline. Opcjonalny w przypadku wydarzeń online. Jeśli jest określony w przypadku wydarzenia online, musi mieć wartość WEB.
• ad_identifiers lub user_data: zdarzenie musi zawierać identyfikator reklamy lub dane użytkownika. Jeśli masz oba te rodzaje danych, wyślij je oba.

Jeśli wysyłasz konwersje offline jako dodatkowe źródło danych, aby zwiększyć skuteczność i ilość danych, wymagany jest parametr transaction_id. W przeciwnym razie atrybut transaction_id jest opcjonalny, ale zalecany.

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

Oto przykładowy Event sformatowanych, zaszyfrowanych i zakodowanych danych z drugiego zdarzenia:

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "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"
      }
   }
}

Tworzenie treści żądania

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

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

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "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"
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "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"
       }
     }
  ],
  "validateOnly": true
}

1. Zastąp symbole zastępcze w treści, np. OPERATING_ACCOUNT_ID i CONVERSION_ACTION_1_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 w polu Request body (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 email_address 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"
          }
        ]
      }
    ]
  }
}

email_address, który nie jest haszowany i jest tylko zakodowany 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]",
            "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 wartość reference każdego parametru Destination. reference jest definiowany przez użytkownika. Jedynym wymaganiem jest to, aby każdy Destination miał unikalny reference. Oto zmodyfikowana lista destinations w przypadku żądania:

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

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

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

Ustaw destination_references 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 destination_references 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": [
      "conversion_action_1"
   ]
}

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

Dalsze kroki

• Skonfiguruj uwierzytelnianie i skonfiguruj środowisko za pomocą biblioteki klienta.
• Poznaj wymagania dotyczące formatowania, szyfrowania i kodowania poszczególnych typów danych.
• Dowiedz się, jak szyfrować dane użytkowników.
• Dowiedz się, jak pobrać diagnostykę dotyczącą Twoich próśb.
• Dowiedz się więcej o sprawdzonych metodach.
• Dowiedz się więcej o limitach.