App-Conversion-Tracking und Remarketing – Spezifikationen für Anfragen/Antworten

App-User-Agent

Im Rahmen unserer Bemühungen zur Bekämpfung von Spam haben wir eine standardisierte Spezifikation für den User-Agent-Header entwickelt, der von einem Analyse-/Werbeprodukt im Namen eines App-Nutzers gesendet wird. Der User-Agent der App kann aus nativem Code abgeleitet werden, um die folgende Spezifikation einzuhalten:

name version (os_and_version; locale; device; build; Proxy)

Die Definition dieser Felder ist wie folgt:

User-Agent-Komponenten
name

Der Name des Analytics-/Werbeprodukts. (Google AdMob)

Wenn der User-Agent auf der Clientseite erstellt wird, sollte name stattdessen die Bundle-ID der Client-App sein.

Android
// Specified by API consumer.
iOS
// Specified by API consumer.
version

Die Version des Analyse-/Werbeprodukts. (7.10.1)

Android
// Specified by API consumer.
iOS
// Specified by API consumer.
os_and_version

Das Betriebssystem und die Betriebssystemversion, auf der die App ausgeführt wird. (Android 6.0 )

Android
String osAndVersion =
    "Android " + Build.VERSION.RELEASE;
iOS
UIDevice *uid =
  [UIDevice currentDevice];
NSString *osAndVersion =
  [NSString
    stringWithFormat:@"%@ %@",
    [uid systemName],
    [uid systemVersion]];
locale

Ein IETF-Gebietsschema-Tag für das Gerät mit einem aus zwei Buchstaben bestehenden Sprach- und Ländercode, die durch einen Unterstrich getrennt sind. (en_US)

Android
String locale = Locale.getDefault();
iOS
NSString *locale =
  [[NSLocale currentLocale]
    localeIdentifier]
device

Der Name des physischen Geräts, auf dem das Analytics-/Werbeprodukt ausgeführt wird. (iPhone9,1)

Android
String device = Build.MODEL;
iOS
@import Darwin.sys.sysctl;

NSString *device(void) {
  size_t bufferSize = 64;
  NSMutableData *buffer =
    [[NSMutableData alloc]
      initWithLength:bufferSize];
  int status =
    sysctlbyname("hw.machine",
      buffer.mutableBytes,
      &bufferSize, NULL, 0);
  if (status != 0) {
    return nil;
  }
  return [[NSString alloc]
    initWithCString:buffer.mutableBytes
    encoding:NSUTF8StringEncoding];
}
build

„Build/“, gefolgt von der Build-Nummer des Betriebssystems. (Build/13D15)

Android
String build = "Build/" + Build.ID;
iOS
@import Darwin.sys.sysctl;

NSString *build(void) {
  size_t bufferSize = 64;
  NSMutableData *buffer =
    [[NSMutableData alloc]
      initWithLength:bufferSize];
  int status =
    sysctlbyname("kern.osversion",
      buffer.mutableBytes,
      &bufferSize, NULL, 0);
  if (status != 0) {
    return nil;
  }
  return [[NSString alloc]
    initWithCString:buffer.mutableBytes
    encoding:NSUTF8StringEncoding];
}

Fügen Sie ; Proxy nur am Ende des App-User-Agents ein, wenn Sie den App-User-Agent serverseitig erstellen. Wenn der User-Agent der App vollständig auf Clientseite erstellt wird, schließen Sie ; Proxy aus. Der User-Agent einer App könnte also so aussehen:

  • Android: AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M; Proxy)
  • iOS: AdMob/7.10.1 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)

Leitfaden für Conversion-Tracking-Anfragen

Mit Conversion-Tracking-Anfragen wird Google Ads über ein App-Ereignis informiert, das als Conversion erfasst und/oder zum Erstellen einer Remarketing-Liste verwendet werden soll. Außerdem werden Metadaten zu allen Klicks abgerufen, die dem Ereignis vorausgingen.

Alle API-Aufrufe erfolgen an die Domain www.googleadservices.com. Conversion-Anfragen sind POST-Anfragen über HTTPS auf dem folgenden Pfad: 

