- Yêu cầu HTTP
- Tham số đường dẫn
- Nội dung yêu cầu
- Nội dung phản hồi
- Phạm vi uỷ quyền
- CampaignDuration
- FrequencyCap,
- EffectiveFrequencyLimit
- Nhắm mục tiêu
- AudienceTargeting
- PlannedProduct
- AdvancedProductTargeting
- YouTubeSelectSettings
- ForecastMetricOptions (Lựa chọn dự báo về số liệu dự báo)
- OnTargetAudienceMetrics
- ReachCurve
- ReachForecast
- Dự đoán
- EffectiveFrequencyBreakdown
- PlannedProductReachForecast
- PlannedProductForecast
- Hãy làm thử!
Tạo thông tin dự báo về phạm vi tiếp cận cho một tiêu chí nhắm mục tiêu / kiểu kết hợp các loại quảng cáo nhất định.
Danh sách các lỗi đã gửi: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError
Yêu cầu HTTP
POST https://googleads.googleapis.com/v14/customers/{customerId}:generateReachForecast
URL sử dụng cú pháp Chuyển mã gRPC.
Tham số đường dẫn
Tham số | |
---|---|
customerId |
Bắt buộc. Mã của khách hàng. |
Nội dung yêu cầu
Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:
Biểu diễn dưới dạng JSON |
---|
{ "campaignDuration": { object ( |
Trường | |
---|---|
campaignDuration |
Bắt buộc. Thời lượng chiến dịch. |
cookieFrequencyCapSetting |
Giới hạn tần suất cookie đã chọn sẽ áp dụng cho từng sản phẩm theo kế hoạch. Giá trị này tương đương với giới hạn tần suất xuất hiện trong Google Ads khi bạn tạo chiến dịch. Giới hạn này thể hiện số lần tối đa một quảng cáo có thể hiển thị cho cùng một người dùng trong khoảng thời gian chỉ định. Nếu không được chỉ định, giá trị mặc định là 0 (không giới hạn) sẽ được áp dụng. Trường này thay thế trường cookieFrequencyCap không dùng nữa. |
targeting |
Tiêu chí nhắm mục tiêu cần áp dụng cho tất cả sản phẩm đã chọn trong kiểu kết hợp các loại quảng cáo. Đây là tính năng nhắm mục tiêu theo kế hoạch: chi tiết thực thi có thể thay đổi dựa trên sản phẩm quảng cáo, hãy tham khảo ý kiến của chuyên gia triển khai. Xem các chỉ số cụ thể để biết chi tiết về mức độ ảnh hưởng của việc nhắm mục tiêu đến các chỉ số đó. |
plannedProducts[] |
Bắt buộc. Sản phẩm cần dự đoán. Số lượng sản phẩm đã lập kế hoạch tối đa được phép là 15. |
forecastMetricOptions |
Kiểm soát các chỉ số dự báo được trả về trong phản hồi. |
currencyCode |
Mã đơn vị tiền tệ. Mã tiền tệ gồm ba ký tự theo tiêu chuẩn ISO 4217. |
cookieFrequencyCap |
Giới hạn tần suất cookie đã chọn sẽ áp dụng cho từng sản phẩm theo kế hoạch. Giá trị này tương đương với giới hạn tần suất hiển thị trong Google Ads khi bạn tạo chiến dịch, nó thể hiện số lần tối đa một quảng cáo có thể hiển thị cho cùng một người dùng. Nếu không chỉ định thì sẽ không có giới hạn nào được áp dụng. Trường này không được dùng trong phiên bản 4 nữa và cuối cùng sẽ bị xoá. Thay vào đó, hãy sử dụng cookieFrequencyCapsetting. |
minEffectiveFrequency |
Tần suất hiệu quả tối thiểu đã chọn (số lần một người xem quảng cáo) cho các chỉ số phạm vi tiếp cận được báo cáo [1-10]. Việc này sẽ không ảnh hưởng đến tiêu chí nhắm mục tiêu mà chỉ ảnh hưởng đến báo cáo. Nếu không chỉ định, giá trị mặc định sẽ được áp dụng là 1. Không thể kết hợp trường này với trườngeffectiveFrequencyLimit. |
effectiveFrequencyLimit |
Giá trị tần suất hiệu quả tối thiểu cao nhất (số lần một người tiếp xúc với quảng cáo) [1-10] để đưa vào Forecast.effective_frequency_breakdowns. Nếu bạn không chỉ định, hệ thống sẽ không cung cấp thông tin Forecast.effective_frequency_breakdowns. Giá trị tần suất hiệu quả được cung cấp tại đây cũng sẽ được dùng làm tần suất hiệu quả tối thiểu cho các chỉ số phạm vi tiếp cận được báo cáo. Không thể kết hợp trường này với trường min EffectiveFrequency. |
customerReachGroup |
Tên của khách hàng cần được lập kế hoạch. Đây là giá trị do người dùng xác định. |
Nội dung phản hồi
Tin nhắn trả lời có chứa đường cong phạm vi tiếp cận đã tạo.
Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:
Biểu diễn dưới dạng JSON |
---|
{ "onTargetAudienceMetrics": { object ( |
Trường | |
---|---|
onTargetAudienceMetrics |
Tham chiếu về đối tượng mục tiêu cho đường cong này. |
reachCurve |
Đường cong phạm vi tiếp cận được tạo cho kiểu kết hợp sản phẩm theo kế hoạch. |
Phạm vi uỷ quyền
Yêu cầu phạm vi OAuth sau:
https://www.googleapis.com/auth/adwords
Để biết thêm thông tin, hãy xem Tổng quan về OAuth 2.0.
CampaignDuration
Thời lượng của chiến dịch theo kế hoạch.
Biểu diễn dưới dạng JSON |
---|
{
"dateRange": {
object ( |
Trường | |
---|---|
dateRange |
Phạm vi ngày của chiến dịch. Ngày có định dạng yyyy-mm-dd và toàn bộ. Ngày kết thúc phải nhỏ hơn 1 năm trong tương lai và phạm vi ngày phải nhỏ hơn 92 ngày. Không thể kết hợp trường này với trường DurationInDays. |
durationInDays |
Giá trị thời lượng tính bằng ngày. Không thể kết hợp trường này với trường dateRange. |
FrequencyCap
Quy tắc chỉ định số lần tối đa một quảng cáo có thể hiển thị cho người dùng trong một khoảng thời gian cụ thể.
Biểu diễn dưới dạng JSON |
---|
{
"impressions": integer,
"timeUnit": enum ( |
Trường | |
---|---|
impressions |
Bắt buộc. Số lượt hiển thị, tính toàn bộ. |
timeUnit |
Bắt buộc. Loại đơn vị thời gian. |
EffectiveFrequencyLimit
Giới hạn tần suất hiệu quả.
Biểu diễn dưới dạng JSON |
---|
{ "effectiveFrequencyBreakdownLimit": integer } |
Trường | |
---|---|
effectiveFrequencyBreakdownLimit |
Giá trị tần suất hiệu quả cao nhất để đưa vào thuộc tính Forecast.effective_frequency_breakdowns. Trường này hỗ trợ các tần số từ 1 đến 10. |
Nhắm mục tiêu
Tiêu chí nhắm mục tiêu mà các chỉ số về lưu lượng truy cập sẽ được báo cáo.
Biểu diễn dưới dạng JSON |
---|
{ "plannableLocationIds": [ string ], "ageRange": enum ( |
Trường | |
---|---|
plannableLocationIds[] |
Danh sách mã vị trí có thể lập kế hoạch để nhắm mục tiêu bằng thông tin dự đoán này. Nếu bạn cung cấp nhiều mã, thì tất cả các mã đều phải có cùng một Các yêu cầu phải đặt trường này hoặc |
ageRange |
Độ tuổi nhắm mục tiêu. Một giá trị chưa được đặt sẽ tương đương với việc nhắm đến mọi độ tuổi. |
genders[] |
Giới tính được nhắm mục tiêu. Một giá trị chưa được đặt tương đương với việc nhắm mục tiêu MALE và FEMALE. |
devices[] |
Thiết bị mục tiêu. Nếu bạn không chỉ định, thì tính năng này sẽ nhắm mục tiêu tất cả thiết bị có thể áp dụng. Các thiết bị áp dụng thay đổi tuỳ theo sản phẩm và khu vực, đồng thời có thể được lấy tại |
network |
Mạng có thể nhắm mục tiêu cho sản phẩm quảng cáo. Nếu bạn không chỉ định, hãy nhắm mục tiêu tất cả các mạng áp dụng. Các mạng áp dụng khác nhau tuỳ theo sản phẩm và khu vực, và bạn có thể lấy tại |
audienceTargeting |
Đối tượng được nhắm mục tiêu. Nếu không xác định, không nhắm mục tiêu đến bất kỳ đối tượng cụ thể nào. |
plannableLocationId |
Mã của vị trí đã chọn. Bạn có thể lấy mã vị trí có thể lập kế hoạch từ Các yêu cầu phải đặt trường này hoặc Trường này sẽ không được dùng nữa kể từ phiên bản 12 và sẽ bị xoá trong bản phát hành sau này. Thay vào đó, hãy sử dụng |
AudienceTargeting
Nhắm mục tiêu theo đối tượng để dự đoán phạm vi tiếp cận.
Biểu diễn dưới dạng JSON |
---|
{
"userInterest": [
{
object ( |
Trường | |
---|---|
userInterest[] |
Danh sách đối tượng dựa trên mối quan tâm của người dùng cần nhắm mục tiêu. |
PlannedProduct
Sản phẩm đang được lên kế hoạch để tiếp cận.
Biểu diễn dưới dạng JSON |
---|
{
"advancedProductTargeting": {
object ( |
Trường | |
---|---|
advancedProductTargeting |
Cài đặt nhắm mục tiêu cho sản phẩm đã chọn. Để liệt kê tiêu chí nhắm mục tiêu có sẵn cho mỗi sản phẩm, hãy sử dụng |
plannableProductCode |
Bắt buộc. Sản phẩm đã chọn để lên kế hoạch. Mã được liên kết với sản phẩm quảng cáo (ví dụ: Trueview, Quảng cáo đệm). Để liệt kê các mã sản phẩm hiện có, hãy sử dụng |
budgetMicros |
Bắt buộc. Phân bổ ngân sách tối đa cực nhỏ cho sản phẩm đã chọn. Giá trị được chỉ định trong mã đơn vị tiền tệ lập kế hoạch đã chọn. Ví dụ: 1 000 000$ = 1 000 000 000 000 micros. |
AdvancedProductTargeting
Cài đặt nhắm mục tiêu nâng cao cho sản phẩm.
Biểu diễn dưới dạng JSON |
---|
{ // Union field |
Trường | |
---|---|
Trường hợp advanced_targeting . Tùy chọn nhắm mục tiêu cho sản phẩm này. advanced_targeting chỉ có thể là một trong những trạng thái sau: |
|
youtubeSelectSettings |
Chế độ cài đặt cho tính năng nhắm mục tiêu trên YouTube Chọn lọc. |
YouTubeSelectSettings
Yêu cầu chế độ cài đặt cho Nhóm YouTube Chọn lọc
Biểu diễn dưới dạng JSON |
---|
{ "lineupId": string } |
Trường | |
---|---|
lineupId |
Nhóm kênh nổi tiếng dùng tính năng Nhắm mục tiêu trên YouTube Chọn lọc. |
ForecastMetricOptions
Kiểm soát các chỉ số dự báo sẽ trả về.
Biểu diễn dưới dạng JSON |
---|
{ "includeCoview": boolean } |
Trường | |
---|---|
includeCoview |
Cho biết liệu có đưa các chỉ số về hoạt động cùng xem vào thông tin dự đoán phản hồi hay không. |
OnTargetAudienceMetrics
Chỉ số về đối tượng cho các sản phẩm theo kế hoạch. Các chỉ số này xem xét các phương diện nhắm mục tiêu sau:
- Vị trí
- PlannableAgeRange
- Giới tính
- Nhắm mục tiêu đối tượng (chỉ dành cho youtubeAudienceSize)
Biểu diễn dưới dạng JSON |
---|
{ "youtubeAudienceSize": string, "censusAudienceSize": string } |
Trường | |
---|---|
youtubeAudienceSize |
Quy mô đối tượng tham chiếu phù hợp với tiêu chí nhắm mục tiêu được xem xét cho YouTube. |
censusAudienceSize |
Quy mô đối tượng tham chiếu phù hợp với tiêu chí nhắm mục tiêu được xem xét trong dữ liệu điều tra dân số. |
ReachCurve
Đường cong phạm vi tiếp cận cho các sản phẩm theo kế hoạch.
Biểu diễn dưới dạng JSON |
---|
{
"reachForecasts": [
{
object ( |
Trường | |
---|---|
reachForecasts[] |
Tất cả các điểm trên đường cong phạm vi tiếp cận. |
ReachForecast
Một điểm trên đường cong phạm vi tiếp cận.
Biểu diễn dưới dạng JSON |
---|
{ "costMicros": string, "forecast": { object ( |
Trường | |
---|---|
costMicros |
Chi phí tính theo phần triệu. |
forecast |
Chỉ số lưu lượng truy cập được dự đoán cho thời điểm này. |
plannedProductReachForecasts[] |
Các chỉ số về lưu lượng truy cập và mức phân bổ được dự báo cho từng sản phẩm theo kế hoạch tại thời điểm này trên đường cong phạm vi tiếp cận. |
Thông tin dự đoán
Chỉ số lưu lượng truy cập dự đoán cho sản phẩm dự kiến và tiêu chí nhắm mục tiêu.
Biểu diễn dưới dạng JSON |
---|
{
"effectiveFrequencyBreakdowns": [
{
object ( |
Trường | |
---|---|
effectiveFrequencyBreakdowns[] |
Danh sách thông tin dự đoán tần suất hiệu quả. Danh sách này được sắp xếp theo thứ tự bắt đầu bằng 1 trở lên và kết thúc bằng giá trị được đặt trong GenerateReachForecastRequest.effective_frequency_limit. Nếu bạn không đặteffectivefrequencyLimit thì danh sách này sẽ trống. |
onTargetReach |
Số người riêng biệt đã tiếp cận được ít nhất lần GenerateReachForecastRequest.min_effective_frequency hoặc GenerateReachForecastRequest.effective_frequency_limit với số lần khớp chính xác với Tiêu chí nhắm mục tiêu. Xin lưu ý rằng dữ liệu phải đạt đến một số lượng người duy nhất tối thiểu thì dữ liệu mới được báo cáo. Nếu không đáp ứng số lượng tối thiểu, thì giá trị onTargetReach sẽ được làm tròn thành 0. |
totalReach |
Tổng số người riêng biệt đã tiếp cận được ít nhất lần GenerateReachForecastRequest.min_effective_frequency hoặc GenerateReachForecastRequest.effective_frequency_limit lần. Bao gồm cả những người có thể nằm ngoài Phạm vi nhắm mục tiêu được chỉ định. Xin lưu ý rằng dữ liệu phải đạt đến một số lượng người duy nhất tối thiểu thì dữ liệu mới được báo cáo. Nếu không đáp ứng số lượng tối thiểu, thì giá trị tổng phạm vi tiếp cận sẽ được làm tròn thành 0. |
onTargetImpressions |
Số lượt hiển thị quảng cáo khớp chính xác với tiêu chí Nhắm mục tiêu. |
totalImpressions |
Tổng số lượt hiển thị quảng cáo. Số liệu này bao gồm những lượt hiển thị có thể nằm ngoài phạm vi Nhắm mục tiêu được chỉ định, do không có đủ thông tin về người dùng đã đăng nhập. |
viewableImpressions |
Số lần hiển thị của quảng cáo được coi là có thể xem. Xem https://support.google.com/google-ads/answer/7029393 để biết thêm thông tin về điều gì khiến quảng cáo có thể xem và cách đo lường khả năng xem. |
onTargetCoviewReach |
Số người riêng biệt đã tiếp cận khớp chính xác với tiêu chí Nhắm mục tiêu bao gồm cả những người cùng xem. |
totalCoviewReach |
Số người riêng biệt đã tiếp cận được, bao gồm cả những người cùng xem. Bao gồm cả những người có thể nằm ngoài Phạm vi nhắm mục tiêu được chỉ định. |
onTargetCoviewImpressions |
Số lượt hiển thị quảng cáo khớp chính xác với tiêu chí Nhắm mục tiêu bao gồm cả những người cùng xem. |
totalCoviewImpressions |
Tổng số lượt hiển thị quảng cáo, bao gồm cả những người cùng xem. Số liệu này bao gồm những lượt hiển thị có thể nằm ngoài phạm vi Nhắm mục tiêu được chỉ định, do không có đủ thông tin về người dùng đã đăng nhập. |
EffectiveFrequencyBreakdown
Bảng chi tiết về số người riêng biệt được tiếp cận tại một tần suất hiệu quả nhất định.
Biểu diễn dưới dạng JSON |
---|
{ "effectiveFrequency": integer, "onTargetReach": string, "totalReach": string, "effectiveCoviewReach": string, "onTargetEffectiveCoviewReach": string } |
Trường | |
---|---|
effectiveFrequency |
Tần suất hiệu quả [1-10]. |
onTargetReach |
Số người riêng biệt đã đạt được ít nhất Lần tần suất hiệu quả khớp chính xác với Nhắm mục tiêu. Xin lưu ý rằng dữ liệu phải đạt đến một số lượng người duy nhất tối thiểu thì dữ liệu mới được báo cáo. Nếu không đáp ứng số lượng tối thiểu, thì giá trị onTargetReach sẽ được làm tròn thành 0. |
totalReach |
Tổng số người riêng biệt đã đạt được ít nhất lần tần suất hiệu quả. Bao gồm cả những người có thể nằm ngoài Phạm vi nhắm mục tiêu được chỉ định. Xin lưu ý rằng dữ liệu phải đạt đến một số lượng người duy nhất tối thiểu thì dữ liệu mới được báo cáo. Nếu không đáp ứng số lượng tối thiểu, thì giá trị tổng phạm vi tiếp cận sẽ được làm tròn thành 0. |
effectiveCoviewReach |
Số người dùng (bao gồm cả người dùng cùng xem) đã tiếp cận được giá trị Thử nghiệm tần suất hiệu quả được liên kết. |
onTargetEffectiveCoviewReach |
Số người dùng (bao gồm cả người dùng cùng xem) đã tiếp cận được giá trị PerformanceFrequency (Tần suất hiệu quả) được liên kết trong phạm vi thông tin nhân khẩu học của kế hoạch đã chỉ định. |
PlannedProductReachForecast
Các chỉ số về lưu lượng truy cập và mức phân bổ được dự báo cho một sản phẩm cụ thể tại một điểm trên đường cong phạm vi tiếp cận.
Biểu diễn dưới dạng JSON |
---|
{
"plannableProductCode": string,
"costMicros": string,
"plannedProductForecast": {
object ( |
Trường | |
---|---|
plannableProductCode |
Sản phẩm đã chọn để lên kế hoạch. Các mã sản phẩm được trả về nằm trong tập hợp các mã được ListPlannableProducts trả về khi sử dụng cùng một mã vị trí. |
costMicros |
Chi phí tính theo phần triệu. Giá trị này có thể khác với mức phân bổ đầu vào của sản phẩm nếu một hoặc nhiều sản phẩm theo kế hoạch không thể sử dụng hết ngân sách do kho hàng có giới hạn. |
plannedProductForecast |
Chỉ số lưu lượng truy cập được dự đoán cho sản phẩm này. |
PlannedProductForecast
Chỉ số về lưu lượng truy cập được dự báo cho một sản phẩm theo kế hoạch.
Biểu diễn dưới dạng JSON |
---|
{ "onTargetReach": string, "totalReach": string, "onTargetImpressions": string, "totalImpressions": string, "viewableImpressions": string, "onTargetCoviewReach": string, "totalCoviewReach": string, "onTargetCoviewImpressions": string, "totalCoviewImpressions": string } |
Trường | |
---|---|
onTargetReach |
Số người duy nhất đã tiếp cận khớp chính xác với Nhắm mục tiêu. Xin lưu ý rằng dữ liệu phải đạt đến một số lượng người duy nhất tối thiểu thì dữ liệu mới được báo cáo. Nếu không đáp ứng số lượng tối thiểu, thì giá trị onTargetReach sẽ được làm tròn thành 0. |
totalReach |
Số người duy nhất đã tiếp cận được. Bao gồm cả những người có thể nằm ngoài Phạm vi nhắm mục tiêu được chỉ định. Xin lưu ý rằng dữ liệu phải đạt đến một số lượng người duy nhất tối thiểu thì dữ liệu mới được báo cáo. Nếu không đáp ứng số lượng tối thiểu, thì giá trị tổng phạm vi tiếp cận sẽ được làm tròn thành 0. |
onTargetImpressions |
Số lượt hiển thị quảng cáo khớp chính xác với tiêu chí Nhắm mục tiêu. |
totalImpressions |
Tổng số lượt hiển thị quảng cáo. Số liệu này bao gồm những lượt hiển thị có thể nằm ngoài phạm vi Nhắm mục tiêu được chỉ định, do không có đủ thông tin về người dùng đã đăng nhập. |
viewableImpressions |
Số lần hiển thị của quảng cáo được coi là có thể xem. Xem https://support.google.com/google-ads/answer/7029393 để biết thêm thông tin về điều gì khiến quảng cáo có thể xem và cách đo lường khả năng xem. |
onTargetCoviewReach |
Số người riêng biệt đã tiếp cận khớp chính xác với tiêu chí Nhắm mục tiêu bao gồm cả những người cùng xem. |
totalCoviewReach |
Số người riêng biệt đã tiếp cận được, bao gồm cả những người cùng xem. Bao gồm cả những người có thể nằm ngoài Phạm vi nhắm mục tiêu được chỉ định. |
onTargetCoviewImpressions |
Số lượt hiển thị quảng cáo khớp chính xác với tiêu chí Nhắm mục tiêu bao gồm cả những người cùng xem. |
totalCoviewImpressions |
Tổng số lượt hiển thị quảng cáo, bao gồm cả những người cùng xem. Số liệu này bao gồm những lượt hiển thị có thể nằm ngoài phạm vi Nhắm mục tiêu được chỉ định, do không có đủ thông tin về người dùng đã đăng nhập. |