Śledzenie konwersji z aplikacji i remarketing – specyfikacje żądań/odpowiedzi

Klient użytkownika aplikacji

W ramach szerszych działań mających na celu zwalczanie spamu opracowaliśmy standardową specyfikację nagłówka User-Agent wysyłanego przez usługę analityczną lub reklamową w imieniu użytkownika aplikacji. Ciąg User-Agent aplikacji może być generowany na podstawie kodu natywnego, aby był zgodny z tą specyfikacją:

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

Definicje tych pól są następujące:

Komponenty klienta użytkownika
name

Nazwa usługi analitycznej lub reklamowej. (Google AdMob)

Pamiętaj, że jeśli klient użytkownika jest tworzony po stronie klienta, zamiast name powinien być używany identyfikator pakietu aplikacji klienta.

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

Wersja usługi analitycznej lub reklamowej. (7.10.1)

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

System operacyjny i jego wersja, na których działa aplikacja. (Android 6.0 )

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

Tag języka IETF dla urządzenia, w którym dwuliterowy kod języka i kodu kraju są oddzielone podkreśleniem. (en_US)

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

Nazwa urządzenia fizycznego, na którym działa usługa analityczna lub reklamowa. (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/” z numerem kompilacji systemu operacyjnego. (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];
}

Podczas tworzenia po stronie serwera ciągu User-Agent aplikacji dodawaj znak ; Proxy tylko na końcu tego ciągu. Jeśli klient użytkownika aplikacji jest w całości tworzony po stronie klienta, wyklucz ; Proxy. Klient użytkownika aplikacji może wyglądać tak:

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

Przewodnik po żądaniach śledzenia konwersji

Celem żądań śledzenia konwersji jest powiadomienie Google Ads o zdarzeniu w aplikacji, które powinno być śledzone jako konwersja lub używane do wypełniania listy remarketingowej, oraz pobranie metadanych opisujących kliknięcie, które poprzedziło zdarzenie.

Wszystkie wywołania interfejsu API są kierowane do domeny www.googleadservices.com. Żądania konwersji to żądania POST przesyłane przez HTTPS w tej ścieżce: 

/pagead/conversion/app/version
gdzie version to docelowa wersja interfejsu API śledzenia konwersji.

Standardowe żądanie konwersji w aplikacji będzie zawierać te parametry interfejsu App Conversion API w wersji 1.1.

Prośba o śledzenie konwersji
dev_token

Wymagany

Lokalizacja: zapytanie

Unikalny, statyczny token dewelopera wydany konsumentowi interfejsu API.

Z_eErE4DkvcKjDM1OVE4c4
link_id

Wymagany

Lokalizacja: zapytanie

Identyfikator linku wiążący token programisty użytkownika interfejsu API z konkretną aplikacją.

31FF8D67E5BB5DD5029DCC2734C2F884
app_event_type

Wymagany

Lokalizacja: zapytanie

Nazwa zdarzenia w aplikacji, które wystąpiło. To pole jest wyliczeniem i akceptuje tylko te wartości:

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

Zdarzenie first_open należy zawsze wysyłać w celu przypisywania instalacji, a zdarzenie session_start – w celu ponownego przypisywania sesji. Używaj in_app_purchase w przypadku zakupów dokonanych w natywnym sklepie z aplikacjami, a ecommerce_purchase w przypadku wszystkich innych zakupów.
app_event_name

Wymagane pod pewnymi warunkami

Lokalizacja: zapytanie

Nazwa dowolnego zdarzenia niestandardowego w aplikacji, które nie jest akceptowane w polu app_event_type. To pole powinno zawierać od 1 do 64 znaków Unicode (z użyciem kodowania UTF-8). To pole jest wymagane, jeśli app_event_type ma wartość custom.

level_achieved
Level Achieved

To pole nie może zawierać żadnej z wartości zarezerwowanych dla app_event_type. Jeśli użyjesz zarezerwowanej nazwy zdarzenia, interfejs API zwróci APP_EVENT_NAME_RESERVED_VALUE błąd.
app_event_data

Opcjonalny

Lokalizacja: ciało

Przekaż wszelkie dodatkowe dane zdarzenia rozszerzonego jako prosty obiekt JSON mapujący klucze ciągów znaków na wartości. Dopuszczalne wartości to ciągi tekstowe i tablice ciągów tekstowych.

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

Wymagany w przypadku korzystania ze zintegrowanego pomiaru konwersji w systemie iOS

