استخدام Ad Placement API

تحتوي واجهة Ad Placement API على دالتَين: adBreak() وadConfig()، المعرّفتَين في مساحة الاسم العامة التالية. معظم الوسيطات هي دوال توفّرها وتتيح لك التعامل مع الخطوات الرئيسية الخاصة بالاستعداد لعرض إعلان:

adBreak({
   type: '<type>',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and un-mute the sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before completion
   adViewed: () => {},                  // Ad was viewed and closed
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

adConfig({
   preloadAdBreaks: 'on|auto',      // Should ads always be preloaded
   sound: 'on|off',                 // Is sound currently enabled within the game
});

تُستخدَم هذه الدوالّ لوضع الإعلانات وضبط إعداداتها داخل لعبتك. إنّ الوسيطات الموضّحة أعلاه هي الوسيطات الصالحة الوحيدة التي يمكن تمريرها إلى هذه الدوال. تتطلّب الأنواع المختلفة من الإعلانات مجموعات فرعية مختلفة من هذه الوسيطات كما هو موضّح أدناه.

adBreak() هي الوظيفة الأساسية لعرض الإعلانات داخل لعبتك. يحدّد هذا العنصر موضع إعلان ويستخدِم كائنًا يُعرف باسم إعدادات موضع الإعلان يحدّد كل ما هو مطلوب لعرض إعلان.

تحدّد الدالة adBreak() موضعًا يمكن عرض إعلان فيه. يعتمد ظهور الإعلان فعليًا على عوامل مثل ما يلي:

• نوع موضع الإعلان الذي أفصحت عنه
  • هل يظهر هذا الإعلان في بداية المباراة؟ بين المستويات؟ في لحظة أوقف فيها اللاعب اللعبة مؤقتًا؟
• ما إذا كان يتوفّر إعلان مناسب للاعب الحالي
  • هل هذا الإعلان مناسب لهم؟
  • هل يتوافق مع إعدادات الخصوصية والموافقة على استخدام البيانات؟
• عدد الإعلانات التي شاهدها اللاعب مؤخرًا
• إعدادات التحكّم، مثل معدّل تكرار الإعلانات، التي ضبطتها لهذه اللعبة
  • إما كملاحظات في العلامة، أو
  • ضمن AdSense، مع العلم أنّ عناصر التحكّم المتوفّرة في AdSense ستتطوّر بمرور الوقت.

يعتمد نوع الإعلان الذي يظهر أيضًا على عوامل مشابهة.

يُرجى العِلم أنّ الاتصال بـ adBreak() قد لا يعرض أي إعلان على الإطلاق. وهي ببساطة تحدّد موضعًا يمكن عرض الإعلان فيه.

ويختلف ذلك عن واجهات برمجة التطبيقات التقليدية التي يعرف فيها الرمز البرمجي دائمًا ما إذا كان الإعلان متاحًا، وتحدّد أنت داخل اللعبة ما إذا كنت تريد عرضه. يُشار إلى هذا الأسلوب الذي يتيح لواجهة برمجة التطبيقات Ad Placement API تحديد ما إذا كان سيتم عرض إعلان في موضع إعلان معيّن أم لا، باسم "انعكاس التحكّم".

السبب الأول الذي دفعنا إلى نقل واجهة برمجة التطبيقات الخاصة بالألعاب إلى هذا النموذج هو أنّها تقلّل من حجم الرمز الذي عليك كتابته في لعبتك. ثانيًا، يسهّل هذا الإجراء عرض مواضع إعلانات متوافقة مع السياسات وتقديم تجربة مستخدم رائعة، ما أتاح لنا عرض بعض من أفضل أشكال الإعلانات أداءً على ناشري الألعاب. أخيرًا، يفصل هذا النظام بشكل أفضل عملية عرض الإعلانات في لعبتك عن قرارات تحقيق الربح المتعلقة بنوع الإعلانات وعددها.

نريد أن نتيح لك تغيير إعدادات تحقيق الربح والتحكّم في تجربة المستخدم بدون الحاجة إلى تعديل إصدار جديد من لعبتك وإصداره، وذلك من خلال تحديد تلميحات في العلامة في البداية. ولكن في الإصدارات المستقبلية، سنتمكّن من توفير عناصر التحكّم مباشرةً في واجهات AdSense وAdMob.

الإعلانات البينية

الإعلان البيني هو إعلان بملء الشاشة يمكن عرضه في لحظات مختلفة داخل لعبتك، مثلاً عندما يبدأ اللاعب اللعبة أو بعد أن يكمل مستوى معيّنًا. يؤدي هذا النوع إلى إيقاف اللعبة مؤقتًا وتغطية المستند بأكمله، ويمكن للاعب النقر على الإعلان (وفي هذه الحالة، يظهر الإعلان في علامة تبويب مختلفة في المتصفّح) أو إغلاقه، ما يتيح له مواصلة اللعب.

ملاحظة: يمكن عرض إعلان بيني قبل أن يتم تحميل واجهة المستخدم في لعبتك. يُطلق على هذا النوع من الإعلانات اسم "إعلان ما قبل التشغيل"، ويجب التعامل معه بشكل مختلف قليلاً عن الإعلانات البينية العادية. مزيد من المعلومات حول الإعلانات قبل التشغيل

لعرض إعلان بيني، املأ الحقول التالية ضمن إعدادات موضع الإعلان:

adBreak({
   type: 'start',           // The type of this placement
   name: 'game_started',    // A descriptive name for this placement
   beforeAd: beforeAd,      // Prepare for the ad. Mute and pause the game flow
   afterAd: afterAd,        // Resume the game and un-mute the sound
   adBreakDone: breakDone,  // Always called (if provided) even if an ad didn't show
});

يجب توفير الوسيطة type، وننصحك دائمًا بتسمية مواضع الإعلانات. أما عمليات معاودة الاتصال الأخرى، فهي اختيارية.

تسلسل المكالمات

راجِع تسلسل المكالمات لعرض إعلان بيني.

الوصف

الإعلان البيني - تسلسل المكالمات التفصيلي
لعبة H5	Ad Placement API
	عملية التهيئة والتحميل المُسبَق للإعلانات
تشغيل اللعبة
فرصة جيدة لعرض إعلان... adBreak() ←
	يتوفّر إعلان والوقت مناسب لعرضه... ← beforeAd()
يتم إيقاف اللعبة مؤقتًا وكتم الصوت والاستعداد لعرض الإعلان. return إلى واجهة برمجة التطبيقات →
	تعرض "واجهة برمجة التطبيقات لموضع الإعلان" الإعلان البيني. يمكن للمشاهد النقر على الإعلان (الذي يظهر في علامة تبويب جديدة). ويجب إغلاق الإعلان لمواصلة اللعب.
	يتم استدعاء ← afterAd() في حال تم عرض إعلان
تتم إزالة الإيقاف المؤقت للعبة وإلغاء كتم الصوت.
	←يتم دائمًا استدعاء الدالة adBreakDone()adBreakDone() (حتى إذا لم يتم عرض إعلان)
تسجّل اللعبة إحصاءات حول موضع الإعلان هذا.

ملاحظات

• ‫adBreak() هي دالة غير متزامنة تعرض النتيجة على الفور.
• في حال عدم توفّر إعلان لعرضه في موضع إعلان، لن يتم استدعاء أي من دوالّ معاودة الاتصال، أي لن يتم استدعاء أي من beforeAd() أو afterAd().
• لضمان عدم استمرار تنفيذ لعبتك أثناء عرض الإعلان، استخدِم وظيفة beforeAd() للرجوع من أجل كتم الصوت وإيقاف اللعبة مؤقتًا.
• إذا كان beforeAd() متزامنًا، لن تعرض Ad Placement API إعلانًا إلى أن يتم إرجاعه.
• أعِد تشغيل اللعبة وأزِل كتم الصوت عند تلقّي مكالمة من afterAd().
• في حال توفيرها، يتم دائمًا استدعاء adBreakDone() حتى إذا لم يتم عرض إعلان في موضع الإعلان هذا.
• سيؤدي طلب adBreak() أثناء عرض إعلان آخر إلى حدوث خطأ وسيظهر تحذير في وحدة تحكّم JavaScript.

الإعلانات قبل عرض الفيديو

إعلان ما قبل التشغيل هو إعلان بيني يظهر قبل أن تحمّل لعبتك واجهة المستخدِم. وهي أول ما يراه اللاعب عند الانتقال إلى لعبتك. بما أنّ الإعلان التمهيدي يظهر في وقت مبكر جدًا من عملية تحميل الصفحة، ولا تكون لعبتك معروضة بعد، لن تحتاج إلى إجراء الطلبات المعتادة لإيقاف لعبتك مؤقتًا وكتم صوتها. بدلاً من ذلك، يمكنك استخدام وظيفة الاستدعاء adBreakDone() لتحديد تسلسل بدء لعبتك مع الإعلان، أي عرض واجهة المستخدم وبدء تشغيل الصوت. يمكن عرض إعلان تمهيدي واحد فقط عند تحميل كل صفحة.

تسلسل المكالمات

يتم طلب الإعلان التمهيدي في وقت مبكر جدًا من عملية تحميل الصفحة. بما أنّ لعبتك لم تعرض واجهة المستخدم في هذه المرحلة، يجب عدم تمرير عمليات معاودة الاتصال beforeAd() وafterAd(). بدلاً من ذلك، استخدِم وظيفة الاستدعاء adBreakDone() لبدء لعبتك بعد موضع الإعلان، لأنّه من المؤكّد أنّه سيتم استدعاء هذه الوظيفة حتى إذا لم يكن هناك إعلان.

سيؤدي طلب الرمز التالي، في وقت مبكر من منطق لعبتك، إلى عرض إعلان فيديو أثناء الإحماء. يجب عدم عرض واجهة المستخدم قبل استدعاء هذا الرمز.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})

