- طلب HTTP
- مَعلمات المسار
- نص الطلب
- نص الاستجابة
- نطاقات التفويض
- CampaignDuration
- FrequencyCap
- EffectiveFrequencyLimit
- الاستهداف
- AudienceTargeting
- PlannedProduct
- AdvancedProductTargeting
- YouTubeSelectSettings
- ForecastMetricOptions
- OnTargetAudienceMetrics
- ReachCurve
- ReachForecast
- توقّعات الطقس
- EffectiveFrequencyBreakdown
- PlannedProductReachForecast
- PlannedProductForecast
- جرِّبه الآن
تنشئ توقعات مدى الوصول لاستهداف مجموعة منتجات / استهداف معيّنة.
قائمة الأخطاء الملموسة: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError
طلب HTTP
POST https://googleads.googleapis.com/v14/customers/{customerId}:generateReachForecast
يستخدم عنوان URL بنية تحويل الترميز gRPC.
معلمات المسار
المَعلمات | |
---|---|
customerId |
مطلوبة. رقم تعريف العميل. |
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "campaignDuration": { object ( |
الحقول | |
---|---|
campaignDuration |
مطلوبة. مدة الحملة. |
cookieFrequencyCapSetting |
الحدّ الأقصى المحدّد لعدد مرات ظهور ملفات تعريف الارتباط والذي سيتم تطبيقه على كل منتج مخطط له يعادل هذا تحديد عدد مرات الظهور الذي يتم عرضه في "إعلانات Google" عند إنشاء حملة، كما أنه يمثل الحد الأقصى لعدد المرات التي يمكن فيها عرض الإعلان للمستخدم نفسه خلال فترة زمنية محددة. وإذا لم يتم تحديده، يتم تطبيق القيمة التلقائية 0 (بدون حد أقصى). يحل هذا الحقل محل الحقلcookieFrequencyCap المتوقف نهائيًا. |
targeting |
الاستهداف الذي سيتم تطبيقه على كل المنتجات المختارة في تشكيلة المنتجات هذا استهداف مخطط له: قد تختلف تفاصيل التنفيذ حسب المنتج الإعلاني، لذا استشِر أحد خبراء التنفيذ. يمكنك الاطّلاع على مقاييس معيّنة لمعرفة تفاصيل عن كيفية تأثير الاستهداف فيها. |
plannedProducts[] |
مطلوبة. المنتجات المطلوب توقّعها الحدّ الأقصى لعدد المنتجات المخطّط لها مسموح به هو 15. |
forecastMetricOptions |
تتحكّم هذه السياسة في مقاييس التوقّعات التي يتم عرضها في الردّ. |
currencyCode |
تمثّل هذه السمة رمز العملة. رمز عملة مكوَّن من ثلاثة أحرف وفقًا لمعيار ISO 4217. |
cookieFrequencyCap |
الحدّ الأقصى المحدّد لعدد مرات ظهور ملفات تعريف الارتباط والذي سيتم تطبيقه على كل منتج مخطط له يعادل هذا تحديد عدد مرات الظهور الذي يتم عرضه في "إعلانات Google" عند إنشاء حملة، كما أنه يمثل الحد الأقصى لعدد مرات عرض الإعلان للمستخدم نفسه. وإذا لم يتم تحديده، لن يتم تطبيق أي حد أقصى. تم إيقاف هذا الحقل نهائيًا في الإصدار 4 وستتم إزالته في النهاية. يُرجى استخدام ملف تعريف الارتباط KeyFrequencyCapإعداد بدلاً من ذلك. |
minEffectiveFrequency |
تم اختيار الحدّ الأدنى الفعّال لمعدل التكرار (عدد المرات التي شاهد فيها أحد الأشخاص الإعلان) لمقاييس مدى الوصول المسجّلة [1-10]. لن يؤثّر هذا في الاستهداف، بل على التقارير فقط. وإذا لم يتم تحديده، يتم تطبيق القيمة التلقائية 1. لا يمكن دمج هذا الحقل مع الحقل effectiveFrequencyالحدّ. |
effectiveFrequencyLimit |
قيمة الحد الأدنى الفعّال لمعدل التكرار (عدد مرات ظهور الإعلان على أحد الأشخاص) [من 1 إلى 10] لتضمينها في Forecast.effective_frequency_breakdowns. في حال عدم تحديد هذه السمة، لن يتم تقديم Forecast.effective_frequency_breakdowns. سيتم أيضًا استخدام قيمة عدد مرّات الظهور الفعّالة المقدَّمة هنا باعتبارها الحدّ الأدنى لعدد مرّات الظهور الفعّالة لمقاييس مدى الوصول التي يتم الإبلاغ عنها. لا يمكن دمج هذا الحقل مع الحقل minفعالFrequency. |
customerReachGroup |
اسم العميل الذي يتم التخطيط له. هذه قيمة من تحديد المستخدم. |
نص الاستجابة
رسالة رد تحتوي على منحنى مدى الوصول الذي تم إنشاؤه
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "onTargetAudienceMetrics": { object ( |
الحقول | |
---|---|
onTargetAudienceMetrics |
مرجع عن الجماهير المستهدفة لهذا المنحنى. |
reachCurve |
منحنى مدى الوصول الذي تم إنشاؤه لمجموعة المنتجات المخطّط لها |
نطاقات التفويض
يجب توفير نطاق OAuth التالي:
https://www.googleapis.com/auth/adwords
لمزيد من المعلومات، راجِع نظرة عامة على بروتوكول OAuth 2.0.
CampaignDuration
مدة الحملة المخطط لها.
تمثيل JSON |
---|
{
"dateRange": {
object ( |
الحقول | |
---|---|
dateRange |
النطاق الزمني للحملة. يتم كتابة التواريخ بالتنسيق yyyy-mm-dd وتكون شاملة. يجب أن يكون تاريخ الانتهاء أقل من سنة واحدة في المستقبل، ويجب أن يكون النطاق الزمني أقل من = 92 يومًا. لا يمكن دمج هذا الحقل مع الحقل durationInDays. |
durationInDays |
قيمة المدة بالأيام. لا يمكن دمج هذا الحقل مع حقل نطاق التاريخ. |
FrequencyCap
يشير ذلك المصطلح إلى قاعدة تحدّد الحد الأقصى لعدد مرات عرض الإعلان على المستخدم خلال فترة زمنية معيّنة.
تمثيل JSON |
---|
{
"impressions": integer,
"timeUnit": enum ( |
الحقول | |
---|---|
impressions |
مطلوبة. عدد مرات الظهور، بشكل شامل. |
timeUnit |
مطلوبة. نوع الوحدة الزمنية. |
EffectiveFrequencyLimit
الحدّ الأقصى الفعّال لمعدّل التكرار
تمثيل JSON |
---|
{ "effectiveFrequencyBreakdownLimit": integer } |
الحقول | |
---|---|
effectiveFrequencyBreakdownLimit |
أعلى قيمة معدل تكرار فعّالة يجب تضمينها في Forecast.effective_frequency_breakdowns. يدعم هذا الحقل الترددات من 1 إلى 10 بشكل شامل. |
الاستهداف
الاستهداف الذي سيتم إعداد تقارير مقاييس الزيارات له.
تمثيل JSON |
---|
{ "plannableLocationIds": [ string ], "ageRange": enum ( |
الحقول | |
---|---|
plannableLocationIds[] |
قائمة بأرقام تعريف المواقع الجغرافية القابلة للتخطيط المراد استهدافها باستخدام هذه التوقعات. وفي حال تقديم أكثر من معرّف واحد، يجب أن تحتوي جميع المعرّفات على السمة يجب أن تضبط الطلبات هذا الحقل أو على |
ageRange |
الفئة العمرية المستهدفة. إنّ القيمة التي لم يتم ضبطها تساوي استهداف جميع الأعمار. |
genders[] |
الأجناس المستهدفة. تساوى القيمة التي تم تركها بدون ضبط لاستهداف الذكور وFEMALE. |
devices[] |
الأجهزة المستهدفة. في حال عدم تحديد أي خيار، يتم استهداف جميع الأجهزة السارية. تختلف الأجهزة السارية حسب المنتج والمنطقة، ويمكن الحصول عليها من " |
network |
شبكة قابلة للاستهداف للمنتج الإعلاني في حال عدم تحديد أي خيار، يمكنك استهداف جميع الشبكات السارية. تختلف الشبكات المتوفّرة حسب المنتج والمنطقة، ويمكن الحصول عليها من " |
audienceTargeting |
الجماهير المستهدفة. في حال عدم تحديد نوع الحملة، لن يتم استهداف أي جمهور محدَّد. |
plannableLocationId |
رقم تعريف الموقع الجغرافي المحدّد. يمكن الحصول على أرقام تعريف المواقع الجغرافية القابلة للتخطيط من يجب أن تضبط الطلبات هذا الحقل أو على تم إيقاف هذا الحقل نهائيًا اعتبارًا من الإصدار 12، وستتم إزالته في إصدار مستقبلي. يمكنك استخدام |
AudienceTargeting
استهداف الجمهور لتوقّعات مدى الوصول
تمثيل JSON |
---|
{
"userInterest": [
{
object ( |
الحقول | |
---|---|
userInterest[] |
قائمة الجماهير المطلوب استهدافها استنادًا إلى اهتمامات المستخدمين. |
PlannedProduct
المنتج الذي يتم التخطيط للوصول إليه.
تمثيل JSON |
---|
{
"advancedProductTargeting": {
object ( |
الحقول | |
---|---|
advancedProductTargeting |
إعدادات الاستهداف للمنتج المحدّد. لإدراج الاستهداف المتاح لكل منتج، استخدِم |
plannableProductCode |
مطلوبة. المنتج الذي تم اختياره للتخطيط. الرمز المرتبط بمنتج الإعلان (مثل: Trueview، والملصقات الصغيرة). لإدراج رموز المنتجات القابلة للتخطيط، استخدِم |
budgetMicros |
مطلوبة. الحد الأقصى لتخصيص الميزانية بالمايكرو للمنتج المحدّد. يتم تحديد القيمة في رمز عملة التخطيط المحدّد. على سبيل المثال: 1 000 000$ = 1 000 000 000 000 ميكرو. |
AdvancedProductTargeting
إعدادات الاستهداف المتقدمة للمنتجات.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الاتحاد advanced_targeting خيارات الاستهداف لهذا المنتج. يمكن أن يكون الحقل "advanced_targeting " واحدًا فقط مما يلي: |
|
youtubeSelectSettings |
إعدادات استهداف YouTube Select |
YouTubeSelectSettings
طلب إعدادات قوائم YouTube Select
تمثيل JSON |
---|
{ "lineupId": string } |
الحقول | |
---|---|
lineupId |
قائمة "استهداف YouTube Select". |
ForecastMetricOptions
تتحكّم هذه السياسة في مقاييس التوقّعات المعروضة.
تمثيل JSON |
---|
{ "includeCoview": boolean } |
الحقول | |
---|---|
includeCoview |
يشير إلى ما إذا كان سيتم تضمين مقاييس المشاهدة على الشاشة نفسها في توقّعات الاستجابة. |
OnTargetAudienceMetrics
مقاييس الجمهور للمنتجات المخطّط لها وتراعي هذه المقاييس سمات الاستهداف التالية:
- الموقع الجغرافي
- PlannableAgeRange
- الجنس
- استهداف الجمهور (لجمهور youtubeCustomerSize فقط)
تمثيل JSON |
---|
{ "youtubeAudienceSize": string, "censusAudienceSize": string } |
الحقول | |
---|---|
youtubeAudienceSize |
يُرجى الإشارة إلى حجم الجمهور الذي يتطابق مع الاستهداف المعني على YouTube. |
censusAudienceSize |
يُرجى الإشارة إلى حجم الجمهور الذي يتطابق مع الاستهداف المعني للإحصاء السكاني. |
ReachCurve
منحنى مدى الوصول إلى الجمهور للمنتجات المُخطَّط لها
تمثيل JSON |
---|
{
"reachForecasts": [
{
object ( |
الحقول | |
---|---|
reachForecasts[] |
جميع النقاط على منحنى مدى الوصول إلى الجمهور |
ReachForecast
نقطة على منحنى مدى الوصول
تمثيل JSON |
---|
{ "costMicros": string, "forecast": { object ( |
الحقول | |
---|---|
costMicros |
تشير هذه السمة إلى التكلفة بالمايكرو. |
forecast |
مقاييس الزيارات المتوقّعة لهذه النقطة |
plannedProductReachForecasts[] |
مقاييس التخصيص وعدد الزيارات المتوقّعة لكل منتج مخطَّط له عند هذه النقطة في منحنى مدى الوصول إلى الجمهور. |
التوقعات
مقاييس الزيارات المتوقّعة للمنتجات والاستهداف المخطّط له.
تمثيل JSON |
---|
{
"effectiveFrequencyBreakdowns": [
{
object ( |
الحقول | |
---|---|
effectiveFrequencyBreakdowns[] |
قائمة بتوقّعات مرّات الظهور الفعّالة يتم ترتيب القائمة بدءًا من 1 أو أكثر وتنتهي بالقيمة التي تم ضبطها في generateReachForecastRequest.effective_frequency_limit. وستكون هذه القائمة فارغة في حال عدم تحديد فعالةعدد مرات الظهور. |
onTargetReach |
عدد الأشخاص الفريدين الذين تم الوصول إليهم على الأقل في إحصاءات GenerateReachForecastRequest.min_effective_frequency أو مرات GenerateReachForecastRequest.effective_frequency_limit التي تتطابق تمامًا مع الاستهداف. تجدر الإشارة إلى أنّه يجب الوصول إلى حدّ أدنى من الأشخاص الفريدين كي يتمّ إعداد تقارير عن البيانات. وإذا لم يتم استيفاء الحد الأدنى للعدد، سيتم تقريب قيمة onTargetReach إلى 0. |
totalReach |
إجمالي عدد الأشخاص الفريدين الذين تم الوصول إليهم بحدّ أدنى من خلال أوقات GenerateReachForecastRequest.min_effective_frequency أو GenerateReachStartRequest.effective_frequency_limit. ويشمل ذلك الأشخاص الذين قد لا يندرجون ضمن نطاق الاستهداف المحدّد. تجدر الإشارة إلى أنّه يجب الوصول إلى حدّ أدنى من الأشخاص الفريدين كي يتمّ إعداد تقارير عن البيانات. إذا لم يتم استيفاء الحد الأدنى للعدد، سيتم تقريب قيمة total Reach إلى 0. |
onTargetImpressions |
عدد مرات ظهور الإعلان التي تتطابق تمامًا مع الاستهداف. |
totalImpressions |
إجمالي عدد مرات ظهور الإعلان. يشمل ذلك مرات الظهور التي قد تقع خارج نطاق الاستهداف المحدّد بسبب عدم كفاية المعلومات عن المستخدمين الذين سجّلوا الدخول. |
viewableImpressions |
عدد المرات التي تم فيها اعتبار مرات ظهور الإعلان قابلة للعرض. يمكنك الاطّلاع على https://support.google.com/google-ads/answer/7029393 للحصول على مزيد من المعلومات حول العوامل التي تجعل الإعلان قابلاً للعرض وكيفية قياس إمكانية العرض. |
onTargetCoviewReach |
عدد الأشخاص الفريدين الذين تم الوصول إليهم يتطابقون تمامًا مع الاستهداف، بما في ذلك المشاهدين على الشاشة نفسها |
totalCoviewReach |
عدد الأشخاص الفريدين الذين تم الوصول إليهم، بما في ذلك المشاهدين على الشاشة نفسها ويشمل ذلك الأشخاص الذين قد لا يندرجون ضمن نطاق الاستهداف المحدّد. |
onTargetCoviewImpressions |
عدد مرات ظهور الإعلان التي تتطابق تمامًا مع الاستهداف، بما في ذلك المشاهدين على الشاشة نفسها |
totalCoviewImpressions |
إجمالي عدد مرات ظهور الإعلان بما في ذلك المشاهدين على الشاشة نفسها يشمل ذلك مرات الظهور التي قد تقع خارج نطاق الاستهداف المحدّد بسبب عدم كفاية المعلومات عن المستخدمين الذين سجّلوا الدخول. |
EffectiveFrequencyBreakdown
تحليل لعدد المستخدمين الفرديين الذين تم الوصول إليهم بمعدّل تكرار فعّال معيّن
تمثيل JSON |
---|
{ "effectiveFrequency": integer, "onTargetReach": string, "totalReach": string, "effectiveCoviewReach": string, "onTargetEffectiveCoviewReach": string } |
الحقول | |
---|---|
effectiveFrequency |
معدّل التكرار الفعّال [1-10] |
onTargetReach |
عدد الأشخاص الفريدين الذين وصلوا إلى معدّل تكرار فعّال على الأقل يتطابق تمامًا مع الاستهداف. تجدر الإشارة إلى أنّه يجب الوصول إلى حدّ أدنى من الأشخاص الفريدين كي يتمّ إعداد تقارير عن البيانات. وإذا لم يتم استيفاء الحد الأدنى للعدد، سيتم تقريب قيمة onTargetReach إلى 0. |
totalReach |
إجمالي عدد الأشخاص الفريدين الذين تم الوصول إليهم على الأقل من مرّات التكرار الفعّالة ويشمل ذلك الأشخاص الذين قد لا يندرجون ضمن نطاق الاستهداف المحدّد. تجدر الإشارة إلى أنّه يجب الوصول إلى حدّ أدنى من الأشخاص الفريدين كي يتمّ إعداد تقارير عن البيانات. إذا لم يتم استيفاء الحد الأدنى للعدد، سيتم تقريب قيمة total Reach إلى 0. |
effectiveCoviewReach |
عدد المستخدمين (بما في ذلك المستخدمون الذين يشاهدون المحتوى على الشاشة نفسها) الذين تم الوصول إليهم بالنسبة إلى قيمة فعالة التكرار المرتبطة. |
onTargetEffectiveCoviewReach |
عدد المستخدمين (بما في ذلك المستخدمون الذين يشاهدون المحتوى على الشاشة نفسها) الذين تم الوصول إليهم بالنسبة إلى قيمة فعالة التكرار المرتبطة ضمن الفئة الديمغرافية المحدّدة للخطة. |
PlannedProductReachForecast
مقاييس التخصيص وعدد الزيارات المتوقّعة لمنتج معيّن في نقطة على منحنى مدى الوصول إلى الجمهور.
تمثيل JSON |
---|
{
"plannableProductCode": string,
"costMicros": string,
"plannedProductForecast": {
object ( |
الحقول | |
---|---|
plannableProductCode |
المنتج الذي تم اختياره للتخطيط. وتكون رموز المنتجات المعروضة ضمن مجموعة الرموز التي تعرضها ListPlannableProducts عند استخدام معرّف الموقع الجغرافي نفسه. |
costMicros |
تشير هذه السمة إلى التكلفة بالمايكرو. قد يختلف هذا المبلغ عن تخصيص مدخلات المنتج إذا لم يتمكّن منتج واحد أو أكثر من المنتجات المخطّط لها من استيفاء الميزانية المطلوبة بسبب محدودية المستودع. |
plannedProductForecast |
مقاييس الزيارات المتوقّعة لهذا المنتج |
PlannedProductForecast
مقاييس الزيارات المتوقّعة لمنتج مخطط له
تمثيل JSON |
---|
{ "onTargetReach": string, "totalReach": string, "onTargetImpressions": string, "totalImpressions": string, "viewableImpressions": string, "onTargetCoviewReach": string, "totalCoviewReach": string, "onTargetCoviewImpressions": string, "totalCoviewImpressions": string } |
الحقول | |
---|---|
onTargetReach |
عدد الأشخاص الفريدين الذين تم الوصول إليهم يتطابقون تمامًا مع الاستهداف. تجدر الإشارة إلى أنّه يجب الوصول إلى حدّ أدنى من الأشخاص الفريدين كي يتمّ إعداد تقارير عن البيانات. وإذا لم يتم استيفاء الحد الأدنى للعدد، سيتم تقريب قيمة onTargetReach إلى 0. |
totalReach |
عدد الأشخاص الفريدين الذين تم الوصول إليهم. ويشمل ذلك الأشخاص الذين قد لا يندرجون ضمن نطاق الاستهداف المحدّد. تجدر الإشارة إلى أنّه يجب الوصول إلى حدّ أدنى من الأشخاص الفريدين كي يتمّ إعداد تقارير عن البيانات. إذا لم يتم استيفاء الحد الأدنى للعدد، سيتم تقريب قيمة total Reach إلى 0. |
onTargetImpressions |
عدد مرات ظهور الإعلان التي تتطابق تمامًا مع الاستهداف. |
totalImpressions |
إجمالي عدد مرات ظهور الإعلان. يشمل ذلك مرات الظهور التي قد تقع خارج نطاق الاستهداف المحدّد بسبب عدم كفاية المعلومات عن المستخدمين الذين سجّلوا الدخول. |
viewableImpressions |
عدد المرات التي تم فيها اعتبار مرات ظهور الإعلان قابلة للعرض. يمكنك الاطّلاع على https://support.google.com/google-ads/answer/7029393 للحصول على مزيد من المعلومات حول العوامل التي تجعل الإعلان قابلاً للعرض وكيفية قياس إمكانية العرض. |
onTargetCoviewReach |
عدد الأشخاص الفريدين الذين تم الوصول إليهم يتطابقون تمامًا مع الاستهداف، بما في ذلك المشاهدين على الشاشة نفسها |
totalCoviewReach |
عدد الأشخاص الفريدين الذين تم الوصول إليهم، بما في ذلك المشاهدين على الشاشة نفسها ويشمل ذلك الأشخاص الذين قد لا يندرجون ضمن نطاق الاستهداف المحدّد. |
onTargetCoviewImpressions |
عدد مرات ظهور الإعلان التي تتطابق تمامًا مع الاستهداف، بما في ذلك المشاهدين على الشاشة نفسها |
totalCoviewImpressions |
إجمالي عدد مرات ظهور الإعلان بما في ذلك المشاهدين على الشاشة نفسها يشمل ذلك مرات الظهور التي قد تقع خارج نطاق الاستهداف المحدّد بسبب عدم كفاية المعلومات عن المستخدمين الذين سجّلوا الدخول. |