Lokalizacja: zapytanie

Wartość parametru zapytania info, która jest rejestrowana podczas instalacji lub ponownej instalacji aplikacji na iOS z pakietu Google On Device Measurement (ODM): Event Data SDK. To pole umożliwia zintegrowany pomiar konwersji w kampaniach promujących aplikacje na iOS.

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

Wymagany

Typ identyfikatora przekazanego w polu rdid.

Android

advertisingid
 
appsetid

iOS

idfa
 
idfv
rdid

Wymagany

Lokalizacja: zapytanie

Prawidłowy ciąg tekstowy UUID reprezentujący identyfikator urządzenia w formacie surowym.

f10e1de2-e237-4f50-b6aa-843c45cc63d6

Jeśli identyfikator urządzenia jest niedostępny, np. w przypadku użytkownika, który nie wyraził zgody na ATT, ustaw go na same zera.

00000000-0000-0000-0000-000000000000
ctry_c

Wymagany

Lokalizacja: zapytanie

Dwuliterowy kod kraju w standardzie ISO wskazujący kraj, z którego pochodzi konwersja.

To pole jest wymagane, aby włączyć pomiar konwersji z aplikacji nie na poziomie użytkownika na urządzeniach z iOS i Androidem.

US, IN
eea

Wymagane pod pewnymi warunkami

Lokalizacja: zapytanie

Zakres Europejskiego Obszaru Gospodarczego.

0: rozporządzenia europejskie nie mają zastosowania do tego użytkownika ani konwersji.

1: rozporządzenia europejskie mają zastosowanie do tego użytkownika i konwersji. Jeśli na przykład użytkownik znajduje się na terenie Europejskiego Obszaru Gospodarczego, podlega on odpowiednim rozporządzeniom europejskim. 

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

Wymagane pod pewnymi warunkami

Lokalizacja: zapytanie

Flagi dotyczące reklam spersonalizowanych:

0: użytkownik odmówił zgody na personalizację reklam.

1: użytkownik wyraził zgodę na personalizację reklam. 

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

Wymagane pod pewnymi warunkami

Lokalizacja: zapytanie

Flaga zgody na wykorzystywanie danych użytkowników w celach reklamowych.

0: użytkownik odmówił zgody na przekazywanie do Google danych na poziomie użytkownika w celach reklamowych.

1: użytkownik wyraził zgodę na przekazywanie do Google danych na poziomie użytkownika w celach reklamowych. 

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

Wymagany

Lokalizacja: zapytanie

Stan ograniczenia śledzenia reklam na urządzeniu.

  • 0: użytkownik nie ogranicza śledzenia reklam.
  • 1: użytkownik ogranicza śledzenie reklam.
app_version

Wymagany

Lokalizacja: zapytanie

Bieżąca wersja aplikacji. Powinna być ujednolicona w ten sposób:

Android

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

iOS

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

Wymagany

Lokalizacja: zapytanie

Bieżąca wersja systemu operacyjnego hosta aplikacji. Powinno być ujednolicone w ten sposób:

Android

android.os.Build.VERSION.RELEASE

iOS

[[UIDevice currentDevice] systemVersion]
sdk_version

Wymagany

Lokalizacja: zapytanie

Wersja pakietu SDK, która zmierzyła zdarzenie. Ponieważ jest to używane głównie do debugowania, powinno odzwierciedlać wersję opublikowaną dokładnie tak, jak jest ona publikowana w wersjach SDK. Jeśli aplikacja nie korzysta z pakietu SDK, przekaż tę samą wartość co app_version.

1.9.5r6
timestamp

Wymagany

Lokalizacja: zapytanie

Sygnatura czasowa systemu UNIX, w której wystąpiło zdarzenie konwersji, w sekundach z dokładnością do mikrosekund.

1432681913.123456
fot

Wymagany

Lokalizacja: zapytanie

Sygnatura czasowa UNIX z odpowiedniego parametru first_open w sekundach z dokładnością do mikrosekund w przypadku wszystkich kolejnych sesji i zdarzeń po instalacji.

1432681913.123456
value

Opcjonalny

Lokalizacja: zapytanie

Wartość pieniężna zdarzenia (jeśli występuje). Wartość ta powinna być zawsze sformatowana jako liczba zmiennoprzecinkowa czytelna dla komputera, z użyciem kropki dziesiętnej do oddzielenia części całkowitej i ułamkowej.

