應用程式轉換追蹤和再行銷 - 請求/回應規格

應用程式使用者代理程式

為防範垃圾內容，我們已制定標準規格，供 Analytics/廣告產品代表應用程式使用者傳送 User-Agent 標頭。應用程式 User-Agent 可從原生程式碼衍生，以符合下列規格：

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

這些欄位的定義如下：

User-Agent 元件
name

數據分析/廣告產品的名稱。(Google AdMob)

請注意，如果使用者代理程式是在用戶端建構，name 應為用戶端應用程式的套件組合 ID。

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

數據分析/廣告產品的版本。 (7.10.1)

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

應用程式執行的作業系統和作業系統版本。(Android 6.0 )

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

裝置的 IETF 語言代碼，使用兩個字母的語言和國家/地區代碼，並以底線分隔。(en_US)

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

執行 Analytics/Ads 產品的實體裝置名稱。(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/」，後接作業系統的版本號碼。 (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];
}

建構應用程式 User-Agent 伺服器端時，請只在應用程式 User-Agent 結尾加入 ; Proxy。如果應用程式 User-Agent 完全是在用戶端建構，請排除 ; Proxy。因此，應用程式的使用者代理程式可能如下所示：

  • 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)

轉換追蹤要求指南

轉換追蹤要求的目的是通知 Google Ads 應用程式事件應追蹤為轉換和/或用於填入再行銷名單，以及擷取描述事件前任何點擊的相關中繼資料。

所有 API 呼叫都會傳送至 www.googleadservices.com 網域。轉換要求是透過 HTTPS 在下列路徑發出的 POST 要求：

/pagead/conversion/app/version
其中 version 是轉換追蹤 API 的預期版本。

標準應用程式轉換要求會包含下列應用程式轉換 API 1.1 版的參數。

轉換追蹤要求
dev_token

必要

位置：查詢

發給 API 消費者的專屬靜態開發人員權杖。

Z_eErE4DkvcKjDM1OVE4c4
link_id

必要

位置：查詢

連結 ID，可將 API 消費者的開發人員權杖繫結至特定應用程式。

31FF8D67E5BB5DD5029DCC2734C2F884
app_event_type

必要

位置：查詢

發生的應用程式事件名稱。這個欄位是列舉，只接受下列值：

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

您應一律傳送 first_open 事件來歸因安裝次數，並一律傳送 session_start 事件來重新歸因工作階段。透過原生應用程式商店進行的交易請使用 in_app_purchase，所有其他交易則使用 ecommerce_purchase。
app_event_name

在特定情況下為必填屬性

位置：查詢

「app_event_type」欄位中不接受任何自訂應用程式事件名稱。這個欄位應包含 1 到 64 個 Unicode 字元 (使用 UTF-8 編碼)。如果 app_event_type 為自訂，則必須填寫這個欄位。

level_achieved
Level Achieved

這個欄位不得包含為 app_event_type 保留的任何值。如果使用預留事件名稱，API 會傳回 APP_EVENT_NAME_RESERVED_VALUE 錯誤。
app_event_data

選用

位置：身體

將任何其他豐富事件資料轉送為簡單的 JSON 物件，將字串鍵對應至值。可接受的值為字串和字串陣列。

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

在 iOS 上使用整合轉換評估時的必要條件

位置：查詢

從 Google 裝置端評估 (ODM)：事件資料 SDK 擷取，在 iOS 應用程式安裝或重新安裝時取得的 info 查詢參數值。這個欄位可啟用 iOS 應用程式廣告活動的整合轉換評估。

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

必要

在 rdid 欄位中傳遞的 ID 類型。

Android

advertisingid
 
appsetid

iOS

idfa
 
idfv
rdid

必要

位置：查詢

代表原始裝置 ID 的有效 UUID 字串。

f10e1de2-e237-4f50-b6aa-843c45cc63d6

如果缺少裝置 ID (例如未同意 ATT 的使用者裝置 ID)，請將其設為全零。

00000000-0000-0000-0000-000000000000
ctry_c

必要

位置：查詢

雙字母 ISO 國家/地區代碼，指出轉換的來源國家/地區。

如要在 iOS 和 Android 裝置上啟用非使用者層級的應用程式轉換評估，就必須填寫這個欄位。

US, IN
eea

在特定條件下為必要屬性

位置：查詢

歐洲經濟區範圍。

0：歐洲法規不適用於這位使用者和轉換。

1：歐洲法規適用於這位使用者和轉換。 舉例來說，如果使用者位於歐洲經濟區，就屬於適用歐洲法規的範圍。

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

在特定條件下為必要屬性

位置：查詢

個人化廣告的旗標