/pagead/conversion/app/version
Dabei ist version die beabsichtigte Version der Conversion-Tracking-API.

Eine Standardanfrage für App-Conversions enthält die folgenden Parameter für die App Conversion API v1.1.

Antrag zum Conversion-Tracking
dev_token

Erforderlich

Standort: Abfrage

Das eindeutige, statische Entwicklertoken, das dem API-Nutzer ausgestellt wurde.

Z_eErE4DkvcKjDM1OVE4c4
link_id

Erforderlich

Standort: Abfrage

Die Link-ID, die das Entwicklertoken des API-Nutzers an eine bestimmte App bindet.

31FF8D67E5BB5DD5029DCC2734C2F884
app_event_type

Erforderlich

Standort: Abfrage

Der Name des App-Ereignisses, das aufgetreten ist. Dieses Feld ist eine Aufzählung und akzeptiert nur die folgenden Werte:

 • first_open
 • session_start
 • in_app_purchase
 • view_item_list
 • view_item
 • view_search_results
 • add_to_cart
 • ecommerce_purchase
 • custom

Das first_open-Ereignis sollte immer gesendet werden, um Installationen zuzuordnen, und das session_start-Ereignis sollte immer gesendet werden, um Sitzungen neu zuzuordnen. Verwenden Sie in_app_purchase für Käufe, die über den nativen App-Shop getätigt wurden, und ecommerce_purchase für alle anderen Käufe.
app_event_name

Unter bestimmten Bedingungen erforderlich

Standort: Abfrage

Der Name eines benutzerdefinierten App-Ereignisses, das im Feld app_event_type nicht akzeptiert wird. Dieses Feld sollte 1 bis 64 Unicode-Zeichen (mit UTF-8-Codierung) enthalten. Dieses Feld ist erforderlich, wenn app_event_type benutzerdefiniert ist.

level_achieved
Level Achieved

Dieses Feld darf keine der für app_event_type reservierten Werte enthalten. Wenn ein reservierter Ereignisname verwendet wird, gibt die API einen APP_EVENT_NAME_RESERVED_VALUE-Fehler zurück.
app_event_data

Optional

Standort: Körper

Leiten Sie alle zusätzlichen Rich-Event-Daten als einfaches JSON-Objekt weiter, in dem String-Schlüssel Werten zugeordnet werden. Zulässige Werte sind Strings und String-Arrays.

{"level": 5, "attempts": 20}
odm_info

Erforderlich, wenn die integrierte Conversion-Analyse unter iOS verwendet wird

Standort: Abfrage

Der Wert des Abfrageparameters info, der bei der Installation oder Neuinstallation einer iOS-App über das Google On Device Measurement (ODM): Event Data SDK erfasst wird. Mit diesem Feld wird die integrierte Conversion-Messung für iOS-App-Kampagnen aktiviert.

XYZr_AB8C-_zGtKjUhqtzPLeQ8lbJB5dADVR0tpZ9f-28sN5qN9GTZ_FztjL0OL
FzgxUJDhZr8w6lwGxAwPcxSwR5orjWepZiVP7sRRoCiaHerR-1TP17eJKtazgeSg
_CVEs13LllDTfrhVM8uWISqlg8dXobsLzmj8C7WrOlktHA5P_E23
id_type

Erforderlich

Der Typ der ID, die im Feld rdid übergeben wird.

Android

advertisingid
 
appsetid

iOS

idfa
 
idfv
rdid

Erforderlich

Standort: Abfrage

Ein gültiger UUID-String, der die Rohgeräte-ID darstellt.

f10e1de2-e237-4f50-b6aa-843c45cc63d6

Falls die Geräte-ID fehlt, z. B. die Geräte-ID eines Nutzers, der keine ATT-Einwilligung erteilt hat, setzen Sie sie auf „0“.

00000000-0000-0000-0000-000000000000
ctry_c

Erforderlich

Standort: Abfrage

Der zweistellige ISO-Ländercode für das Land, in dem die Conversion stattgefunden hat.

Dieses Feld ist erforderlich, um die App-Conversion-Messung auf Nicht-Nutzerebene unter iOS und Android zu aktivieren.

US, IN
eea