1.99
currency_code

Wymagane pod pewnymi warunkami

Lokalizacja: zapytanie

Kod waluty w formacie ISO 4217 parametru value. To pole jest wymagane, jeśli podano parametr value i nie jest on pusty.

USD
gclid

Wymagane pod pewnymi warunkami

Lokalizacja: zapytanie

Wartość parametru zapytania gclid z adresu URL precyzyjnego linku, który otworzył aplikację.

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

Wymagane pod pewnymi warunkami

Lokalizacja: zapytanie

Wartość parametru zapytania gclid z adresu URL precyzyjnego linku pobranego z wartości install_referrer za pomocą interfejsu Play Install Referrer API.

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

Wymagane pod pewnymi warunkami

Lokalizacja: zapytanie

Identyfikator na potrzeby atrybucji opartej na gclid w sytuacjach, gdy rdid (advertisingid) jest not dostępny lub wszystkie zeroes ORAZ występuje gclid lub market_referrer_gclid.

1
gbraid

Wymagane pod pewnymi warunkami

Lokalizacja: zapytanie

Ostatnia wartość gbraid wysłana za pomocą adresu URL precyzyjnego linku, który otworzył aplikację. Pamiętaj, że musi być ona przechowywana w pamięci podręcznej aplikacji, aby można ją było wysyłać z przyszłymi konwersjami, które nastąpią w aplikacji.

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
app_open_source

Wymagane pod pewnymi warunkami

Lokalizacja: zapytanie

Wartość służąca do identyfikowania precyzyjnych linków do kliknięć reklam lub sesji w aplikacji pochodzących z wyników wyszukiwania.

ad_click or organic
User-Agent

Wymagany

Lokalizacja: nagłówek

Klient użytkownika aplikacji zdefiniowany w poprzedniej sekcji.

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

Wymagany

Lokalizacja: nagłówek

Publiczny adres IPv4 lub IPv6 urządzenia, na którym zarejestrowano zdarzenie.

216.58.194.174

Wszystkie żądania muszą być wysyłane przez HTTPS. Pingi otrzymane przez HTTP zostaną odrzucone.

Pamiętaj, że jeśli treść żądania jest pusta (w przypadku, gdy w app_event_data ładunku nie są przekazywane żadne dane zdarzenia rozszerzonego), nasz serwer wymaga, aby w żądaniu wyraźnie ustawić nagłówek Content-Length: 0.

Kodowanie danych zdarzenia

W przypadku parametru app_event_data body używaj tych konwencji dotyczących podstawowych typów danych:

  • Float

    • Używaj kropki jako separatora dziesiętnego niezależnie od lokalizacji aplikacji.
    • Do przedstawiania wartości pieniężnych używaj precyzji do dwóch miejsc po przecinku, np. 2,99.
    • Nie używaj notacji wykładniczej, np.2E+9.
    • Nie używaj przecinka do rozdzielania grup cyfr, np. 1 000 000
    • Przykłady prawidłowych ofert:
      • -0.5
      • 2.99
      • 1000000.123

  • Liczba całkowita

    • Wysyłaj tylko wartości całkowite bez cyfr po przecinku.
    • Nie używaj przecinka do oddzielania grup cyfr, np.1 000 000.
    • Przykłady prawidłowych ofert:
      • 1000
      • -11
      • 0

  • Data

    • Format daty: rrrr-mm-dd
      • yyyy = czterocyfrowy rok, np. 2016
      • mm = miesiąc zapisany dwiema cyframi, np. 09 to wrzesień
      • dd = dzień zapisany dwiema cyframi, np. 23 – 23 dzień miesiąca
    • Zawsze wysyłaj liczbę cyfr podaną powyżej. Jeśli na przykład wysyłasz wartość dla dd dla 5 dnia miesiąca, wyślij 05.
    • Przykłady prawidłowych ofert:
      • "2016-09-23"
      • "1990-12-31"

  • Sygnatura czasowa

    • Format czasu: sygnatura czasowa systemu Unix/Epoch w sekundach zdefiniowana w strefie czasowej UTC z dokładnością do mikrosekund.
    • Przykłady prawidłowych ofert:
      • 1478713087 for Wed, 09 Nov 2016 17:38:07 GMT
      • 1073513982.123000 for Wed, 07 Jan 2004 22:19:42.123 GMT

  • Tablice

    • Wysyłaj tylko tablice wartości pierwotnych (ciągi znaków, liczby i wartości logiczne).
    • Prawidłowe przykłady:
      • [123, 456, 789]
      • ["abc"]

