Theo dõi lượt chuyển đổi đối với ứng dụng và tái tiếp thị – Quy cách của yêu cầu/nội dung phản hồi

Tác nhân người dùng ứng dụng

Trong nỗ lực chung nhằm chống lại thư rác, chúng tôi đã phát triển một quy cách tiêu chuẩn cho tiêu đề User-Agent do một sản phẩm phân tích/quảng cáo gửi thay cho người dùng ứng dụng. Bạn có thể lấy User-Agent của ứng dụng từ mã gốc để tuân thủ quy cách sau:

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

Sau đây là định nghĩa của các trường này:

Thành phần User-Agent
name

Tên của sản phẩm phân tích/quảng cáo. (Google AdMob)

Xin lưu ý rằng nếu tác nhân người dùng được tạo ở phía máy khách, thì name phải là mã nhận dạng gói của ứng dụng máy khách.

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

Phiên bản của sản phẩm phân tích/quảng cáo. (7.10.1)

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

Hệ điều hành và phiên bản hệ điều hành mà ứng dụng đang chạy. (Android 6.0 )

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

Thẻ ngôn ngữ IETF cho thiết bị, sử dụng mã ngôn ngữ và mã quốc gia gồm hai chữ cái, được phân tách bằng dấu gạch dưới. (en_US)

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

Tên của thiết bị thực đang chạy sản phẩm phân tích/quảng cáo. (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/" theo sau là số bản dựng của hệ điều hành. (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];
}

Chỉ thêm ; Proxy vào cuối User-Agent của ứng dụng khi tạo User-Agent của ứng dụng ở phía máy chủ. Nếu User-Agent của ứng dụng được tạo hoàn toàn ở phía máy khách, hãy loại trừ ; Proxy. Do đó, User-Agent của ứng dụng có thể là:

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

Yêu cầu theo dõi lượt chuyển đổi

Mục đích của các yêu cầu theo dõi lượt chuyển đổi là thông báo cho Google Ads về một sự kiện trong ứng dụng cần được theo dõi dưới dạng lượt chuyển đổi và/hoặc được dùng để điền sẵn thông tin vào danh sách tái tiếp thị, đồng thời truy xuất siêu dữ liệu mô tả mọi lượt nhấp xảy ra trước sự kiện đó.

Tất cả lệnh gọi API đều được thực hiện cho miền www.googleadservices.com. Yêu cầu chuyển đổi là yêu cầu POST thông qua HTTPS trên đường dẫn sau: 

/pagead/conversion/app/version
trong đó version là phiên bản dự kiến của API theo dõi lượt chuyển đổi. Hiện tại, phiên bản hợp lệ duy nhất là 1.0.

Một yêu cầu chuyển đổi ứng dụng thông thường sẽ chứa các tham số sau.

Yêu cầu theo dõi lượt chuyển đổi
dev_token

Bắt buộc

Vị trí: Truy vấn

Mã thông báo duy nhất, tĩnh của nhà phát triển được cấp cho người dùng API.

Z_eErE4DkvcKjDM1OVE4c4
link_id

Bắt buộc

Vị trí: Truy vấn

Giá trị nhận dạng đường liên kết liên kết mã thông báo của nhà phát triển của người dùng API với một ứng dụng cụ thể.

31FF8D67E5BB5DD5029DCC2734C2F884
app_event_type

Bắt buộc

Vị trí: Truy vấn

Tên của sự kiện ứng dụng đã xảy ra. Trường này là một bản liệt kê và sẽ chỉ chấp nhận các giá trị sau:

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

Sự kiện first_open phải luôn được gửi để phân bổ lượt cài đặt và sự kiện session_start phải luôn được gửi để phân bổ lại các phiên. Sử dụng in_app_purchase cho các giao dịch mua được thực hiện thông qua cửa hàng ứng dụng gốc; sử dụng ecommerce_purchase cho tất cả các giao dịch mua khác.
app_event_name

Bắt buộc trong một số điều kiện nhất định

Vị trí: Truy vấn

Tên của mọi sự kiện tuỳ chỉnh trong ứng dụng không được chấp nhận trong trường app_event_type. Trường này phải chứa từ 1 đến 64 ký tự Unicode (sử dụng phương thức mã hoá UTF-8). Đây là trường bắt buộc nếu app_event_type là tuỳ chỉnh.

level_achieved
Level Achieved