Unter bestimmten Bedingungen erforderlich

Standort: Abfrage

Der EWR-Geltungsbereich.

0: Die EU-Verordnungen gelten nicht für diesen Nutzer und diese Conversion.

1: Die EU-Verordnungen gelten für diesen Nutzer und diese Conversion. Wenn sich ein Nutzer beispielsweise im EWR befindet, fallen seine Daten unter die anwendbaren europäischen Verordnungen. 

*Required to be sent when the value is known.
ad_personalization

Unter bestimmten Bedingungen erforderlich

Standort: Abfrage

Die Flags für personalisierte Anzeigen

0: Der Endnutzer hat die Einwilligung zur Personalisierung von Anzeigen verweigert.

1: Der Endnutzer hat die Einwilligung zur Personalisierung von Anzeigen erteilt. 

*Required to be sent when the value is known.
ad_user_data

Unter bestimmten Bedingungen erforderlich

Standort: Abfrage

Das Einwilligungs-Flag für die Verwendung von Nutzerdaten zu Werbezwecken

0: Der Nutzer hat die Einwilligung zur Übermittlung von Daten auf Nutzerebene an Google zu Werbezwecken verweigert.

1: Der Nutzer hat die Einwilligung zur Übermittlung von Daten auf Nutzerebene an Google zu Werbezwecken erteilt. 

*Required to be sent when the value is known.
lat

Erforderlich

Standort: Abfrage

Status des Anzeigen-Trackings für das Gerät.

  • 0: Der Nutzer hat „Anzeigen-Tracking einschränken“ deaktiviert.
  • 1: Der Nutzer hat „Anzeigen-Tracking einschränken“ aktiviert.
app_version

Erforderlich

Standort: Abfrage

Die aktuelle Version der App. Sie sollte so standardisiert werden:

Android

packageManager.getPackageInfo(packageName(),
  PackageManager.GET_META_DATA).versionName

iOS

[[[NSBundle mainBundle] infoDictionary]
  objectForKey:@"CFBundleShortVersionString"]
 
1.2.4
os_version

Erforderlich

Standort: Abfrage

Die aktuelle Version des Host-Betriebssystems der App. Das sollte so standardisiert werden:

Android

android.os.Build.VERSION.RELEASE

iOS

[[UIDevice currentDevice] systemVersion]
sdk_version

Erforderlich

Standort: Abfrage

Die Version des SDK, mit dem das Ereignis erfasst wurde. Da diese Version hauptsächlich zum Debuggen verwendet wird, sollte sie der Releaseversion genau entsprechen, wie sie mit Ihren SDK-Releases veröffentlicht wird. Wenn die App kein SDK verwendet, übergeben Sie denselben Wert wie app_version.

1.9.5r6
timestamp

Erforderlich

Standort: Abfrage

Der UNIX-Zeitstempel des Conversion-Ereignisses in Sekunden mit einer Genauigkeit bis auf Mikrosekunden.

1432681913.123456
fot

Erforderlich

Standort: Abfrage

Der UNIX-Zeitstempel aus dem entsprechenden first_open in Sekunden mit Mikrosekunden-Genauigkeit für alle nachfolgenden Sitzungen und Ereignisse nach der Installation.

1432681913.123456
value

Optional

Standort: Abfrage

Der Geldwert des Ereignisses, falls vorhanden. Dieser Wert sollte immer als maschinenlesbarer Gleitkommawert formatiert werden, wobei ein Dezimalpunkt verwendet wird, um den Ganzzahl- und den Bruchteil des Werts zu trennen.

1.99
currency_code

Unter bestimmten Bedingungen erforderlich

Standort: Abfrage

Der ISO 4217-Währungscode für den Parameter value. Dieses Feld ist erforderlich, wenn der Parameter value angegeben und nicht leer ist.

USD
gclid

Unter bestimmten Bedingungen erforderlich

Standort: Abfrage

Der Wert des gclid-Suchparameters aus einer Deeplink-URL, über die die App geöffnet wurde.

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

Unter bestimmten Bedingungen erforderlich

Standort: Abfrage

Der Wert des Abfrageparameters gclid aus einer Deeplink-URL, die über die Play Install Referrer API aus dem Wert „install_referrer“ erfasst wurde.

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

