Trang này được dịch bởi Cloud Translation API.

API Alpha báo cáo hoạt động quảng cáo

Báo cáo Hoạt động quảng cáo là một thông tin tập trung về hiệu suất quảng cáo. Công cụ này kết hợp dữ liệu, chỉ số và các phương diện từ API báo cáo mạng và API báo cáo dàn xếp cũng như dữ liệu đặt giá thầu vào một báo cáo hợp nhất duy nhất.

Ads Activity Report API cung cấp thêm những điểm cải tiến từ tính năng Dàn xếp Báo cáo API và API Báo cáo mạng như minh hoạ trong bảng dưới đây:

	API Báo cáo mạng	API Báo cáo dàn xếp	API Báo cáo hoạt động trên Google Ads
Hiệu suất mạng	✅	✅	✅
Hiệu suất thác nước		✅	✅
Hiệu suất của chiến lược đặt giá thầu			✅
Hiệu suất của thử nghiệm A/B cho tính năng dàn xếp			✅
Báo cáo theo giờ			✅
Kích thước báo cáo	100.000	100.000	500.000

Các chỉ số, phương diện và bộ lọc phương diện

Các chỉ số sau đây đã được thêm vào Ads Activity Report API trong ngoài nhiều chỉ số có sẵn trong Network Report API và API Báo cáo dàn xếp.

Chỉ số	Mô tả
BID_REQUEST	Số yêu cầu được gửi đến nguồn quảng cáo đặt giá thầu.
BIDS_IN_AUCTION	Số lượng giá thầu mà nguồn quảng cáo tham gia các phiên đấu giá đặt giá thầu đã gửi.
WINNING_BIDS	Số lượng giá thầu đã thắng một phiên đấu giá đặt giá thầu.

Các phương diện mới sau đây được đưa vào API Báo cáo hoạt động quảng cáo.

Phương diện	Mô tả
TUẦN	Ngày đầu tiên trong một tuần (theo ngôn ngữ mã đề cập trong chế độ cài đặt bản địa hoá) ở định dạng YYYYMMDD (đối với ví dụ: "20210701"). Các yêu cầu chỉ có thể chỉ định một trong các giá trị DATE, WEEK, hoặc MONTH phương diện thời gian.
GIỜ	Giờ ở định dạng HH theo giờ PST. Ví dụ: "05" trong 5 giờ sáng theo giờ PST, "13" trong 1 giờ chiều theo giờ PST. Thứ nguyên DATE cũng phải được chỉ định trong yêu cầu. Đáp tối đa 28 ngày dữ liệu được trả về khi thứ nguyên HOUR được chỉ định. Ngày bắt đầu phạm vi ngày trước ngày hiện tại 28 ngày trở lên trả về lỗi.
MEDIATION_AB_TEST (tên thử nghiệm)	Xem hiệu suất theo thử nghiệm A/B cho tính năng dàn xếp. Bắt buộc phải chỉ định mã này nếu tham số VARIANT được chỉ định.
MEDIATION_AB_TEST_VARIANT (Biến thể A, Biến thể B)	Xem hiệu suất theo biến thể thử nghiệm A/B dàn xếp.