Przykładowe żądania

Przykład żądania pierwszego otwarcia z pomiarem na urządzeniu: dane zdarzeń pakiet SDK do zintegrowanego pomiaru konwersji:

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

Przykład żądania pierwszego otwarcia bez pakietu 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

Przykład żądania po instalacji z pakietem 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
       &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

Przykład żądania pierwszego otwarcia bez pomiaru na urządzeniu: pakiet SDK danych zdarzenia:

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

Przykład żądania pierwszego otwarcia w przypadku niedeterministycznej konwersji na Androidzie w ACAPI w wersji 1.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

Przykład prawidłowego żądania śledzenia konwersji z niestandardowym typem zdarzenia i informacjami o przychodach:

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

Przykład prawidłowego żądania śledzenia konwersji z niestandardowym typem zdarzenia i informacjami o przychodach, w którym identyfikator rdid (advertisingid) jest niedostępny:

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

Przykład prawidłowego żądania rozpoczęcia sesji:

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

Przykład prawidłowego żądania ponownego przypisania rozpoczęcia sesji w przypadku sesji, która rozpoczęła się od precyzyjnego linku example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M:

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

Przykład prawidłowego żądania śledzenia konwersji w przypadku użytkownika z Europejskiego Obszaru Gospodarczego, który wyraził zgodę na wykorzystywanie danych użytkownika na potrzeby reklam, ale nie zgodził się na personalizację reklam:

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

Przewodnik po odpowiedziach dotyczących śledzenia konwersji

Odpowiedź śledzenia konwersji ma taki format:

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

Obie tablice ad_events i errors mogą być puste.

Spodziewamy się, że błędy będą miały postać kodów błędów odczytywanych przez maszyny, np. invalid_timestamp.

Kody błędów

  • invalid_timestamp – żądanie nie zawierało prawidłowej sygnatury czasowej.

  • eea_missing_or_invalid – w żądaniu nie ustawiono pola „eea” lub było ono nieprawidłowe.

  • ad_user_data_missing – nie ustawiono pola żądania „ad_user_data”. Pole „ad_user_data” jest wymagane w przypadku wszystkich żądań DMA objętych zakresem.

  • ad_user_data_invalid – nieprawidłowa wartość żądania „ad_user_data”. Pole „ad_user_data” jest wymagane w przypadku wszystkich żądań DMA objętych zakresem.

  • ad_personalization_missing_or_invalid – w żądaniu nie ustawiono pola „ad_personalization” lub było ono nieprawidłowe. Pole „ad_personalization” jest wymagane w przypadku wszystkich żądań z regionów DMA objętych zakresem.

Zdarzenia reklamowe to podstawowe obiekty atrybucji aplikacji. Zawierają one te właściwości:

Ważne uwagi dotyczące zachowania odpowiedzi w zależności od zgody użytkownika:
Jeśli konwersja ma zgodę użytkownika na dane użytkownika w reklamach, a użytkownik wyraził zgodę na korzystanie z danych w różnych usługach w ustawieniach użytkownika Google, Google Ads odpowie jednym ostatnim kliknięciem we wszystkich swoich usługach CPS. Jeśli użytkownik nie wyraził zgody na korzystanie z danych z różnych usług w ustawieniach użytkownika Google, Google Ads będzie odpowiadać wieloma ostatnimi kliknięciami w przypadku każdego CPS.

Jeśli konwersja obejmuje niektóre usługi Google, w przypadku których użytkownik wyraził zgodę na korzystanie z nich w różnych usługach, ale nie obejmuje innych, Google Ads odpowie jednym ostatnim kliknięciem w przypadku usług, w których użytkownik wyraził zgodę na korzystanie z nich w różnych usługach, ale wieloma ostatnimi kliknięciami w przypadku usług, w których użytkownik nie wyraził zgody na korzystanie z nich w różnych usługach.

Odpowiedź dotycząca śledzenia konwersji
ad_event_id

Zawsze obecny

ciąg znaków

ad_event_id służy jako unikalny identyfikator zdarzeń związanych z reklamami. Jest on ponownie używany w żądaniu atrybucji międzysieciowej i powinien być rejestrowany lub przechowywany na potrzeby debugowania.

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

Zawsze obecny

ciąg znaków

Dane o konwersjach używane na potrzeby atrybucji. Początkowo będziemy obsługiwać 1 rodzaj danych o konwersjach.