Trường này không được chứa bất kỳ giá trị nào dành riêng cho app_event_type. Nếu bạn sử dụng tên sự kiện dành riêng, API sẽ trả về lỗi APP_EVENT_NAME_RESERVED_VALUE.
app_event_data

Không bắt buộc

Vị trí: Cơ thể

Chuyển tiếp mọi dữ liệu sự kiện bổ sung có định dạng phong phú dưới dạng một chuỗi ánh xạ đối tượng JSON đơn giản cho các khoá đến giá trị. Các giá trị được chấp nhận là các chuỗi và mảng chuỗi.

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

Bắt buộc

Vị trí: Truy vấn

Một chuỗi UUID hợp lệ đại diện cho mã nhận dạng thô của thiết bị.

f10e1de2-e237-4f50-b6aa-843c45cc63d6

Trong trường hợp thiếu mã nhận dạng thiết bị, chẳng hạn như mã nhận dạng thiết bị của người dùng chưa đồng ý theo ATT, hãy đặt mã nhận dạng đó thành tất cả các số 0.

00000000-0000-0000-0000-000000000000
id_type

Bắt buộc

Vị trí: Truy vấn

Loại giá trị nhận dạng được lưu trữ trong trường rdid. Chúng tôi có thể chấp nhận nhiều giá trị hơn tại đây trong tương lai, nhưng trước mắt, chúng tôi sẽ hỗ trợ những giá trị sau.

Android

advertisingid

iOS

idfa
eea

Bắt buộc trong một số điều kiện nhất định

Vị trí: Truy vấn

Phạm vi EEA.

0: Quy định của Châu Âu không áp dụng cho người dùng và lượt chuyển đổi này

1: Quy định của Châu Âu áp dụng cho người dùng và lượt chuyển đổi này. Ví dụ: nếu người dùng ở trong EEA, thì họ sẽ thuộc phạm vi áp dụng các quy định hiện hành của Châu Âu. 

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

Bắt buộc trong một số điều kiện nhất định

Vị trí: Truy vấn

Các cờ cho quảng cáo được cá nhân hoá

0: Người dùng cuối đã từ chối đồng ý cá nhân hoá quảng cáo

1: Người dùng cuối đã đồng ý cá nhân hoá quảng cáo 

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

Bắt buộc trong một số điều kiện nhất định

Vị trí: Truy vấn

Cờ đồng ý cho việc sử dụng dữ liệu người dùng cho mục đích quảng cáo

0: Người dùng đã từ chối đồng ý truyền dữ liệu ở cấp người dùng đến Google cho mục đích quảng cáo

1: Người dùng đã đồng ý truyền dữ liệu ở cấp người dùng đến Google cho mục đích quảng cáo 

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

Bắt buộc

Vị trí: Truy vấn

Trạng thái giới hạn theo dõi quảng cáo của thiết bị.

  • 0: Người dùng chưa chọn giới hạn việc theo dõi quảng cáo.
  • 1: Người dùng đã chọn giới hạn việc theo dõi quảng cáo.
app_version

Bắt buộc

Vị trí: Truy vấn

Phiên bản hiện tại của ứng dụng. Bạn nên chuẩn hoá phiên bản này như sau.

Android

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

iOS

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

Bắt buộc

Vị trí: Truy vấn

Phiên bản hiện tại của hệ điều hành máy chủ lưu trữ của ứng dụng. Bạn nên chuẩn hoá giá trị này như sau.

Android

android.os.Build.VERSION.RELEASE

iOS

[[UIDevice currentDevice] systemVersion]
sdk_version

Bắt buộc

Vị trí: Truy vấn

Phiên bản SDK đã đo lường sự kiện. Vì chủ yếu được dùng để gỡ lỗi, nên phiên bản này phải phản ánh chính xác phiên bản phát hành như khi được xuất bản cùng với các bản phát hành SDK của bạn. Nếu ứng dụng không dùng SDK, vui lòng truyền cùng giá trị như app_version.

1.9.5r6
timestamp

Bắt buộc

Vị trí: Truy vấn

Dấu thời gian UNIX khi sự kiện chuyển đổi diễn ra, tính bằng giây với độ chính xác lên đến micrô giây.

1432681913.123456
value

Không bắt buộc

Vị trí: Truy vấn

Giá trị bằng tiền của sự kiện (nếu có). Giá trị này phải luôn được định dạng dưới dạng giá trị dấu phẩy động mà máy có thể đọc được, sử dụng dấu thập phân để phân tách phần nguyên và phần phân số của giá trị.