Tên thứ nguyên trong API Báo cáo dàn xếp	Tên phương diện trong Ads Activity Report API (API Báo cáo hoạt động quảng cáo)	Mô tả
AD_UNIT¹	AD_UNIT_ID	Mã nhận dạng duy nhất của đơn vị quảng cáo (ví dụ: "123456789").
AD_UNIT¹	AD_UNIT_NAME	Tên của đơn vị quảng cáo.
ỨNG DỤNG¹	APP_ID	Mã nhận dạng duy nhất của ứng dụng di động (ví dụ: "1234567890").
ỨNG DỤNG¹	APP_NAME	Tên ứng dụng.
AD_SOURCE¹	AD_SOURCE_ID	Mã nhận dạng duy nhất của nguồn quảng cáo (ví dụ: "1234567890123456789".
AD_SOURCE¹	AD_SOURCE_NAME	Tên của nguồn quảng cáo (ví dụ: "Mạng AdMob").
AD_SOURCE_INSTANCE¹	AD_SOURCE_INSTANCE_ID	Mã nhận dạng duy nhất của phiên bản nguồn quảng cáo (ví dụ: "123456789012").
AD_SOURCE_INSTANCE¹	AD_SOURCE_INSTANCE_NAME	Tên của phiên bản nguồn quảng cáo (ví dụ: "AdMob (mặc định)").
MEDIATION_GROUP¹	MEDIATION_GROUP_ID	Mã nhận dạng duy nhất của nhóm dàn xếp (ví dụ: "1234567890").
MEDIATION_GROUP¹	MEDIATION_GROUP_NAME	Mã nhận dạng duy nhất của nhóm dàn xếp (ví dụ: "AdMob (mặc định)").

¹: Xem bài viết Scalars để biết thêm thông tin.

Các phương diện sau đây đã cập nhật định dạng.

Tên thứ nguyên trong API Báo cáo dàn xếp	Nội dung mô tả trong Mediation Report API (API Báo cáo dàn xếp)	Nội dung mô tả trong Ads Activity Report API (API Báo cáo hoạt động quảng cáo)
ESTIMATED_EARNINGS	Thu nhập ước tính của nhà xuất bản AdMob. Đơn vị tiền tệ (USD, EUR hoặc loại khác) của các chỉ số thu nhập được xác định theo nội dung bản địa hoá cho đơn vị tiền tệ. Số lượng được tính bằng phần triệu. Ví dụ: 6, 5 đô la sẽ là được biểu thị bằng 6500000. Thu nhập ước tính trên mỗi nhóm dàn xếp và mỗi cấp phiên bản nguồn quảng cáo là được hỗ trợ kể từ ngày 20 tháng 10 năm 2019. Thu nhập ước tính của bên thứ ba sẽ hiển thị 0 cho ngày trước ngày 20 tháng 10 năm 2019.	Thu nhập ước tính của nhà xuất bản AdMob. Đơn vị tiền tệ (USD, EUR hoặc loại khác) của các chỉ số thu nhập được xác định theo nội dung bản địa hoá cho đơn vị tiền tệ.
OBSERVED_ECPM	eCPM trung bình ước tính của mạng quảng cáo bên thứ ba. Đơn vị tiền tệ (USD, EUR hoặc loại khác) của các chỉ số thu nhập được xác định theo nội dung bản địa hoá cho đơn vị tiền tệ. Số lượng được tính bằng phần triệu. Ví dụ: 2, 30 đô la sẽ là được biểu thị bằng 2300000. eCPM trung bình ước tính trên mỗi nhóm dàn xếp và mỗi cấp phiên bản nguồn quảng cáo được hỗ trợ kể từ ngày 20 tháng 10 năm 2019. Mức trung bình ước tính của bên thứ ba eCPM sẽ hiển thị bằng 0 cho các ngày trước ngày 20/10/2019.	eCPM trung bình cho tất cả quảng cáo. Đơn vị tiền tệ (USD, EUR hoặc đơn vị tiền tệ khác) của các chỉ số thu nhập được xác định theo chế độ cài đặt bản địa hoá cho đơn vị tiền tệ. eCPM trung bình trên mỗi nhóm dàn xếp và trên mỗi phiên bản nguồn quảng cáo là được hỗ trợ kể từ ngày 20 tháng 10 năm 2019. OBSERVED_ECPM sẽ hiển thị 0 cho các ngày trước ngày 20 tháng 10 năm 2019.

Scalars

Các phương diện bên dưới đã được cập nhật trong Ads Activity Report API (API Báo cáo hoạt động quảng cáo) để các giá trị vô hướng thay vì đối tượng. Việc này sẽ giúp câu trả lời đơn giản hơn và giảm bớt độ phức tạp của chúng.

Các phương diện bị ảnh hưởng trong API Báo cáo dàn xếp và API Báo cáo mạng:

AD_UNIT
APP
AD_SOURCE
AD_SOURCE_INSTANCE
MEDIATION_GROUP

Dữ liệu phản hồi báo cáo mẫu
Định dạng phương diện Dàn xếp / API Mạng	"AD_UNIT": { "value":"ca-app-pub-XXXXXXXXXXXXXXXXX/YYYYYYYYYY", "displayLabel": "Test ad unit name" }
Định dạng phương diện API AAR	"AD_UNIT_NAME": "Test ad unit name", "AD_UNIT_ID": "ca-app-pub-XXXXXXXXXXXXXXXXX/YYYYYYYYYY"

Báo cáo theo giờ

Giờ đây, bạn có thể xem hiệu suất theo giờ trong API AdMob. Báo cáo hàng giờ là có sẵn trong tối đa 28 ngày.

Thứ nguyên DATE cũng phải được chỉ định trong yêu cầu để truy xuất hàng giờ . Hệ thống sẽ trả về dữ liệu tối đa 28 ngày khi phương diện HOUR là đã chỉ định. Ngày bắt đầu phạm vi ngày trên 28 ngày trước ngày ngày hiện tại trả về một lỗi.

Kích thước báo cáo lớn hơn

Ads Activity Report API cho phép bạn truy xuất tổng cộng 500.000 hàng. Cho để biết thêm thông tin, hãy xem hướng dẫn về hạn mức.

Tạo yêu cầu

Làm theo các bước sau để tạo yêu cầu.

curl (dòng lệnh)

Yêu cầu bằng curl

Tải tệp mật khẩu ứng dụng khách và tạo thông tin xác thực cho phép.

Vào lần đầu tiên thực hiện bước này, bạn sẽ được yêu cầu chấp nhận một trong trình duyệt của bạn. Trước khi chấp nhận, hãy đảm bảo bạn đăng nhập bằng Tài khoản Google có quyền truy cập vào API AdMob. Thông tin ứng dụng sẽ được uỷ quyền truy cập dữ liệu thay mặt cho bất kỳ tài khoản hiện đã đăng nhập.

Để xác thực và uỷ quyền, bạn nên sử dụng oauth2l, một công cụ dòng lệnh đơn giản dành cho hoạt động với Google OAuth 2.0. Cài đặt oauth2l và chạy bên dưới, thay thế path_to_credentials_json bằng một đường dẫn vào tệp credentials.json mà bạn tải xuống khi đăng ký đám mây. Trong lần chạy đầu tiên, lệnh này sẽ hướng dẫn bạn qua Quy trình uỷ quyền OAuth 2.0. Các lần chạy tiếp theo sẽ làm mới mã thông báo tự động.
```
~/go/bin/oauth2l header --json path_to_credentials_json \
        https://www.googleapis.com/auth/admob.readonly
```

Tạo báo cáo hoạt động quảng cáo.

curl -X POST https://admob.googleapis.com/v1alpha/accounts/pub-XXXXXXXXXXXXXXXX/adsActivityReport:generate \
     -H "Content-Type: application/json" \
     -H "$(~/go/bin/oauth2l header --json path_to_credentials_json https://www.googleapis.com/auth/admob.readonly)"  --data @- << EOF
      {
        "report_spec": {
        "date_range": {
          "start_date": {"year": 2023, "month": 1, "day": 1},
          "end_date": {"year": 2023, "month": 1, "day": 2}
        },
        "dimensions": ["DATE", "HOUR", "MEDIATION_AB_TEST", "VARIANT", "AD_SOURCE_ID", "AD_SOURCE_NAME"],
        "metrics": ["CLICKS", "BID_REQUEST","WINNING_BIDS", "IMPRESSIONS", "ESTIMATED_EARNINGS" ],
        "dimension_filters": [{"dimension": "COUNTRY", "matches_any": {"values": ["US"]}}],
        "sort_conditions": [{"metric":"CLICKS", "order": "DESCENDING"}],
        "localization_settings": {"currency_code": "USD", "language_code": "en-US"}
        }
      }
EOF

Câu trả lời mẫu:

{
"rows": [
  {
    "dimensionValues": {
      "DATE": {
        "value": "20221102"
      },
      "HOUR": {
        "value": "23"
      },
      "MEDIATION_AB_TEST": {
        "value": "Mediation AB Test"
      },
      "VARIANT": {
        "value": "Variant A"
      },
      "AD_SOURCE_ID": {
        "value": "5450213213286189855"
      },
      "AD_SOURCE_NAME": {
        "value": "AdMob Network"
      }
    },
    "metricValues": {
      "CLICKS": {
        "doubleValue": 0
      },
      "BID_REQUEST": {
        "integerValue": "27"
      },
      "WINNING_BIDS": {
        "doubleValue": 0.1111111111111111
      },
      "IMPRESSIONS": {
        "integerValue": "2"
      },
      "ESTIMATED_EARNINGS": {
        "doubleValue": 0
      }
    }
  },
{
    "dimensionValues": {
      "DATE": {
        "value": "20221102"
      },
      "HOUR": {
        "value": "23"
      },
      "MEDIATION_AB_TEST": {
        "value": "Mediation AB Test"
      },
      "VARIANT": {
        "value": "Variant B"
      },
      "AD_SOURCE_ID": {
        "value": "5450213213286189855"
      },
      "AD_SOURCE_NAME": {
        "value": "AdMob Network"
      }
    },
    "metricValues": {
      "CLICKS": {
        "doubleValue": 1
      },
      "BID_REQUEST": {
        "integerValue": "6"
      },
      "WINNING_BIDS": {
        "doubleValue": 1
      },
      "IMPRESSIONS": {
        "integerValue": "3"
      },
      "ESTIMATED_EARNINGS": {
        "doubleValue": 0.000427519
      }
    }
  }
]}