Ereignisse senden

In dieser Kurzanleitung erfahren Sie, wie Sie Ereignisdaten senden.

Verwenden Sie die Data Manager API für eines der folgenden Szenarien:

• Onlineereignisse: Senden Sie Ereignisdaten als zusätzliche Datenquelle für Ihre Tag-Conversions, um die Signale für Anzeigeninteraktionen zu maximieren und Ihre Daten und die Gesamtleistung zu verbessern.

• Offline-Ereignisse: Senden Sie Ereignisdaten für Offline-Conversions oder erweiterte Conversions für Leads.

Wählen Sie die gewünschte Version des Leitfadens aus:

Werbetreibender Datenpartner

In dieser Kurzanleitung führen Sie die folgenden Schritte aus:

1. Bereiten Sie ein Destination vor, um Ereignisdaten zu empfangen.
2. Ereignisdaten für den Versand vorbereiten
3. Erstellen Sie eine IngestionService-Anfrage für Ereignisse.
4. Senden Sie die Anfrage mit dem Google APIs Explorer.
5. Erfolgs- und Fehlerantworten verstehen

Ziel vorbereiten

Bevor Sie Daten senden können, müssen Sie das Ziel vorbereiten. Hier ist ein Beispiel für Destination, das Sie verwenden können:

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

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

• Legen Sie die accountId der operatingAccount auf die Google Ads-Konto-ID fest, an die die Ereignisdaten gesendet werden sollen. Die product des operatingAccount muss GOOGLE_ADS sein.

• Legen Sie productDestinationId auf die ID der Conversion-Aktion für die Ereignisse fest. Bei Online-Ereignissen muss die Conversion-Aktion eine Google Ads-Conversion-Aktion mit type = WEBPAGE sein. Bei Offline-Ereignissen muss die Conversion-Aktion eine Google Ads-Conversion-Aktion mit type sein, die auf UPLOAD_CLICKS festgelegt ist.

  In dieser Anleitung wird beschrieben, wie Sie eine Anfrage erstellen, mit der alle Ereignisse an dieselbe Conversion-Aktion gesendet werden. Wenn Sie Ereignisse für mehrere Conversion-Aktionen in derselben Anfrage senden möchten, lesen Sie den Abschnitt Mehrere Ziele.

Ereignisdaten vorbereiten

Sehen Sie sich die folgenden Ereignisdaten an. Jede Tabelle entspricht einem Conversion-Ereignis. Jedes Conversion-Ereignis hat einen Zeitstempel, eine Conversion-Aktion und einen Conversion-Wert.

Jedes Ereignis kann Werbe-IDs wie gclid oder Nutzer-IDs wie E‑Mail-Adressen, Telefonnummern und Adressinformationen enthalten. Ein Ereignis kann auch Informationen zum Nutzer enthalten, die zum Zeitpunkt des Ereignisses erfasst wurden, z. B. den Wert des Kunden oder ob es sich um einen neuen, wiederkehrenden oder reaktivierten Kunden handelt.

Hier sind die Daten des ersten Ereignisses:

Hier sind die Daten des zweiten Ereignisses:

Daten formatieren

Formatieren Sie die Felder gemäß der Formatierungsanleitung. Hier sind die Daten des ersten Ereignisses nach der Formatierung:

Hier sind die Daten des zweiten Ereignisses nach der Formatierung:

Daten hashen und codieren

Außerdem müssen die formatierten E‑Mail-Adressen, Vornamen und Nachnamen mit dem SHA‑256-Algorithmus gehasht und entweder mit Hexadezimal- oder Base64-Codierung codiert werden. Hier sind die Daten des ersten Ereignisses nach der Formatierung, dem Hashing und der Codierung mit Hexadezimalcodierung:

Hier sind die Daten des zweiten Ereignisses nach der Formatierung, dem Hashing und der Hexadezimalcodierung:

Konvertieren Sie die Daten in ein Event.

Konvertieren Sie die formatierten und gehashten Daten jedes Ereignisses in ein Event. Füllen Sie die folgenden Pflichtfelder aus:

• event_timestamp: Die Uhrzeit, zu der das Ereignis aufgetreten ist.
• transaction_id: Die eindeutige Kennung für das Ereignis.
• event_source: Die Quelle des Ereignisses. Erforderlich für Offlineereignisse. Optional für Online-Ereignisse. Wenn für eine Onlineveranstaltung angegeben, muss WEB sein.
• ad_identifiers oder user_data: Das Ereignis muss entweder eine Werbe-ID oder Nutzerdaten enthalten. Senden Sie beide, wenn Sie beide für das Ereignis haben.

Eine vollständige Liste der verfügbaren Felder finden Sie in der Referenzdokumentation zu Event. Geben Sie für jedes Feld, für das Sie einen Wert für das Ereignis haben, einen Wert ein.

Hier ist ein Beispiel für die Event für die formatierten, gehashten und codierten Daten aus dem zweiten Ereignis:

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

Anfragetext erstellen

Kombinieren Sie Destination und Events für den Anfragetext:

{
  "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",
       "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. Aktualisieren Sie die Platzhalter im Text, z. B. OPERATING_ACCOUNT_ID und CONVERSION_ACTION_1_ID, mit den Werten für Ihr Konto und Ziel.
2. Setzen Sie validateOnly auf true, um die Anfrage zu validieren, ohne die Änderungen anzuwenden. Wenn Sie die Änderungen anwenden möchten, setzen Sie validateOnly auf false.
3. In diesem Beispiel wird keine Verschlüsselung verwendet.

Anfrage senden

1. Kopieren Sie den Anfragetext mit der Schaltfläche zum Kopieren oben rechts im Beispiel.
2. Klicken Sie in der Symbolleiste auf die Schaltfläche API.
3. Fügen Sie den kopierten Anfragetext in das Feld Request body (Anfragetext) ein.
4. Klicken Sie auf die Schaltfläche Ausführen, folgen Sie der Anleitung zur Autorisierung und prüfen Sie die Antwort.

Erfolgsantworten

Eine erfolgreiche Anfrage gibt eine Antwort mit einem Objekt zurück, das eine requestId enthält.

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

Fehlerantworten

Eine fehlgeschlagene Anfrage führt zu einem Fehlerantwort-Statuscode wie 400 Bad Request und einer Antwort mit Fehlerdetails.

Wenn beispielsweise ein email_address einen Nur-Text-String anstelle eines hexadezimal codierten Werts enthält, wird die folgende Antwort zurückgegeben:

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

Eine email_address, die nicht gehasht und nur hexadezimal codiert ist, führt zu folgender Antwort:

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

Ereignisse für mehrere Ziele senden

Wenn Ihre Daten Ereignisse für verschiedene Ziele enthalten, können Sie sie mit Zielreferenzen im selben Request senden.

Wenn Sie beispielsweise ein Ereignis für die Conversion-Aktions-ID 123456789 und ein weiteres Ereignis für die Conversion-Aktions-ID 777111122 haben, senden Sie beide Ereignisse in einer einzelnen Anfrage, indem Sie die reference der einzelnen Destination festlegen. Der reference ist nutzerdefiniert. Die einzige Anforderung ist, dass jeder Destination einen eindeutigen reference hat. Hier ist die geänderte destinations-Liste für die Anfrage:

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

Legen Sie die destination_references jedes Event fest, um es an ein oder mehrere bestimmte Ziele zu senden. Hier ist beispielsweise ein Event, das nur für das erste Destination gilt. Die destination_references-Liste enthält also nur die reference des ersten Destination:

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

Das Feld destination_references ist eine Liste, sodass Sie mehrere Ziele für ein Ereignis angeben können. Wenn Sie die destination_references eines Event nicht festlegen, sendet die Data Manager API das Ereignis an alle Ziele in der Anfrage.

Nächste Schritte

• Konfigurieren Sie die Authentifizierung und richten Sie Ihre Umgebung mit einer Clientbibliothek ein.
• Weitere Informationen zu den Formatierungs-, Hash- und Codierungsanforderungen für die einzelnen Datentypen
• Informationen zum Verschlüsseln von Nutzerdaten
• Best Practices
• Weitere Informationen zu Limits und Kontingenten