1.99
currency_code

Bắt buộc trong một số điều kiện nhất định

Vị trí: Truy vấn

Mã đơn vị tiền tệ theo ISO 4217 cho tham số value. Đây là trường bắt buộc nếu bạn cung cấp tham số value và không để trống.

USD
gclid

Bắt buộc trong một số điều kiện nhất định

Vị trí: Truy vấn

Giá trị của tham số truy vấn gclid từ một URL đường liên kết sâu đã mở ứng dụng.

Cj0KEQjw0dy4BRCuuL_e5M
market_referrer_gclid

Bắt buộc trong một số điều kiện nhất định

Vị trí: Truy vấn

Giá trị của tham số truy vấn gclid trong một URL đường liên kết sâu được thu thập từ giá trị install_referrer thông qua API Play Install Referrer.

BX3QojHp4mY5MrJtFM_d1u
gclid_only_request

Bắt buộc trong một số điều kiện nhất định

Vị trí: Truy vấn

Giá trị nhận dạng cho hoạt động phân bổ dựa trên gclid trong các trường hợp mà rdid (advertisingid) not có sẵn hoặc tất cả zeroes VÀ gclid hoặc market_referrer_gclid đều xuất hiện.

1
gbraid

Bắt buộc trong một số điều kiện nhất định

Vị trí: Truy vấn

Giá trị gbraid được gửi lần gần đây nhất thông qua URL đường liên kết sâu đã mở ứng dụng. Xin lưu ý rằng giá trị này cần được lưu vào bộ nhớ đệm trên ứng dụng để có thể được gửi cùng với các lượt chuyển đổi trong tương lai xảy ra trên ứng dụng.

ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
app_open_source

Bắt buộc trong một số điều kiện nhất định

Vị trí: Truy vấn

Giá trị để xác định đường liên kết sâu của lượt nhấp vào quảng cáo hoặc phiên ứng dụng tự nhiên.

ad_click or organic
User-Agent

Bắt buộc

Vị trí: Tiêu đề

Tác nhân người dùng ứng dụng như được xác định trong phần trước.

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

Bắt buộc

Vị trí: Tiêu đề

Địa chỉ IPv4 hoặc IPv6 công khai của thiết bị nơi sự kiện được đo lường.

216.58.194.174

Bạn phải gửi tất cả các yêu cầu thông qua HTTPS. Các lệnh ping nhận được qua HTTP sẽ bị từ chối.

Xin lưu ý rằng nếu nội dung yêu cầu trống (trong trường hợp không có dữ liệu sự kiện phong phú nào được truyền trong tải trọng app_event_data), thì máy chủ của chúng tôi yêu cầu bạn đặt tiêu đề Content-Length: 0 một cách rõ ràng cho yêu cầu của mình.

Yêu cầu mẫu

Sau đây là ví dụ về một yêu cầu theo dõi lượt chuyển đổi hợp lệ có loại sự kiện không tuỳ chỉnh và thông tin doanh thu:

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

Ví dụ về một yêu cầu theo dõi lượt chuyển đổi hợp lệ có loại sự kiện không tuỳ chỉnh và thông tin về doanh thu khi không có rdid (advertisingid) là:

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

Sau đây là ví dụ về một yêu cầu bắt đầu phiên hợp lệ:

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
       &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

Ví dụ về yêu cầu bắt đầu phiên phân bổ lại hợp lệ cho một phiên bắt đầu từ đường liên kết sâu example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M là:

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
       &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

Ví dụ về một yêu cầu theo dõi lượt chuyển đổi hợp lệ cho người dùng ở EEA đã đồng ý cho phép sử dụng dữ liệu người dùng quảng cáo và từ chối cá nhân hoá quảng cáo là:

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
       &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

Mã hoá dữ liệu sự kiện

