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 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "durationDays": integer,
  "dateRange": {
    object (DateRange)
  }
  // End of mutually exclusive fields.
}
الحقول
اختيار مدة الحملة في ما يلي قائمة بالحقول التي يستبعد كلّ منها الآخر. سيتم ضبط حقل واحد على الأكثر في الرد:
durationDays

integer

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

object (DateRange)

الحقل مطلوب. النطاق الزمني الذي تغطّيه الخطة
نهاية الحقول التي يستبعد كلّ منها الآخر

PlannedProduct

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

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

string

الحقل مطلوب. رمز المنتج، مثل "VIDEO_REACH_CAMPAIGN".
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)

إجمالي التكلفة لهذه النقطة بوحدة Micro
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)

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