0：使用者拒絕提供廣告個人化同意聲明

1：使用者同意提供廣告個人化同意聲明 

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

在特定條件下為必要屬性

位置：查詢

使用者同意聲明旗標，表示是否允許基於廣告用途使用使用者資料

0：使用者拒絕同意將使用者層級資料傳送給 Google，用於廣告用途

1：使用者同意將使用者層級資料傳送給 Google，用於廣告用途 

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

必要

位置：查詢

裝置的「限制廣告追蹤」狀態。

  • 0：使用者尚未選擇限制廣告追蹤。
  • 1：使用者已選擇限制廣告追蹤。
app_version

必要

位置：查詢

應用程式的目前版本。這應標準化如下。

Android

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

iOS

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

必要

位置：查詢

應用程式主機作業系統的目前版本。請按照下列方式標準化。

Android

android.os.Build.VERSION.RELEASE

iOS

[[UIDevice currentDevice] systemVersion]
sdk_version

必要

位置：查詢

評估事件的 SDK 版本。由於這主要是用於偵錯，因此應反映 SDK 發布時的確切發布版本。如果應用程式未使用 SDK，請傳遞與 app_version 相同的值。

1.9.5r6
timestamp

必要

位置：查詢

轉換事件發生的 UNIX 時間戳記，以秒為單位，精確度達微秒。

1432681913.123456
fot

必要

位置：查詢

後續所有工作階段和安裝後事件的 UNIX 時間戳記，以秒為單位，且精確度為微秒。first_open

1432681913.123456
value

選用

位置：查詢

事件的金額價值 (如有)。格式一律應為機器可讀取的浮點值，並使用小數點分隔整數和小數部分。

1.99
currency_code

在特定情況下為必填屬性

位置：查詢

value 參數的 ISO 4217 貨幣代碼。如果提供 value 參數且不為空白，則此欄位為必填。

USD
gclid

在特定情況下為必填屬性

位置：查詢

深層連結網址的 gclid 查詢參數值，該網址已開啟應用程式。

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

在特定情況下為必填屬性

位置：查詢

深層連結網址的 gclid 查詢參數值，透過 Play Install Referrer API 從 install_referrer 值擷取。

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

在特定情況下為必填屬性

位置：查詢

在 rdid (advertisingid) not 可用或所有 zeroes AND 存在 gclid 或 market_referrer_gclid 的情況下，用於 gclid 型歸因的 ID。

1
gbraid

在特定情況下為必填屬性

位置：查詢

透過開啟應用程式的深層連結網址傳送的「上次瀏覽」gbraid值。請注意，這項值必須快取在應用程式中，才能與應用程式中發生的未來轉換一併傳送。

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
app_open_source

在特定情況下為必填屬性

位置：查詢

用來識別廣告點擊深層連結或自然應用程式工作階段的值。

ad_click or organic
User-Agent

必要

位置：標題

如上一節所述的應用程式使用者代理程式。

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

必要

位置：標題

事件發生裝置的公開 IPv4 或 IPv6 位址。

216.58.194.174

所有要求都必須透過 HTTPS 傳送。系統會拒絕透過 HTTP 接收的 Ping。

請注意，如果要求主體為空白 (即 app_event_data 酬載中未傳遞任何豐富的事件資料)，伺服器會要求您在要求中明確設定 Content-Length: 0 標頭。

事件資料編碼

如為 app_event_data 主體參數，請對原始資料類型使用下列慣例：

  • Float

    • 不論應用程式本地化設定為何，一律使用半形句號做為小數分隔符
    • 使用兩位數的小數精度來表示貨幣值，例如 2.99。
    • 請勿使用指數標記法，例如 2E+9
    • 請勿使用逗號分隔數字群組，例如： 1,000,000
    • 有效範例：
      • -0.5
      • 2.99
      • 1000000.123

  • 整數

    • 請只傳送整數值，不得含有小數
    • 請勿使用逗號分隔數字群組，例如 1,000,000
    • 有效範例：
      • 1000
      • -11
      • 0

  • 日期

    • 日期格式：yyyy-mm-dd
      • yyyy = 以四位數字表示的年份，例如 2016
      • mm = 兩位數的月份，例如 09 代表 9 月
      • dd = 兩位數的日期，例如當月 23 號為 23
    • 請務必傳送上述指定的位數，例如，如果傳送該月 5 號的 dd 值，請傳送 05。
    • 有效範例：
      • "2016-09-23"
      • "1990-12-31"

  • 時間戳記

    • 時間格式：以世界標準時間時區定義的Unix/Epoch 時間戳記 (以秒為單位)，精確度達微秒
    • 有效範例：
      • 1478713087 for Wed, 09 Nov 2016 17:38:07 GMT
      • 1073513982.123000 for Wed, 07 Jan 2004 22:19:42.123 GMT

  • 陣列

    • 只傳送原始值 (字串、數字和布林值) 的陣列
    • 有效範例：
      • [123, 456, 789]
      • ["abc"]