Đối với tham số nội dung app_event_data, vui lòng sử dụng các quy ước sau cho các loại dữ liệu gốc:

  • Float

    • Sử dụng ký tự dấu chấm làm dấu phân cách số thập phân, bất kể nội dung bản địa hoá của ứng dụng
    • Sử dụng độ chính xác thập phân gồm 2 chữ số để biểu thị giá trị tiền tệ. Ví dụ: 2,99
    • Không sử dụng ký hiệu khoa học, ví dụ: 2E+9
    • Không dùng dấu phẩy để phân tách các nhóm chữ số, ví dụ: 1.000.000
    • Ví dụ hợp lệ:
      • -0.5
      • 2.99
      • 1000000.123

  • Số nguyên

    • Chỉ gửi giá trị số nguyên không có chữ số thập phân
    • Không dùng dấu phẩy để phân tách các nhóm chữ số, ví dụ: 1.000. 000
    • Ví dụ hợp lệ:
      • 1000
      • -11
      • 0

  • Ngày

    • Định dạng ngày: yyyy-mm-dd
      • yyyy = năm ở dạng bốn chữ số, ví dụ: 2016
      • mm = tháng có hai chữ số, ví dụ: 09 cho tháng 9
      • dd = ngày có hai chữ số, ví dụ: 23 cho ngày 23 của tháng
    • Luôn gửi số lượng chữ số được chỉ định ở trên, ví dụ: nếu gửi giá trị cho dd vào ngày 5 của tháng, hãy gửi 05.
    • Ví dụ hợp lệ:
      • "2016-09-23"
      • "1990-12-31"

  • Dấu thời gian

    • Định dạng thời gian: Dấu thời gian Unix/Epoch được xác định theo múi giờ UTC với độ chính xác lên đến micrô giây
    • Ví dụ hợp lệ:
      • 1478713087 cho Wed, 09 Nov 2016 17:38:07 GMT
      • 1073513982.123000 cho Wed, 07 Jan 2004 22:19:42.123 GMT

  • Mảng

    • Chỉ gửi mảng giá trị nguyên thuỷ (chuỗi, số và boolean)
    • Ví dụ hợp lệ:
      • [123, 456, 789]
      • ["abc"]

Phản hồi theo dõi lượt chuyển đổi

Phản hồi theo dõi lượt chuyển đổi có định dạng sau:

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

Cả mảng ad_events và errors đều có thể trống.

Chúng tôi dự kiến các lỗi sẽ là mã lỗi mà máy có thể đọc được, ví dụ: invalid_timestamp.

Mã lỗi

  • invalid_timestamp – Yêu cầu không có dấu thời gian hợp lệ.

  • eea_missing_or_invalid – Yêu cầu không có trường "eea" được đặt hoặc trường này không hợp lệ.

  • ad_user_data_missing – Bạn chưa đặt trường yêu cầu "ad_user_data". Trường "ad_user_data" là trường bắt buộc đối với tất cả các yêu cầu thuộc phạm vi DMA.

  • ad_user_data_invalid – Giá trị yêu cầu "ad_user_data" không hợp lệ. Trường "ad_user_data" là trường bắt buộc đối với tất cả các yêu cầu thuộc phạm vi DMA.

  • ad_personalization_missing_or_invalid – Yêu cầu không đặt trường "ad_personalization" hoặc trường này không hợp lệ. Trường "ad_personalization" là trường bắt buộc đối với tất cả các yêu cầu trong phạm vi DMA.

Sự kiện quảng cáo là các đối tượng cốt lõi của hoạt động phân bổ ứng dụng và sẽ chứa các thuộc tính sau.

Lưu ý quan trọng về hành vi phản hồi tuỳ thuộc vào sự đồng ý của người dùng:
Nếu lượt chuyển đổi có sự đồng ý của người dùng quảng cáo và người dùng có sự đồng ý sử dụng trên nhiều ứng dụng trong chế độ cài đặt người dùng của Google, thì Google Ads sẽ phản hồi bằng một lượt nhấp cuối cùng trên tất cả các CPS. Nếu người dùng chưa đồng ý với sự đồng ý sử dụng trên nhiều nền tảng trong phần cài đặt người dùng của Google, thì Google Ads sẽ phản hồi bằng nhiều lượt nhấp cuối cùng, trên cơ sở mỗi lượt chuyển đổi sau khi nhấp.

Nếu lượt chuyển đổi bao gồm một số CPS trong sự đồng ý sử dụng trên nhiều dịch vụ do người dùng chọn nhưng không bao gồm những CPS khác, thì Google Ads sẽ phản hồi bằng một lượt nhấp cuối cùng trên các CPS được cấp sự đồng ý sử dụng trên nhiều dịch vụ, nhưng có nhiều lượt nhấp cuối cùng (trên cơ sở mỗi CPS) cho những CPS không được cấp sự đồng ý sử dụng trên nhiều dịch vụ.