conversion
timestamp

Zawsze obecny

liczba

Sygnatura czasowa systemu UNIX, w której wystąpiło zdarzenie związane z reklamą, w sekundach z dokładnością do mikrosekund. Tej wartości należy używać w przypadku atrybucji ostatniego kliknięcia.

1432681913.123456
campaign_type

Zawsze obecny

ciąg znaków

To pole określa typ kampanii, w której wystąpiło zdarzenie związane z reklamą. Możliwe wartości są podane poniżej.

ACI
ACE
ACPre
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI to skrót od kampanii promującej instalacje aplikacji. ACE to skrót od kampanii budujących zaangażowanie w aplikację.
campaign_id

Zawsze obecny

liczba

Identyfikator numeryczny kampanii, która wygenerowała zdarzenie reklamy. Ta wartość jest gwarantowana jako unikalna.

123456789
campaign_name

Zawsze obecny

ciąg znaków

Nazwa kampanii zdefiniowana przez reklamodawcę, która wygenerowała zdarzenie reklamy. Ta wartość nie jest gwarantowana jako niepowtarzalna.

Occasional Gamers (Video)
ad_type

Zawsze obecny

ciąg znaków

Typ reklamy, która spowodowała zdarzenie reklamowe. Ta wartość może służyć do rozróżniania różnych typów zasobów reklamowych w ten sposób:

Promowanie aplikacji 
ClickToDownload
Zaangażowanie w aplikację 
AppDeepLink
 Zaangażowanie w aplikację – proces instalacji i kontynuacji 
AppDeepLinkContinue
 Wszystkie inne wartości 
Unknown
external_customer_id

Zawsze obecny

liczba

Identyfikator reklamodawcy, który jest właścicielem kampanii, która wygenerowała zdarzenie reklamy. Ta wartość może służyć do rozróżniania kont Google Ads.

123456789
location

Zawsze obecny

liczba

Kod identyfikacyjny lokalizacji geograficznej zdarzenia związanego z reklamą. Aby zinterpretować kody lokalizacji, zapoznaj się z  dokumentacją interfejsu Google Ads API.
network_type

Zawsze obecny

ciąg znaków

To pole określa sieć reklamową Google Ads, w której wystąpiło zdarzenie związane z reklamą. Możliwe wartości:

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

Będzie to null, gdy campaign_type ma wartość ACI lub ACE, a network_type ma wartość Display.

ciąg znaków

To pole określa „podtyp” sieci reklamowej Google Ads, w której wystąpiło zdarzenie związane z reklamą. Możliwe wartości zależą od głównego typu sieci.

Zwykła wyszukiwarka Google 
GoogleSearch
 Partnerzy w sieci wyszukiwania Google 
SearchPartners

Wyświetlacz

Wydawcy w internecie mobilnym 
mGDN
 Wydawcy aplikacji 
Google AdMob

YouTube

Sieć filmowa YouTube 
YouTubeVideos
 Sieć wyszukiwania w YouTube 
YouTubeSearch
 Sieć partnerów wideo 
VideoPartners

GoogleTv

Sieć filmowa Google TV 
GoogleTvVideos

międzysieciowe,

Kampania Performance Max w wielu sieciach 
cross-network
video_id

Podawane tylko wtedy, gdy network_type ma wartość YouTube, a campaign_type nie ma wartości ACI ani ACE.

ciąg znaków

Identyfikator filmu w YouTube powiązany ze zdarzeniem reklamy.

dQw4w9WgXcQ
keyword

Podawane tylko wtedy, gdy network_type ma wartość Search, a campaign_type nie ma wartości ACI ani ACE.

ciąg znaków

Słowo kluczowe powiązane ze zdarzeniem reklamy.

+food +delivery
match_type

Podawane tylko wtedy, gdy network_type ma wartość Search, a campaign_type nie ma wartości ACI ani ACE.

ciąg znaków

Typ dopasowania słów kluczowych w sieci wyszukiwania.

Ścisłe 
e
 Do wyrażenia 
p
 Przybliżone 
b
placement

Podawane tylko wtedy, gdy network_type ma wartość Display, a campaign_type nie ma wartości ACI ani ACE.

ciąg znaków

Miejsce docelowe powiązane ze zdarzeniem reklamy.

mobileapp::1-343200656
ad_group_id

Podawany tylko wtedy, gdy campaign_type nie ma wartości Performance_Max.