Unter bestimmten Bedingungen erforderlich

Standort: Abfrage

Kennung für die gclid-basierte Zuordnung in Szenarien, in denen „rdid“ (advertisingid) not verfügbar ist oder alle zeroes UND entweder gclid oder market_referrer_gclid vorhanden sind.

1
gbraid

Unter bestimmten Bedingungen erforderlich

Standort: Abfrage

Der zuletzt gesehene gbraid-Wert, der über die Deeplink-URL gesendet wurde, mit der die App geöffnet wurde. Dieser Wert muss in der App zwischengespeichert werden, damit er mit den zukünftigen Conversions gesendet werden kann, die in der App erfolgen.

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
app_open_source

Unter bestimmten Bedingungen erforderlich

Standort: Abfrage

Wert zur Identifizierung von Deeplinks für Anzeigenklicks oder organischen App-Sitzungen.

ad_click or organic
User-Agent

Erforderlich

Standort: Header

Der App-User-Agent, wie im vorherigen Abschnitt definiert.

AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M)
X-Forwarded-For

Erforderlich

Standort: Header

Die öffentliche IPv4- oder IPv6-Adresse des Geräts, auf dem das Ereignis erfasst wurde.

216.58.194.174

Alle Anfragen müssen über HTTPS gesendet werden. Über HTTP empfangene Pings werden abgelehnt.

Wenn der Anfragetext leer ist (in Fällen, in denen keine Rich-Event-Daten in der app_event_data-Nutzlast übergeben werden), muss der Content-Length: 0-Header in der Anfrage explizit festgelegt werden.

Codierung von Ereignisdaten

Verwenden Sie für den app_event_data-Body-Parameter die folgenden Konventionen für primitive Datentypen:

  • Gleitkommazahl

    • Punkt als Dezimaltrennzeichen verwenden, unabhängig von der App-Lokalisierung
    • Verwenden Sie für Geldwerte eine Dezimalstelle mit zwei Ziffern, z. B. 2,99.
    • Verwenden Sie keine Exponentialschreibweise, z. B. 2E+9.
    • Verwenden Sie kein Komma, um Zifferngruppen zu trennen, z. B. 1.000.000.
    • Gültige Beispiele:
      • -0.5
      • 2.99
      • 1000000.123

  • Ganzzahl

    • Senden Sie nur ganzzahlige Werte ohne Dezimalstellen.
    • Verwenden Sie kein Komma, um Zifferngruppen zu trennen, z. B. 1.000.000.
    • Gültige Beispiele:
      • 1000
      • -11
      • 0

  • Datum

    • Datumsformat: JJJJ-MM-TT
      • yyyy = vierstelliges Jahr, z.B. 2016
      • mm = zweistelliger Monat, z.B. 09 für September
      • dd = zweistelliger Tag, z. B. 23 für den 23. Tag des Monats
    • Senden Sie immer die oben angegebene Anzahl von Ziffern.Wenn Sie beispielsweise den Wert für „dd“ für den 5. Tag des Monats senden, senden Sie 05.
    • Gültige Beispiele:
      • "2016-09-23"
      • "1990-12-31"

  • Timestamp

    • Zeitformat: Unix-/Epoch-Zeitstempel in Sekunden, definiert in der UTC-Zeitzone mit Mikrosekundenpräzision
    • Gültige Beispiele:
      • 1478713087 für Wed, 09 Nov 2016 17:38:07 GMT
      • 1073513982.123000 für Mittwoch, 07. Januar 2004, 22:19:42.123 GMT

  • Arrays

    • Nur Arrays mit primitiven Werten (Strings, Zahlen und boolesche Werte) senden
    • Gültige Beispiele:
      • [123, 456, 789]
      • ["abc"]

Beispielanfragen

