Method: advertisers.reachForecast.generateReachForecast

تنشئ هذه الطريقة توقّعات بشأن مدى الوصول إلى الجمهور لمعلِن معيّن وإعدادات استهداف معيّنة.

طلب HTTP

POST https://displayvideo.googleapis.com/v4/advertisers/{advertiserId}/reachForecast:generateReachForecast

يستخدم عنوان URL بنية تحويل الترميز إلى gRPC.

مَعلمات المسار

المعلمات
advertiserId

string (int64 format)

الحقل مطلوب. رقم تعريف المعلِن الذي سيُطلق الحملة المُخطّط لها.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

تمثيل JSON 
{
  "targeting": {
    object (Targeting)
  },
  "campaignDuration": {
    object (CampaignDuration)
  },
  "currencyCode": string,
  "plannedProducts": [
    {
      object (PlannedProduct)
    }
  ],
  "minEffectiveFrequency": integer
}
الحقول
targeting

object (Targeting)

الحقل مطلوب. معلَمات الاستهداف للحملة المخطّط لها
campaignDuration

object (CampaignDuration)

الحقل مطلوب. مدة الحملة المُخطّط لها
currencyCode

string

الحقل مطلوب. تمثّل هذه السمة رمز العملة للخطة بتنسيق ISO 4217.
plannedProducts[]

object (PlannedProduct)

الحقل مطلوب. قائمة البنود الإعلانية المطلوب تضمينها في التوقّع.
minEffectiveFrequency

integer

اختياريّ. الحدّ الأدنى الفعّال لعدد مرّات الظهور لمقاييس مدى الوصول المُبلغ عنها هذا هو الحدّ الأدنى لعدد المرّات التي يجب أن يرى فيها العميل الإعلان لكي يُعتبر فعّالاً. لا يؤثّر هذا الإعداد إلّا في إعداد التقارير.

يجب أن تتراوح القيمة بين 1 و10، بما في ذلك الرقمان. إذا لم يتم تحديد عدد، سيتم تطبيق القيمة التلقائية وهي 1.

نص الاستجابة

رسالة الردّ الخاصة بـ ReachForecastService.GenerateReachForecast

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "onTargetAudienceMetrics": {
    object (OnTargetAudienceMetrics)
  },
  "reachCurve": {
    object (ReachCurve)
  }
}
الحقول
onTargetAudienceMetrics

object (OnTargetAudienceMetrics)

أحجام الجمهور المقدَّرة للمنطقة الجغرافية المستهدَفة
reachCurve

object (ReachCurve)

منحنى التوقعات الذي تم إنشاؤه

نطاقات الأذونات

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/display-video

لمزيد من المعلومات، يُرجى الاطّلاع على OAuth 2.0 Overview.

الاستهداف

إعدادات الاستهداف لحملة مخطّط لها

تمثيل JSON 
{
  "plannableLocationIds": [
    string
  ],
  "ageRange": enum (PlannableAgeRange),
  "genders": [
    enum (Gender)
  ],
  "devices": [
    enum (DeviceType)
  ]
}
الحقول
plannableLocationIds[]

string (int64 format)

الحقل مطلوب. أرقام تعريف المواقع الجغرافية القابلة للتخطيط التي سيتم استهدافها

يمكن استرداد المواقع الجغرافية القابلة للتخطيط باستخدام طريقة reachForecast.retrievePlannableLocations.
ageRange

enum (PlannableAgeRange)

اختياريّ. الفئة العمرية المستهدَفة
genders[]

enum (Gender)

اختياريّ. خيارات الجنس المطلوب استهدافه.
devices[]

enum (DeviceType)

اختياريّ. الأجهزة التي سيتم استهدافها

CampaignDuration

مدة خطة الوصول

تمثيل JSON 
{

  // Union field duration can be only one of the following:
  "durationDays": integer,
  "dateRange": {
    object (DateRange)
  }
  // End of list of possible types for union field duration.
}
الحقول
حقل الربط duration اختيار مدة الحملة يمكن أن يكون التعليق duration إحدى القيم التالية فقط:
durationDays