範例要求

以下是搭配使用「裝置端評估：事件資料 SDK，適用於整合式轉換評估」的首次開啟請求範例：

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

以下是不含裝置端評估的初次開啟要求範例：整合式轉換評估的事件資料 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

以下是使用「裝置端評估：整合式轉換評估的事件資料 SDK」發出的安裝後要求範例：

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

以下是不含裝置端評估：事件資料 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

以下是 ACAPI 1.1 版的 Android 非確定性轉換初次開啟要求範例：

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

以下是有效的轉換追蹤要求範例，其中包含非自訂事件類型和收益資訊：

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

以下是有效的轉換追蹤請求範例，其中包含非自訂事件類型和收益資訊，但沒有 rdid (advertisingid)：

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

有效的工作階段開始要求範例如下：

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

以下是透過深層連結 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

以下是歐洲經濟區使用者同意提供廣告使用者資料，但拒絕廣告個人化時，有效的轉換追蹤要求範例：

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

轉換追蹤回應指南

轉換追蹤回應的格式如下：

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

ad_events 和 errors 陣列可能都是空白。

我們預期錯誤會是機器可讀取的錯誤代碼，例如 invalid_timestamp。

錯誤代碼

  • invalid_timestamp - 要求沒有有效時間戳記。

  • eea_missing_or_invalid - 要求未設定「eea」欄位，或該欄位無效。

  • ad_user_data_missing - 未設定「ad_user_data」要求欄位。所有適用 DMA 要求的請求都必須包含「ad_user_data」欄位。

  • ad_user_data_invalid - 「ad_user_data」要求值無效。所有適用 DMA 要求的請求都必須包含「ad_user_data」欄位。

  • ad_personalization_missing_or_invalid - 要求未設定「ad_personalization」欄位，或該欄位無效。所有適用 DMA 的請求都必須填寫「ad_personalization」欄位。

廣告事件是應用程式歸因的核心物件，包含下列屬性。

重要注意事項：回應行為取決於使用者同意聲明：
如果轉換有廣告使用者資料同意聲明，且使用者已在 Google 使用者設定中同意跨用途使用，Google Ads 會在所有 CPS 中，回應單一的最後點擊。如果使用者未在 Google 使用者設定中同意跨用途同意聲明，Google Ads 會根據每次轉換費用，傳回多個最後點擊。

如果轉換包含使用者選取同意跨用途使用的特定 CPS，但未包含其他 CPS，Google Ads 會針對同意跨用途使用的 CPS 回應單一最後點擊，但針對未同意跨用途使用的 CPS，則會針對每個 CPS 回應多個最後點擊。

轉換追蹤回應
ad_event_id

一律顯示

字串

ad_event_id 是廣告事件的專屬 ID，這個值會在跨聯播網歸因要求中重複使用，因此應記錄/保留這個值，以利進行偵錯。

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

一律顯示

字串

用於歸因的轉換指標。我們一開始會支援一項轉換指標。

conversion
timestamp

一律顯示

數字

廣告事件發生的 UNIX 時間戳記，以秒為單位，精確度為微秒。這個值應做為最終點擊歸因。

1432681913.123456
campaign_type

一律顯示

字串

這個欄位會指出產生廣告事件的廣告活動類型。可能的值如下。

ACI
ACE
ACPre
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI 是「應用程式安裝廣告活動」的縮寫。ACE 是「參與式應用程式廣告活動」的縮寫。
campaign_id

一律顯示

數字

產生廣告事件的廣告活動數字 ID。這個值保證是唯一的。

123456789
campaign_name

一律顯示

字串

產生廣告事件的廣告活動名稱 (由廣告主定義)。這個值不保證不會重複。

Occasional Gamers (Video)
ad_type

一律顯示

字串

促成廣告事件的廣告類型。這個值可用於區分各種廣告空間類型，如下所示。

應用程式宣傳
ClickToDownload
 應用程式參與度 
AppDeepLink
 應用程式參與度 - 安裝並繼續流程 
AppDeepLinkContinue
 其他值的一般用途 
Unknown
external_customer_id

一律顯示

數字

廣告主 ID，代表擁有廣告事件所屬廣告活動的廣告主。這個值可用於區分 Google Ads 帳戶。

123456789
location

一律顯示

數字

