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

應用程式使用者代理程式

為防止垃圾內容而更加努力,我們為應用程式使用者代表數據分析/廣告產品傳送的 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

執行分析/廣告產品的實體裝置名稱。(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/&tt」),後面接著作業系統的版本號碼。(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。因此,應用程式 User-Agent 可能是:

  • 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 的預期版本。目前唯一有效的版本為 1.0

標準應用程式轉換要求將包含下列參數。

轉換追蹤要求
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}
rdid

必要


位置:查詢


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

f10e1de2-e237-4f50-b6aa-843c45cc63d6

如果缺少裝置 ID (例如來自 ATT 的未同意使用者裝置 ID),請將該 ID 設為零。

00000000-0000-0000-0000-000000000000
id_type

必要


位置:查詢


儲存在 rdid 欄位中的 ID 類型。日後我們可能會接受更多值,但我們會先支援下列值。


Android

advertisingid

iOS

idfa
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
value

選用


位置:查詢


活動金額 (如果有的話)。這個值應一律轉換為機器可讀的浮點值,並使用小數來分隔值的整數和分數部分。

1.99
currency_code

在特定情況下為必填


位置:查詢


value 參數的 ISO 4217 貨幣代碼如果提供 value 參數而不是空白,則此為必要欄位。

USD
gclid

在特定情況下為必填


位置:查詢


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

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

在特定情況下為必填


位置:查詢


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

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

在特定情況下為必填


位置:查詢


在 rdid (advertisingid) 可用 not 或所有 zeroesgclidmarket_referrer_gclid 的情況下,gclid 歸因的 ID。

1
gbraid

在特定情況下為必填


位置:查詢


上次發現透過深層連結開啟應用程式的 gbraid 值。請注意,您必須在應用程式中快取這項資訊,以便日後在應用程式發生轉換時傳送。

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
app_open_source

在特定情況下為必填


位置:查詢


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

ad_click or organic
User-Agent

必要


位置:Header


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

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

必要


位置:Header


評估事件的裝置公開 IPv4 或 IPv6 位址。

216.58.194.174

所有要求都必須透過 HTTPS 傳送。透過 HTTP 收到的連線偵測 (ping) 會遭到拒絕。

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

要求範例

使用非自訂事件類型收益資訊的有效轉換追蹤要求範例如下:

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &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
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"]}}

以下非有效轉換追蹤要求範例,其中包含非自訂事件類型收益資訊 (不適用 ID (adid)) 無效:

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &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
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.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &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
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.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &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
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
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 主體參數,請使用下列原始資料類型慣例:

  • 浮點值

    • 使用點字元做為小數分隔符,與應用程式本地化無關
    • 由兩個數字組成小數,代表貨幣值,例如 2.99
    • 請勿使用指數標記法,例如 2E+9。
    • 請勿使用半形逗號分隔各組數字,例如 1,000,000
    • 有效範例:
      • -0.5
      • 2.99
      • 1000000.123
  • 整數

    • 只傳送不含整數的整數值
    • 請勿使用半形逗號分隔各組數字,例如 1,000,000
    • 有效範例:
      • 1000
      • -11
      • 0
  • 日期

    • 日期格式:yyyy-mm-dd
      • yyyy = 4 位數字的年份,例如 2016
      • mm = 2 位數字,例如 09
      • dd = 2 位數字,例如當月 23 日為 23
    • 一律傳送以上指定的位數,例如在當月 5 日傳送 dd 的值時,請傳送 05
    • 有效範例:
      • "2016-09-23"
      • "1990-12-31"
  • 時間戳記

    • 時間格式:以 UTC 時區定義的 Unix/Epoch 時間戳記 (精確度高達微秒)
    • 有效範例:
      • 週三,1478713087 2016 年 11 月 9 日晚上 17:38:07
      • 週三,1073513982.123000 2004 年 1 月 7 日 22:19:42.123 GMT
  • 陣列

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

轉換追蹤回應

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

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

ad_eventserrors 陣列都可以留空。

預期的錯誤是機器可讀的錯誤代碼,例如 invalid_timestamp

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

轉換追蹤回應
ad_event_id

一律顯示


字串


ad_event_id 可做為廣告事件的專屬 ID。我們會在跨聯播網歸因要求中重複使用,且應記錄/保留以便偵錯。

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

一律顯示


字串


用於歸因的轉換指標。我們最初將支援一個轉換指標。

conversion
timestamp

一律顯示


數字


廣告事件的 UNIX 時間戳記 (以秒為單位),精確度高達毫秒。這個值應用於最終點擊歸因。

1432681913.123456
campaign_type

一律顯示


字串


這個欄位可用來識別產生廣告事件的廣告活動類型。可能的值如下。

ACI
ACE
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
network_subtype

如果 campaign_typeACIACEnetwork_typeDisplay,則為 null


字串


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


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

螢幕

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

YouTube

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

只有在 network_typeYouTubecampaign_type 「不是」ACIACE 時提供。


字串


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

dQw4w9WgXcQ
keyword

只有在 network_typeSearchcampaign_type 「不是」ACIACE 時提供。


字串


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

+food +delivery
match_type

只有在 network_typeSearchcampaign_type 「不是」ACIACE 時提供。


字串


搜尋關鍵字的比對類型。

完全
e
詞組
p
廣泛
b
placement

只有在 network_typeDisplaycampaign_type 「不是」ACIACE 時提供。


字串


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

mobileapp::1-343200656
ad_group_id

一律顯示


數字


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

123456789
ad_group_name

只有在 campaign_typeACIACEACPRE 時提供。


字串


廣告客戶產生廣告事件的廣告群組定義廣告群組名稱。這個值不可保證重複。

My App AdGroup
creative_id

只有在 campaign_type 不是 ACIACE 時才提供。


數字


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

123456789
interaction_type

這個欄位一律會是參與度。


字串

回應範例

要求包含錯誤的轉換追蹤回應範例:

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

搜尋廣告活動的確認轉換追蹤回應範例:

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

多媒體廣告活動的確認轉換追蹤回應範例如下:

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

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
}

跨聯播網歸因要求

Google Ads 明確回應轉換追蹤要求時,API 消費者必須在識別最終點擊後,通知 Google Ads 的跨聯播網歸因決策。

跨聯播網歸因要求與原始轉換追蹤要求相同,但請求路徑如下:

/pagead/conversion/app/1.0/cross_network

並加入兩個必要參數:

跨聯播網歸因要求
ad_event_id

必要


位置:查詢


與先前請求中歸因歸因的廣告事件相關的 ad_event_id ID。

attributed

必要


位置:查詢


Google Ads 獲得的轉換功勞是否由 API 消費者提供。01 其中之一。

以下舉例說明何謂有效的跨聯播網歸因要求:

POST /pagead/conversion/app/1.0/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 回應。