Ein Beispiel für eine „first_open“-Anfrage mit dem SDK „On Device Measurement: Event Data“ für die integrierte Conversion-Messung:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &odm_info=abcdEfadGdaf
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Ein Beispiel für eine Anfrage vom Typ „Erstes Öffnen“ ohne das On-Device Measurement: Event Data SDK for Integrated Conversion Measurement:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Ein Beispiel für eine Anfrage nach der Installation mit dem On-Device-Measurement-SDK für Ereignisdaten für die integrierte Conversion-Messung:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &odm_info=abcdEfadGdaf
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &&fot=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Ein Beispiel für eine Anfrage zum ersten Öffnen ohne das On-Device Measurement: Event Data SDK:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfv
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Ein Beispiel für eine Anfrage zum ersten Öffnen für eine nicht deterministische Android-Conversion für ACAPI v1.1:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=appsetid
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &ctry_c=IN
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (android 11; en-GB; RMX2040; Build/_; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Ein Beispiel für eine gültige Conversion-Tracking-Anfrage mit einem nicht benutzerdefinierten Ereignistyp und Umsatzinformationen:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=0
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
 
{"app_event_data":{"item_id":["Crayons","Markers"]}}

Ein Beispiel für eine gültige Conversion-Tracking-Anfrage mit einem nicht benutzerdefinierten Ereignistyp und Umsatzinformationen, bei der rdid (advertisingid) nicht verfügbar ist:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; Android,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
 
{"app_event_data":{"item_id":["Crayons","Markers"]}}

Ein Beispiel für eine gültige Sitzungsstart-Anfrage:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Ein Beispiel für eine gültige Sitzungsstart-Reattribution-Anfrage für eine Sitzung, die über den Deeplink example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M gestartet wurde, ist:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &ad_personalization=1
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Ein Beispiel für eine gültige Conversion-Tracking-Anfrage für einen Nutzer im EWR, bei dem die Einwilligung zur Verwendung von Nutzerdaten für Werbung erteilt und die Personalisierung von Anzeigen abgelehnt wurde, ist:

POST /pagead/conversion/app/1.1
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=1
       &ad_personalization=0
       &ad_user_data=1
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Leitfaden für Antworten zum Conversion-Tracking

Die Antwort für das Conversion-Tracking hat das folgende Format:

{
  "ad_events": [<ad event objects>],
  "errors": [<error strings>],
  "attributed": true|false
}

Sowohl das Array ad_events als auch das Array errors können leer sein.

Wir gehen davon aus, dass Fehler maschinenlesbare Fehlercodes wie invalid_timestamp sein werden.

Fehlercodes

  • invalid_timestamp: Die Anfrage enthielt keinen gültigen Zeitstempel.

  • eea_missing_or_invalid: Entweder wurde das Feld „eea“ in der Anfrage nicht festgelegt oder es war ungültig.

  • ad_user_data_missing: Das Anfragefeld „ad_user_data“ wurde nicht festgelegt. Das Feld „ad_user_data“ ist für alle Anfragen erforderlich, die unter das DMA fallen.

  • ad_user_data_invalid: Der Anfragewert „ad_user_data“ war ungültig. Das Feld „ad_user_data“ ist für alle Anfragen erforderlich, die unter das DMA fallen.

  • ad_personalization_missing_or_invalid: Entweder war das Feld „ad_personalization“ in der Anfrage nicht festgelegt oder es war ungültig. Das Feld „ad_personalization“ ist für alle DMA-Anfragen erforderlich, die in den Anwendungsbereich fallen.

Anzeigenereignisse sind die Kernobjekte der App-Attribution und enthalten die folgenden Attribute.

Wichtige Hinweise zum Antwortverhalten in Abhängigkeit von der Einwilligung des Nutzers:
Wenn für die Conversion die Einwilligung zur Verwendung von Nutzerdaten für Werbung vorliegt und der Nutzer in seinen Google-Nutzereinstellungen die Einwilligung zur übergreifenden Verwendung erteilt hat, antwortet Google Ads mit einem einzelnen Last-Click über alle CPS hinweg. Wenn der Nutzer in seinen Google-Nutzereinstellungen nicht der Einwilligung zur übergreifenden Verwendung zugestimmt hat, antwortet Google Ads mit mehreren letzten Klicks auf CPS-Basis.

Wenn die Conversion bestimmte CPSs in der vom Nutzer ausgewählten Einwilligung zur dienstübergreifenden Nutzung, aber nicht andere enthält, gibt Google Ads einen einzelnen letzten Klick für die CPSs mit Einwilligung zur dienstübergreifenden Nutzung zurück, aber mehrere letzte Klicks für die CPSs ohne Einwilligung zur dienstübergreifenden Nutzung.

Antwort zum Conversion-Tracking
ad_event_id

Immer vorhanden

String

ad_event_id dient als eindeutige Kennung für Anzeigenereignisse. Sie wird in der Anfrage zur netzwerkübergreifenden Attribution wiederverwendet und sollte zu Debugging-Zwecken protokolliert/aufbewahrt werden.

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

Immer vorhanden

String

Der Conversion-Messwert, der für die Attribution verwendet wird. Anfangs wird nur eine Conversion-Messwert unterstützt.

conversion
timestamp

Immer vorhanden

Zahl

Der UNIX-Zeitstempel des Anzeigenereignisses in Sekunden mit einer Genauigkeit von Mikrosekunden. Dieser Wert sollte für die Attribution des letzten Klicks verwendet werden.

1432681913.123456
campaign_type

Immer vorhanden

String

In diesem Feld wird der Kampagnentyp angegeben, der das Anzeigenereignis ausgelöst hat. Folgende Werte sind möglich.

ACI
ACE
ACPre
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI ist die Abkürzung für „App-Installationskampagne“. ACE ist die Abkürzung für App-Interaktionskampagnen.
campaign_id

Immer vorhanden

Zahl

Die numerische Kampagnen-ID der Kampagne, die das Anzeigenereignis ausgelöst hat. Dieser Wert ist garantiert eindeutig.

123456789
campaign_name

Immer vorhanden

String

Der vom Werbetreibenden definierte Kampagnenname der Kampagne, die das Anzeigenereignis ausgelöst hat. Dieser Wert ist nicht zwangsläufig eindeutig.

Occasional Gamers (Video)
ad_type

Immer vorhanden

String

Der Typ der Anzeige, die zum Anzeigenereignis geführt hat. Mit diesem Wert können Sie zwischen verschiedenen Inventartypen unterscheiden.

App-Werbung 
ClickToDownload
 App-Interaktion 
AppDeepLink
 App-Interaktionen – Installations- und Fortsetzungsablauf 
AppDeepLinkContinue
 Catchall für andere Werte 
Unknown
external_customer_id

Immer vorhanden

Zahl

Die Werbetreibenden-ID des Werbetreibenden, dem die Kampagne gehört, die das Anzeigenereignis ausgelöst hat. Mit diesem Wert lassen sich Google Ads-Konten unterscheiden.

123456789
location

Immer vorhanden

Zahl

Der Standort-ID-Code für den geografischen Standort des Anzeigenereignisses. Informationen zum Interpretieren von Standortcodes finden Sie in der Google Ads API-Referenz.
network_type

Immer vorhanden

String

In diesem Feld wird das Google Ads-Werbenetzwerk angegeben, in dem das Anzeigenereignis stattgefunden hat. Folgende Werte sind möglich:

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

Ist null, wenn campaign_type ACI oder ACE und network_type Display ist.

String

In diesem Feld wird der „Subtyp“ des Google Ads-Werbenetzwerks angegeben, in dem das Anzeigenereignis aufgetreten ist. Die möglichen Werte variieren je nach primärem Netzwerktyp.

Normale Google Suche 
GoogleSearch
 Google Suchnetzwerk-Partner 
SearchPartners

Display

Publisher im mobilen Web 
mGDN
 App-Publisher 
Google AdMob

YouTube

YouTube-Videonetzwerk 
YouTubeVideos
 YouTube-Suchnetzwerk 
YouTubeSearch
 Videopartner 
VideoPartners

GoogleTv

Google TV-Videonetzwerk 
GoogleTvVideos

netzwerkübergreifend

Performance Max-Kampagnen – netzwerkübergreifend 
cross-network
video_id

Wird nur bereitgestellt, wenn network_type YouTube ist und campaign_type nicht ACI und ACE ist.

String

Die YouTube-Video-ID, die mit dem Anzeigenereignis verknüpft ist.

dQw4w9WgXcQ
keyword

Wird nur bereitgestellt, wenn network_type Search ist und campaign_type nicht ACI und ACE ist.

String

Das Such-Keyword, das mit dem Anzeigenereignis verknüpft ist.

+food +delivery
match_type

Wird nur bereitgestellt, wenn network_type Search ist und campaign_type nicht ACI und ACE ist.

String

Die Keyword-Option für Such-Keywords.

Genau passend 
e
 Wortgruppe 
p
 Weitgehend passend 
b
placement

Wird nur bereitgestellt, wenn network_type Display ist und campaign_type nicht ACI und ACE ist.

String

Das mit dem Anzeigenereignis verknüpfte Placement.

mobileapp::1-343200656
ad_group_id

Wird nur bereitgestellt, wenn campaign_type nicht Performance_Max ist.

Zahl

Die numerische ID der Anzeigengruppe, die das Anzeigenereignis ausgelöst hat. Dieser Wert ist garantiert eindeutig.

123456789
ad_group_name

Wird nur angegeben, wenn campaign_type ACI, ACE oder ACPRE ist.

String

Der vom Werbetreibenden definierte Name der Anzeigengruppe, in der das Anzeigenereignis aufgetreten ist. Dieser Wert ist nicht zwangsläufig eindeutig.

My App AdGroup
creative_id

Wird nur bereitgestellt, wenn campaign_type nicht ACI, ACE, ACPRE oder Performance_Max ist.

Zahl

Die numerische ID des Creative-Anzeigenblocks, der das Anzeigenereignis ausgelöst hat. Dieser Wert ist garantiert eindeutig.

123456789
interaction_type

Dieses Feld ist immer „Engagement“.

String
is_deterministic

Gibt an, ob die Attributionsmethode deterministisch ist.

Boolesch

true, false
device_model

Gerätemodell, das das Anzeigenereignis ausgelöst hat.

String

sm-s936w, sm-3936w
os_version

Die Hauptversion des Betriebssystems, die das Anzeigenereignis ausgelöst hat.

String

14, 12
country

Der zweistellige Ländercode, der das Anzeigenereignis ausgelöst hat.

String

CA, US
city

Die Stadt, in der das Anzeigenereignis stattgefunden hat.

String

san jose, london
region

Das Bundesland, in dem das Anzeigenereignis ausgelöst wurde.

String

california, british columbia

Beispielantworten

Beispiel für eine Antwort für eine deterministische Conversion:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "network_type": null,
    "network_subtype": null,
    "ad_group_id": null,
    "ad_group_name": null,
    "is_deterministic": true
    "timestamp": 1234567.898765,
  }],
  "errors": [],
  "attributed": true
}