Phản hồi theo dõi lượt chuyển đổi
ad_event_id

Luôn có mặt

chuỗi

ad_event_id đóng vai trò là giá trị nhận dạng riêng biệt cho các sự kiện quảng cáo. Giá trị này được dùng lại trong yêu cầu phân bổ trên nhiều mạng và cần được ghi nhật ký/giữ lại cho mục đích gỡ lỗi.

Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
conversion_metric

Luôn có mặt

chuỗi

Chỉ số lượt chuyển đổi được dùng để phân bổ. Ban đầu, chúng tôi sẽ hỗ trợ một chỉ số lượt chuyển đổi.

conversion
timestamp

Luôn có mặt

số

Dấu thời gian UNIX khi sự kiện quảng cáo diễn ra, tính bằng giây với độ chính xác lên đến micrô giây. Bạn nên sử dụng giá trị này cho mô hình phân bổ theo lượt nhấp cuối cùng.

1432681913.123456
campaign_type

Luôn có mặt

chuỗi

Trường này sẽ xác định loại chiến dịch đã tạo ra sự kiện quảng cáo. Sau đây là các giá trị có thể có.

ACI
ACE
ACPre
Search
Display
Video
Shopping
Hotel
Performance_Max
Other

ACI là từ viết tắt của chiến dịch Quảng cáo ứng dụng để tăng lượt cài đặt. ACE là từ viết tắt của Chiến dịch quảng cáo ứng dụng để thúc đẩy sự tương tác.
campaign_id

Luôn có mặt

số

Mã chiến dịch dạng số của chiến dịch đã tạo ra sự kiện quảng cáo. Giá trị này được đảm bảo là duy nhất.

123456789
campaign_name

Luôn có mặt

chuỗi

Tên chiến dịch do nhà quảng cáo xác định của chiến dịch đã tạo ra sự kiện quảng cáo. Giá trị này không đảm bảo là giá trị duy nhất.

Occasional Gamers (Video)
ad_type

Luôn có mặt

chuỗi

Loại quảng cáo dẫn đến sự kiện quảng cáo. Bạn có thể dùng giá trị này để phân biệt các loại khoảng không quảng cáo như sau.

Quảng cáo ứng dụng 
ClickToDownload
 Lượt tương tác với ứng dụng 
AppDeepLink
 Lượt tương tác với ứng dụng – Quy trình Cài đặt và tiếp tục 
AppDeepLinkContinue
 Giá trị chung cho các giá trị khác 
Unknown
external_customer_id

Luôn có mặt

số

Giá trị nhận dạng nhà quảng cáo cho nhà quảng cáo sở hữu chiến dịch đã tạo ra sự kiện quảng cáo. Bạn có thể dùng giá trị này để phân biệt các tài khoản Google Ads.

123456789
location

Luôn có mặt

số

Mã vị trí địa lý của vị trí địa lý nơi diễn ra sự kiện quảng cáo. Tham khảo tài liệu tham khảo về API Google Ads để diễn giải mã vị trí.
network_type

Luôn có mặt

chuỗi

Trường này sẽ xác định mạng quảng cáo trên Google Ads mà sự kiện quảng cáo đã xảy ra. Các giá trị có thể có như sau.

Search
Display
YouTube
GoogleTv
cross-network
network_subtype

Sẽ là null khi campaign_type là ACI hoặc ACE và network_type là Display.

chuỗi

Trường này sẽ xác định "kiểu phụ" của mạng quảng cáo Google Ads mà sự kiện quảng cáo đã xảy ra. Các giá trị có thể có sẽ thay đổi tuỳ theo loại mạng chính.

Google Tìm kiếm thông thường 
GoogleSearch
 Đối tác tìm kiếm của Google 
SearchPartners

Màn hình

Nhà xuất bản web di động 
mGDN
 Nhà xuất bản ứng dụng 
Google AdMob

YouTube

Mạng video trên YouTube 
YouTubeVideos
 Mạng Tìm kiếm của YouTube 
YouTubeSearch
 Đối tác video 
VideoPartners

GoogleTv

Mạng video Google TV 
GoogleTvVideos

nhiều mạng

Chiến dịch Tối đa hoá hiệu suất trên nhiều mạng 
cross-network
video_id

Chỉ được cung cấp khi network_type là YouTube và campaign_type không phải là ACI và ACE.

chuỗi

Mã video trên YouTube được liên kết với sự kiện quảng cáo.