الإعلان التمهيدي – تسلسل المكالمات التفصيلي
لعبة H5	Ad Placement API
	بدء عملية إعداد واجهة برمجة التطبيقات والتخزين المؤقّت المسبق للإعلانات
قيد التشغيل ولكن لم يبدأ ولم يعرض واجهة مستخدم
adBreak(type:'preroll',…) ←
	تنتهي واجهة برمجة التطبيقات لموضع الإعلان من عملية الإعداد وتحميل الإعلانات. إذا كان هناك إعلان، يتم عرضه. يمكن للاعب النقر على الإعلان (الذي يظهر في علامة تبويب جديدة). ويجب إغلاقها لبدء اللعبة.
	← يتم دائمًا طلب adBreakDone() (حتى إذا لم يتم عرض إعلان)
يتم عرض واجهة مستخدم اللعبة على الشاشة ويمكن للاعب الآن التفاعل معها. يمكن للعبة استخدام العنصر placementInfo الذي تم تمريره إلى adBreakDone() حسب الحاجة (على سبيل المثال، لتسجيل إحصاءات إضافية).

ملاحظات

• ستحاول إعلانات ما قبل التشغيل دائمًا التحميل المُسبَق للإعلانات:
  • لا يُشترَط الاتصال بالرقم adConfig(preloadAds: ‘on') عند استخدام الإعلانات التمهيدية.
• وكما هو الحال مع مواضع الإعلان الأخرى، قد يعرض الإعلان ما قبل التشغيل إعلانًا أو لا يعرضه.
• يجب عدم تمرير beforeAd() وafterAd() إلى إعلان ما قبل التشغيل.
  • بما أنّ "الإعلانات قبل التشغيل" يتم عرضها قبل بدء لعبتك، ليس عليك إيقاف صوت اللعبة مؤقتًا أو كتمه.
  • إذا مرّرت beforeAd() أو afterAd() مع إعلان ما قبل التشغيل، سيتعذّر تنفيذ الطلب وسيتم تسجيل خطأ في وحدة تحكّم JavaScript.
• ينتظر إعلان ما قبل التشغيل تلقائيًا إلى أن يتم تهيئة واجهة برمجة التطبيقات لموضع الإعلان وتحميل الإعلانات مسبقًا:
  • ومع ذلك، هناك مهلة (ثانيتان) تمنع تأخير المكالمة إلى أجل غير مسمى. يضمن ذلك استدعاء adBreakDone() في الوقت المناسب وبدء لعبتك.
  • يتم طلب adBreakDone() دائمًا حتى إذا لم يكن هناك إعلان.
• ننصحك باستخدام إعلان ما قبل التشغيل لعرض الإعلانات قبل بدء لعبتك.
  • بدلاً من ذلك، يمكنك استخدام عملية الاسترجاع onReady() إلى adConfig() كآلية لتسلسل منطق لعبتك مع عملية تهيئة واجهة برمجة التطبيقات وتحميل الإعلانات مسبقًا.

الإعلانات مقابل مكافأة

يسمح لك "الإعلان مقابل مكافأة" بمكافأة اللاعبين بعناصر داخل التطبيق إذا اختاروا مشاهدة إعلان. في المقابل، تكون الإعلانات البينية قابلة للإيقاف، إذ يظهر الإعلان للمشغّل ويمكنه اختيار إغلاقه. تتطلّب "الإعلانات مقابل مكافأة" الموافقة. يختار اللاعب ما إذا كان يريد مشاهدة إعلان مقابل مكافأة ومتى يريد ذلك.

وعلى عكس الإعلانات البينية التي يمكن للمشغّل إغلاقها في أي وقت، يجب مشاهدة الإعلان لمدة زمنية محددة (قد تختلف حسب تصميم الإعلان المعروض) من أجل الحصول على مكافأة.

بما أنّ "الإعلانات مقابل مكافآت" اختيارية بالنسبة إلى اللاعب، فإنّها تتطلّب دمجًا أعمق في مسار لعبتك. يجب توفير وظائف لعرض طلب مكافأة داخل لعبتك، ولتخصيص المكافأة للاعب إذا شاهد الإعلان.

يجب ألا تكون للمكافآت قيمة خارج تطبيقك، ويجب ألا تكون لها قيمة نقدية (أو يمكن استبدالها بسهولة بقيمة نقدية)، ويجب ألا تكون قابلة للبيع أو الاستبدال بسلع وخدمات، ويجب ألا تشجّع اللاعبين على النقر على الإعلانات. يُرجى الرجوع إلى مسودة السياسة بشأن الإعلانات البينية والإعلانات مقابل مكافآت لمعرفة مزيد من التفاصيل.

بما أنّ المكافآت اختيارية بالنسبة إلى اللاعب، يمكنك إضافتها في أي مكان مناسب في لعبتك، ويمكنك استخدامها بالإضافة إلى الإعلانات البينية. مثل "الإعلانات البينية"، تشكّل مواضع الإعلانات هذه فرصًا لعرض "الإعلانات مقابل مكافآت". لن تستدعي واجهة Ad Placement API الرمز إلا إذا كان سيتم فعليًا تقديم إعلان مقابل مكافأة في نقطة معيّنة في لعبتك.

والهدف هنا هو السماح لك بدمج لعبتك مع واجهة برمجة التطبيقات AdPlacement API مرة واحدة، ثم يمكنك بمرور الوقت استخدام عناصر التحكّم إما في العلامة أو في AdSense لتغيير المزيج الدقيق من الإعلانات التي يتم تفعيلها، وذلك بدون الحاجة إلى إعادة ترميز لعبتك وإعادة إصدارها.

يكون نوع موضع الإعلان مقابل مكافأة دائمًا 'reward' ويمكن استخدام جميع الحقول في إعدادات موضع الإعلان.

adBreak({
   type: 'reward',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and re-enable sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before it finished.
   adViewed: () => {},                  // Player watched the ad–give them the reward.
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

الدالتان الجديدتان الرئيسيتان هما beforeReward()، وهي المشغّل الذي يشير إلى أنّه عليك عرض طلب المكافأة، وadViewed()، ويتم استدعاؤها عندما يشاهد اللاعب الإعلان بنجاح، ما يتيح لك منح المكافأة.

يمكنك تحديد موضع إعلان مقابل مكافأة على النحو التالي:

adBreak({
   type: 'reward',
   name: 'new_life_reward_1',
   beforeAd: pauseGame,
   afterAd: restartGame,
   beforeReward: showRewardPrompt,
   adDismissed: adDismissed,
   adViewed: adViewed,
   adBreakDone: breakDone,
});

تبدأ "الإعلانات مقابل مكافأة" بطلب في لعبتك يعرض على اللاعب مكافأة إذا شاهد إعلانًا.

تسلسل طلب عرض إعلان مقابل مكافأة

الوصف

الإعلان مقابل مكافأة – تسلسل المكالمات التفصيلي
لعبة H5	Ad Placement API
	بدء الإعلانات وتخزينها مؤقتًا مسبقًا
تشغيل اللعبة
adBreak(type:'reward', ... ) ←
	يتوفّر إعلان، لذا ابدأ موضع "إعلان مقابل مكافأة". يتم استدعاء beforeReward() بشكل متزامن، أي مباشرةً بعد استدعاء adBreak() ← beforeReward(showAdFn)
تعرض اللعبة طلب الحصول على المكافأة. تتيح هذه الإعلانات للاعبين فرصة الحصول على مكافأة مقابل مشاهدة إعلان. يمكن تقديم أكثر من نوع واحد من المكافآت (على سبيل المثال، محاولة لعب جديدة أو عملة ذهبية). يمكن للاعب النقر على طلب الحصول على مكافأة أو إغلاقه أو تجاهله ببساطة. إذا نقر اللاعب على طلب، تخزّن اللعبة نوع المكافأة التي طلبها وتستدعي showAdFn().... بخلاف ذلك، إذا تم إغلاق طلب المكافأة أو تجاهله، لن يحدث أي شيء إلى أن تجري مكالمة أخرى إلى adBreak() باستخدام نوع موضع مكافأة، وعندها ستتم إعادة ضبط واجهة برمجة التطبيقات Ad Placement API وتنظيف الحالة من هذه المكالمة. إذا كان التطبيق يستدعي showAdFn من فاصل إعلاني سابق، لن يكون لذلك أي تأثير.
showAdFn() ←
	← beforeAd()
تتوقف اللعبة مؤقتًا ويتم كتم الصوت وتجهيز الإعلان للعرض return إلى واجهة برمجة التطبيقات →
	تعرض واجهة برمجة التطبيقات الإعلان. ويحتوي على زر إغلاق وعدّ تنازلي للمدة المتبقية من الإعلان.
في حال أغلق المشغّل الإعلان...
	← adDismissed()
أغلق اللاعب الإعلان ولم تقدّم اللعبة المكافأة.
بخلاف ذلك، يشاهد اللاعب الإعلان إلى نهايته...
	← adViewed()
شاهد اللاعب الإعلان إلى نهايته وحصل على المكافأة من اللعبة. (يتم ذلك عادةً من خلال ضبط بعض حالات اللعبة التي يتم استردادها عند إعادة تشغيل اللعبة باستخدام طلب afterAd() أدناه).
بعد مشاهدة الإعلان أو إغلاقه...
	← يتم استدعاء afterAd() إذا تم عرض إعلان
تتم إزالة الإيقاف المؤقت للعبة وإلغاء كتم الصوت.
	←يتم دائمًا استدعاء الدالة adBreakDone()adBreakDone() (حتى إذا لم يتم عرض إعلان)
تسجّل اللعبة إحصاءات حول موضع الإعلان هذا.

ملاحظات

• ‫adBreak() هي دالة غير متزامنة تعرض النتيجة على الفور.
• في حال عدم توفّر إعلان لعرضه في موضع الإعلان، لن يتم استدعاء أي من دوال الرجوع، أي لن يتم استدعاء أي من beforeAd() أو beforeReward().
• لضمان عدم استمرار تنفيذ لعبتك أثناء عرض الإعلان، استخدِم وظيفة beforeAd() للرجوع من أجل كتم الصوت وإيقاف اللعبة مؤقتًا.
• إذا كان beforeAd() متزامنًا، لن تعرض Ad Placement API إعلانًا إلى أن يتم إرجاعه.
• أعِد تشغيل اللعبة وأزِل كتم الصوت عند تلقّي مكالمة من afterAd().
• في حال توفيرها، يتم دائمًا استدعاء adBreakDone() حتى إذا لم يتم عرض إعلان في موضع الإعلان هذا.
• سيؤدي طلب adBreak() أثناء عرض إعلان آخر إلى حدوث خطأ وسيظهر تحذير في وحدة تحكّم JavaScript.