Beispiel für eine Antwort für eine nicht deterministische Conversion unter iOS:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "network_type": null,
    "network_subtype": null,
    "ad_group_id": null,
    "ad_group_name": null,
    "is_deterministic": false
    },
    "device_info": {
        "device_model": "iphone12,3",
        "os_version": "14",
    },
    "timestamp": 1432681918.123456
    }],
  "errors": [],
  "attributed": true
}

Beispiel für eine Antwort für eine nicht deterministische Conversion unter Android:

{
  "ad_events": [
    {
      "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
      "conversion_metric": "conversion",
      "interaction_type": "click",
      "campaign_type": "ACI",
      "campaign_id": 123456789,
      "campaign_name": "My App Campaign",
      "network_type": null,
      "network_subtype": null,
      "ad_group_id": null,
      "ad_group_name": null,
      "is_deterministic": false
      "geo_info": {
        "city": "san jose"
        "country": "US"
        "region": "california"
      },
      "device_info": {
          "device_model": "sm-s926u",
          "os_version": "14",
      },
      "timestamp": 1432681918.123456
    },
    ],
    "errors": [],
    "warnings" [],
  }

Ein Beispiel für eine Antwort für eine iOS-/Android-Conversion, die auf „gbraid“ zurückgeführt wird:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "interaction_type": "engagement",
    "network_type": "NULL",
    "is_deterministic": true
    "timestamp": 0.000000,
  }],
  "errors": [],
  "attributed": true
  "warnings" [],
}