dQw4w9WgXcQ
keyword

Chỉ được cung cấp khi network_type là Search và campaign_type không phải là ACI và ACE.

chuỗi

Từ khoá tìm kiếm được liên kết với sự kiện quảng cáo.

+food +delivery
match_type

Chỉ được cung cấp khi network_type là Search và campaign_type không phải là ACI và ACE.

chuỗi

Kiểu khớp cho từ khoá tìm kiếm.

Chính xác 
e
 Cụm từ 
p
 Rộng 
b
placement

Chỉ được cung cấp khi network_type là Display và campaign_type không phải là ACI và ACE.

chuỗi

Vị trí được liên kết với sự kiện quảng cáo.

mobileapp::1-343200656
ad_group_id

Chỉ được cung cấp khi campaign_type không phải là Performance_Max.

số

Mã dạng số của nhóm quảng cáo đã tạo ra sự kiện quảng cáo. Giá trị này được đảm bảo là duy nhất.

123456789
ad_group_name

Chỉ được cung cấp khi campaign_type là ACI, ACE hoặc ACPRE.

chuỗi

Tên nhóm quảng cáo do nhà quảng cáo xác định của nhóm quảng cáo đã tạo ra sự kiện quảng cáo. Giá trị này không đảm bảo là giá trị duy nhất.

My App AdGroup
creative_id

Chỉ được cung cấp khi campaign_type không phải là ACI, ACE, ACPRE hoặc Performance_Max.

số

Mã dạng số của đơn vị quảng cáo mẫu quảng cáo đã tạo ra sự kiện quảng cáo. Giá trị này được đảm bảo là duy nhất.

123456789
interaction_type

Trường này sẽ luôn là mức độ tương tác.

chuỗi

Câu trả lời mẫu

Sau đây là ví dụ về phản hồi theo dõi lượt chuyển đổi khi yêu cầu có chứa lỗi:

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

Ví dụ về một phản hồi theo dõi lượt chuyển đổi tiêu cực là:

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

Phản hồi theo dõi lượt chuyển đổi sẽ được trả về cho tất cả các yêu cầu theo dõi lượt chuyển đổi.

Sau đây là ví dụ về một phản hồi khẳng định về hoạt động theo dõi lượt chuyển đổi cho một người dùng không thuộc Khu vực kinh tế Châu Âu (EEA) đối với một Chiến dịch quảng cáo ứng dụng toàn cầu:

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

Ví dụ về phản hồi khẳng định của tính năng theo dõi lượt chuyển đổi cho một người dùng không thuộc Khu vực kinh tế Châu Âu (EEA) đối với chiến dịch Tìm kiếm là:

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

Ví dụ về phản hồi khẳng định về tính năng theo dõi lượt chuyển đổi cho một người dùng không thuộc Khu vực kinh tế Châu Âu (EEA) đối với chiến dịch Hiển thị là:

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

Ví dụ về phản hồi khẳng định của tính năng theo dõi lượt chuyển đổi cho một người dùng không thuộc Khu vực kinh tế Châu Âu (EEA) trong một chiến dịch trên 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
}


Yêu cầu phân bổ trên nhiều mạng

Khi Google Ads phản hồi tích cực cho một yêu cầu theo dõi lượt chuyển đổi, người dùng API phải thông báo cho Google Ads về quyết định phân bổ trên nhiều mạng sau khi xác định được lượt nhấp cuối cùng.

Yêu cầu phân bổ trên nhiều mạng giống với yêu cầu theo dõi lượt chuyển đổi ban đầu, nhưng có đường dẫn yêu cầu là:

/pagead/conversion/app/1.0/cross_network

và việc bổ sung hai tham số bắt buộc:

Yêu cầu phân bổ trên nhiều mạng
ad_event_id

Bắt buộc

Vị trí: Truy vấn

Giá trị nhận dạng ad_event_id từ sự kiện quảng cáo được liên kết với mô hình phân bổ trong yêu cầu trước đó.
attributed

Bắt buộc

Vị trí: Truy vấn

API người dùng có nhận được giá trị đóng góp cho lượt chuyển đổi trên Google Ads hay không. 0 hoặc 1.

Sau đây là ví dụ về một yêu cầu phân bổ hợp lệ trên nhiều mạng:

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

Một yêu cầu phân bổ trên nhiều mạng hợp lệ sẽ luôn nhận được phản hồi chung 200 mà không có nội dung phản hồi.