integer

الحقل مطلوب. عدد الأيام التي تغطيها الخطة
dateRange

object (DateRange)

الحقل مطلوب. النطاق الزمني الذي تغطّيه الخطة

PlannedProduct

تمثّل هذه السمة إعدادات منتج معيّن في الخطة.

تمثيل JSON 
{
  "plannableProductCode": string,
  "budgetMicros": string,
  "advancedProductTargeting": {
    object (AdvancedProductTargeting)
  }
}
الحقول
plannableProductCode

string

الحقل مطلوب. رمز المنتج، مثل "حملة وصول الفيديو"
budgetMicros

string (int64 format)

الحقل مطلوب. تمثّل هذه السمة ميزانية هذا المنتج بوحدة Micro.
advancedProductTargeting

object (AdvancedProductTargeting)

اختياريّ. عمليات إلغاء اختيارية للاستهداف على مستوى البند الإعلاني

AdvancedProductTargeting

عمليات إلغاء الاستهدافات المحدّدة للمنتج

تمثيل JSON 
{
  "surfaceTargetingSettings": {
    object (SurfaceTargetingSettings)
  },
  "targetFrequency": {
    object (TargetFrequency)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "ageRange": enum (PlannableAgeRange),
  "genders": [
    enum (Gender)
  ],
  "devices": [
    enum (DeviceType)
  ],
  "userInterestIds": [
    string
  ],
  "userListIds": [
    string
  ],
  "youtubeSelectSettings": {
    object (YouTubeSelectSettings)
  },
  "dateRange": {
    object (DateRange)
  },
  "plannableLocationIds": [
    string
  ],
  "network": enum (PlannableNetwork)
}
الحقول
surfaceTargetingSettings

object (SurfaceTargetingSettings)

اختياريّ. مساحات العرض القابلة للتخطيط لاستهدافها
targetFrequency

object (TargetFrequency)

اختياريّ. متوسط عدد المرّات التي ستظهر فيها الإعلانات للمستخدِم نفسه خلال فترة زمنية معيّنة
frequencyCap

object (FrequencyCap)

اختياريّ. تمثّل هذه السمة الحدّ الأقصى لعدد مرات الظهور للمنتج المحدّد.
ageRange

enum (PlannableAgeRange)

اختياريّ. الفئة العمرية المستهدَفة
genders[]

enum (Gender)

اختياريّ. خيارات الجنس المطلوب استهدافه.
devices[]

enum (DeviceType)

اختياريّ. الأجهزة التي سيتم استهدافها
userInterestIds[]

string

اختياريّ. أرقام تعريف اهتمامات المستخدمين المطلوب استهدافهم.

يمكن استرداد اهتمامات المستخدمين القابلة للتخطيط باستخدام الطريقة reachForecast.retrievePlannableUserInterests.
userListIds[]

string

اختياريّ. معرّفات قوائم المستخدِمين المطلوب استهدافها.

يمكن استرداد قوائم المستخدمين القابلة للتخطيط باستخدام الطريقة reachForecast.retrievePlannableUserInterests.
youtubeSelectSettings

object (YouTubeSelectSettings)

اختياريّ. إعدادات YouTube Select
dateRange

object (DateRange)

اختياريّ. النطاق الزمني الذي تريد استهدافه.
plannableLocationIds[]

string (int64 format)

اختياريّ. أرقام تعريف المواقع الجغرافية القابلة للتخطيط التي يجب استهدافها.
network

enum (PlannableNetwork)

اختياريّ. الشبكة التي سيتم استهدافها

SurfaceTargetingSettings

اختيار استهداف السطح

تمثيل JSON 
{
  "surfaces": [
    enum (PlannableSurface)
  ]
}
الحقول
surfaces[]

enum (PlannableSurface)

اختياريّ. الأسطح المطلوب استهدافها.

YouTubeSelectSettings

إعدادات قوائم YouTube Select

تمثيل JSON 
{
  "lineupId": string
}
الحقول
lineupId

string (int64 format)

اختياريّ. رقم تعريف قائمة YouTube Select

OnTargetAudienceMetrics

أحجام الجمهور المقدّرة لموقع جغرافي مستهدَف

تمثيل JSON 
{
  "youtubeAudienceSize": string,
  "censusAudienceSize": string
}
الحقول
youtubeAudienceSize

string (int64 format)

حجم الجمهور المقدّر على YouTube
censusAudienceSize

string (int64 format)

حجم الجمهور استنادًا إلى بيانات الإحصاء السكاني للموقع الجغرافي المستهدَف

ReachCurve

منحنى مدى الوصول إلى الجمهور الذي تم إنشاؤه

تمثيل JSON 
{
  "reachForecasts": [
    {
      object (ReachForecast)
    }
  ]
}
الحقول
reachForecasts[]

object (ReachForecast)

نقاط على طول المنحنى، مرتّبة حسب التكلفة

ReachForecast

نقطة واحدة في منحنى الوصول

تمثيل JSON 
{
  "costMicros": string,
  "plannedProductReachForecasts": [
    {
      object (PlannedProductReachForecast)
    }
  ],
  "forecast": {
    object (PlannedProductForecast)
  }
}
الحقول
costMicros

string (int64 format)

إجمالي التكلفة لهذه النقطة بوحدة الميكرو.
plannedProductReachForecasts[]

object (PlannedProductReachForecast)

تفاصيل المنتجات الفردية في نقطة التكلفة هذه
forecast

object (PlannedProductForecast)

التوقّعات المجمّعة للخطة بأكملها

PlannedProductReachForecast

توقّعات الأداء لمنتج معيّن

تمثيل JSON 
{
  "costMicros": string,
  "plannableProductCode": string,
  "plannedProductForecast": {
    object (PlannedProductForecast)
  }
}
الحقول
costMicros

string (int64 format)

تمثّل هذه السمة تكلفة هذا المنتج بوحدة Micro.
plannableProductCode

string

تمثّل هذه السمة رمز المنتج.
plannedProductForecast

object (PlannedProductForecast)

مقاييس أداء المنتج

PlannedProductForecast

مقاييس الأداء لنقطة توقّع

تمثيل JSON 
{
  "onTargetReach": string,
  "onTargetImpressions": string,
  "trueviewViews": string,
  "totalReach": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string
}
الحقول
onTargetReach

string (int64 format)

عدد المستخدمين الفريدين الذين تم الوصول إليهم والذين يتطابقون مع تعريف الجمهور المستهدَف
onTargetImpressions

string (int64 format)

عدد مرّات الظهور المستهدَفة
trueviewViews

string (int64 format)

عدد مشاهدات إعلانات TrueView
totalReach

string (int64 format)

إجمالي عدد المستخدمين الفرديين الذين تم الوصول إليهم
totalImpressions

string (int64 format)

إجمالي عدد مرّات الظهور
viewableImpressions

string (int64 format)

عدد مرات الظهور القابلة للعرض.
onTargetCoviewReach

string (int64 format)

عدد المستخدمين الفرديين الذين تم الوصول إليهم والذين يستوفون تعريف الجمهور المستهدَف، بما في ذلك المشاركون في المشاهدة على الشاشة نفسها
totalCoviewReach

string (int64 format)

إجمالي عدد المستخدمين الفرديين الذين تم الوصول إليهم، بما في ذلك المشاركون في المشاهدة على الشاشة نفسها
onTargetCoviewImpressions

string (int64 format)

عدد مرّات الظهور المستهدَفة، بما في ذلك المشاهدون على الشاشة نفسها
totalCoviewImpressions

string (int64 format)

إجمالي عدد مرّات الظهور، بما في ذلك المستخدمون المشاركون في المشاهدة