Ein Beispiel für eine Conversion-Tracking-Antwort, wenn die Anfrage Fehler enthielt:

{
  "ad_events": [],
  "errors": ["INVALID_CURRENCY_CODE"],
  "attributed": false
}

Beispiel für eine negative Antwort auf Conversion-Tracking:

{
  "ad_events": [],
  "errors": [],
  "attributed": false
}

Für alle Conversion-Tracking-Anfragen wird eine Conversion-Tracking-Antwort zurückgegeben.

Ein Beispiel für eine bestätigende Conversion-Tracking-Antwort für einen Nutzer außerhalb des EWR für eine universelle App-Kampagne:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "GoogleSearch",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Ein Beispiel für eine bestätigende Conversion-Tracking-Antwort für einen Nutzer außerhalb des EWR für eine Suchkampagne:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Search",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "GoogleSearch",
    "video_id": null,
    "keyword": "+space +birds",
    "match_type": "b",
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Beispiel für eine bestätigende Antwort zum Conversion-Tracking für einen Nutzer außerhalb des EWR für eine Displaykampagne:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Display",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "mGDN",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": "mobile-app::2-343200656",
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}

Ein Beispiel für eine bestätigende Antwort zum Conversion-Tracking für einen Nutzer außerhalb des EWR für eine YouTube-Kampagne:

{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "engagement",
    "campaign_type": "Video",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "YouTube",
    "network_subtype": "YouTubeVideos",
    "video_id": "dQw4w9WgXcQ",
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": 123456789,
    "ad_group_name": "My App AdGroup",
    "creative_id": 123456789,
    "timestamp": 1432681913.123456
  }],
  "errors": [],
  "attributed": true,
  "warnings": []
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  {
    "ad_event_id": "I8YUwWqxvOyqcwOcqBAkYZBMaOONSd",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Search",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}
 
{
  "ad_events": [{
    "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Display",
    "network_subtype": "",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  {
    "ad_event_id": "I8YUwWqxvOyqcwOcqBAkYZBMaOONSd",
    "conversion_metric": "conversion",
    "interaction_type": "click",
    "campaign_type": "ACI",
    "campaign_id": 123456789,
    "campaign_name": "My App Campaign",
    "ad_type": "ClickToDownload",
    "external_customer_id": 123456789,
    "location": 21144,
    "network_type": "Youtube",
    "network_subtype": "YouTubeVideos",
    "video_id": null,
    "keyword": null,
    "match_type": null,
    "placement": null,
    "ad_group_id": null,
    "ad_group_name": "",
    "creative_id": null,
    "timestamp": 1432681913.123456
  },
  ],
  "errors": [],
  "warnings": [],
  "attributed": true
}


Anfrage zur netzwerkübergreifenden Attribution

Wenn Google Ads positiv auf eine Conversion-Tracking-Anfrage antwortet, muss der API-Nutzer Google Ads über seine netzwerkübergreifende Attributionsentscheidung informieren, nachdem er den letzten Klick ermittelt hat.

Die ursprungsübergreifende Attributionsanfrage ist mit der ursprünglichen Anfrage zum Conversion-Tracking identisch, hat aber den folgenden Anfragepfad:

/pagead/conversion/app/1.1/cross_network

und das Hinzufügen von zwei erforderlichen Parametern:

Anfrage zur netzwerkübergreifenden Attribution
ad_event_id

Erforderlich

Standort: Abfrage

Die ad_event_id-Kennung aus dem Anzeigenereignis, das mit der Zuordnung in der vorherigen Anfrage verknüpft ist.
attributed

Erforderlich

Standort: Abfrage

Gibt an, ob Google Ads vom API-Nutzer eine Gutschrift für die Conversion erhalten hat. 0 oder 1.

Ein Beispiel für eine gültige netzwerkübergreifende Attributionsanfrage:

POST /pagead/conversion/app/1.1/cross_network
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=custom
       &app_event_name=level_achieved
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &value=1.99
       &currency_code=USD
       &ad_event_id=Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
       &attributed=1
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8

Für eine gültige netzwerkübergreifende Attributionsanfrage wird immer eine generische 200-Antwort ohne Antworttext zurückgegeben.