liczba

Identyfikator numeryczny grupy reklam, która wygenerowała zdarzenie związane z reklamą. Ta wartość jest niepowtarzalna.

123456789
ad_group_name

Podawany tylko wtedy, gdy atrybut campaign_type ma wartość ACI, ACE lub ACPRE.

ciąg znaków

Nazwa grupy reklam zdefiniowana przez reklamodawcę, która wygenerowała zdarzenie reklamy. Ta wartość nie jest gwarantowana jako niepowtarzalna.

My App AdGroup
creative_id

Podawany tylko wtedy, gdy wartość atrybutu campaign_type to nie ACI, ACE, ACPRE lub Performance_Max.

liczba

Numeryczny identyfikator jednostki reklamowej kreacji, która wygenerowała zdarzenie reklamy. Ta wartość jest niepowtarzalna.

123456789
interaction_type

To pole zawsze będzie miało wartość „zaangażowanie”.

ciąg znaków
is_deterministic

Wskazuje, czy metoda atrybucji jest deterministyczna.

Wartość logiczna

true, false
device_model

Model urządzenia, które wygenerowało zdarzenie związane z reklamą.

Ciąg znaków

sm-s936w, sm-3936w
os_version

Główna wersja systemu operacyjnego, w którym wystąpiło zdarzenie związane z reklamą.

Ciąg znaków

14, 12
country

Dwuliterowy kod kraju, w którym wystąpiło zdarzenie związane z reklamą.

Ciąg znaków

CA, US
city

Miasto, w którym wystąpiło zdarzenie związane z reklamą.

Ciąg znaków

san jose, london
region

Stan lub prowincja, w której wystąpiło zdarzenie związane z reklamą.

Ciąg znaków

california, british columbia

Przykładowe odpowiedzi

Przykład odpowiedzi dotyczącej konwersji deterministycznej:

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

Przykład odpowiedzi dotyczącej niedeterministycznej konwersji w 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
}

Przykład odpowiedzi na nieokreśloną konwersję na Androidzie:

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

Przykład odpowiedzi dotyczącej konwersji na iOS lub Androidzie przypisanej przez parametr gbraid:

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

Przykład odpowiedzi śledzenia konwersji, gdy żądanie zawierało błędy:

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

Przykład negatywnej odpowiedzi śledzenia konwersji:

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

Odpowiedź śledzenia konwersji będzie zwracana w przypadku wszystkich żądań śledzenia konwersji.

Przykład odpowiedzi potwierdzającej śledzenie konwersji w przypadku użytkownika spoza Europejskiego Obszaru Gospodarczego w uniwersalnej kampanii promującej aplikacje:

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

Przykład odpowiedzi potwierdzającej śledzenie konwersji w przypadku użytkownika spoza Europejskiego Obszaru Gospodarczego w kampanii w sieci wyszukiwania:

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

Przykład odpowiedzi potwierdzającej śledzenie konwersji w przypadku użytkownika spoza Europejskiego Obszaru Gospodarczego w kampanii displayowej:

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

Przykład odpowiedzi potwierdzającej śledzenie konwersji w przypadku użytkownika spoza Europejskiego Obszaru Gospodarczego w kampanii w YouTube:

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


Żądanie atrybucji międzysieciowej

Gdy Google Ads odpowie na żądanie śledzenia konwersji, odbiorca interfejsu API musi powiadomić Google Ads o swojej decyzji dotyczącej atrybucji w wielu sieciach po zidentyfikowaniu ostatniego kliknięcia.

Żądanie atrybucji w wielu sieciach jest identyczne z pierwotnym żądaniem śledzenia konwersji, ale ma ścieżkę żądania:

/pagead/conversion/app/1.1/cross_network

i dodanie 2 wymaganych parametrów:

Żądanie atrybucji międzysieciowej
ad_event_id

Wymagany

Lokalizacja: zapytanie

Identyfikator ad_event_id ze zdarzenia reklamy powiązanego z atrybucją w poprzednim żądaniu.

Wielkość liter w parametrze
attributed

Wymagany

Lokalizacja: zapytanie

czy Google Ads otrzymało udział w konwersji od konsumenta interfejsu API. Może to być 0 lub 1.

Przykład prawidłowego żądania atrybucji międzysieciowej:

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

Prawidłowe żądanie atrybucji w różnych sieciach zawsze będzie otrzymywać ogólną odpowiedź 200 bez treści.