廣告事件發生地點的地理位置 ID 代碼。如要解讀位置代碼，請參閱 Google Ads API 參考資料。
network_type

一律顯示

字串

這個欄位會指出廣告事件發生的 Google Ads 廣告聯播網。可能的值如下。

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

當 campaign_type 為 ACI 或 ACE，且 network_type 為 Display 時，會是 null。

字串

這個欄位會指出廣告事件發生的 Google Ads 廣告聯播網「子類型」。可能的值會因主要電視網類型而異。

一般 Google 搜尋 
GoogleSearch
 Google 搜尋夥伴 
SearchPartners

多媒體

行動網站發布商 
mGDN
 應用程式發布商 
Google AdMob

YouTube

YouTube 影片聯播網 
YouTubeVideos
 YouTube 搜尋聯播網 
YouTubeSearch
 影片合作夥伴 
VideoPartners

GoogleTv

Google TV 影片聯播網
GoogleTvVideos

跨聯播網

最高成效廣告活動跨聯播網
cross-network
video_id

只有在 network_type 為 YouTube 且 campaign_type「不是」ACI 和 ACE 時，才會提供這項資訊。

字串

與廣告事件相關聯的 YouTube 影片 ID。

dQw4w9WgXcQ
keyword

只有在 network_type 為 Search 且 campaign_type「不是」ACI 和 ACE 時，才會提供這項資訊。

字串

與廣告事件相關聯的搜尋關鍵字。

+food +delivery
match_type

只有在 network_type 為 Search 且 campaign_type「不是」ACI 和 ACE 時，才會提供這項資訊。

字串

搜尋關鍵字的比對類型。

完全比對 
e
 詞組 
p
 廣泛比對 
b
placement

只有在 network_type 為 Display 且 campaign_type「不是」ACI 和 ACE 時，才會提供這項資訊。

字串

與廣告事件相關聯的刊登位置。

mobileapp::1-343200656
ad_group_id

只有在 campaign_type 不是 Performance_Max 時，才會提供這項資訊。

數字

產生廣告事件的廣告群組數字 ID。這個值保證不會重複。

123456789
ad_group_name

只有在 campaign_type 為 ACI、ACE 或 ACPRE 時才會提供。

字串

產生廣告事件的廣告群組名稱 (由廣告主定義)。這個值不保證不會重複。

My App AdGroup
creative_id

只有在 campaign_type「不是」ACI、ACE、ACPRE 或 Performance_Max 時，才會提供這項資訊。

數字

產生廣告事件的廣告素材廣告單元數字 ID。這個值保證不會重複。

123456789
interaction_type

這個欄位一律為「參與度」。

字串
is_deterministic

指出歸因方法是否為確定性。

布林值

true, false
device_model

產生廣告事件的裝置型號。

字串

sm-s936w, sm-3936w
os_version

產生廣告事件的主要 OS 版本。

字串

14, 12
country

產生廣告事件的國家/地區代碼 (由兩個字母組成)。

字串

CA, US
city

產生廣告事件的城市。

字串

san jose, london
region

產生廣告事件的州或省。

字串

california, british columbia

回覆範例

確定性轉換的回應範例如下：

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

以下是 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
}

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

以下是 iOS/Android 轉換的回應範例，其中轉換是透過 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" [],
}

如果要求含有錯誤，轉換追蹤回應範例如下：

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

負面轉換追蹤回應範例如下：

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

系統會針對所有轉換追蹤要求傳回轉換追蹤回應。

以下是針對非歐洲經濟區使用者，對通用應用程式廣告活動發出的肯定轉換追蹤回應範例：

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

以下是搜尋廣告活動針對非歐洲經濟區使用者傳回的肯定轉換追蹤回應範例：

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

以下是多媒體廣告活動的肯定轉換追蹤回應範例 (適用於非歐洲經濟區使用者)：

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

以下是 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
}


跨聯播網歸因要求

如果 Google Ads 對轉換追蹤要求的回應為肯定，API 消費者就必須在找出最終點擊後，將跨聯播網歸因決策通知 Google Ads。

跨聯播網歸因要求與原始轉換追蹤要求相同，但要求路徑為：

/pagead/conversion/app/1.1/cross_network

並新增兩個必要參數：

跨聯播網歸因要求
ad_event_id

必要

位置：查詢

與先前要求中的歸因相關聯的廣告事件 ad_event_id 識別碼。
attributed

必要

位置：查詢

Google Ads 是否已透過 API 消費者獲得轉換功勞。0 或 1。

有效的跨聯播網歸因要求範例如下：

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

有效的跨聯播網歸因要求一律會收到一般 200 回應，且沒有回應主體。