adBreak()

توقيع الدالة:

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 re-enable 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
);

مَعلمات adBreak()‎

الاسم	النوع	الوصف
جميع أنواع مواضع الإعلانات
type	سلسلة	نوع موضع الإعلان القيم: ‫'preroll' قبل تحميل اللعبة (قبل عرض واجهة المستخدم) ‫'start' قبل بدء اللعب (بعد عرض واجهة المستخدم) 'pause' أن يوقف اللاعب اللعبة مؤقتًا 'next' ينتقل اللاعب إلى المستوى التالي 'browse' يستكشف اللاعب خيارات خارج نطاق أسلوب اللعب 'reward' إعلان مقابل مكافأة
name	سلسلة	(اختياري) اسم موضع الإعلان هذا داخل لعبتك. وهو معرّف داخلي لا يظهر للاعب. في الإصدارات المستقبلية، قد يتم استخدام هذا المعرّف لتفعيل ميزات إضافية لإعداد التقارير والتحسين. ننصحك بتسمية جميع مواضع الإعلانات.
beforeAd	دالة	(اختياري) يتمّ استدعاؤه قبل عرض الإعلان. يجب أن تتوقف اللعبة مؤقتًا ويتم كتم الصوت. يجب تنفيذ هذه الإجراءات بشكل متزامن. سيتم عرض الإعلان فور انتهاء دالة رد الاتصال هذه.
afterAd	دالة	(اختياري) يتم استدعاؤها بعد انتهاء الإعلان (لأي سبب). بالنسبة إلى الإعلانات مقابل مكافآت، يُطلق عليها اسم بعد إما adDismissed أو adViewed، وذلك حسب إجراءات اللاعب. يجب استخدام هذه الدالة لاستئناف سير اللعبة. على سبيل المثال، يمكنك استخدامها لإعادة الصوت وبدء المستوى التالي.
adBreakDone	دالة	(اختياري) يتمّ دائمًا استدعاء هذه السمة كخطوة أخيرة في adBreak()، حتى إذا لم يتمّ عرض أيّ إعلان. تتلقّى الدالة كمعلَمة عنصر placementInfo معرَّفًا على النحو التالي: { breakType: '<type>', breakName: '<name>', breakFormat: 'interstitial|reward', breakStatus: 'error|noAdPreloaded|...|viewed', } راجِع adBreakDone وplacementInfo() للحصول على شرح تفصيلي لكائن معلومات موضع الإعلان.
مواضع الإعلانات مقابل مكافآت فقط...
beforeReward	دالة	يتم استدعاؤها إذا كان هناك إعلان مقابل مكافأة متاح. يجب أن تأخذ الدالة وسيطة واحدة، وهي showAdFn() التي يجب استدعاؤها لعرض "الإعلان مقابل مكافأة".
adDismissed	دالة	يتم استدعاء هذه الطريقة فقط للإعلانات مقابل مكافأة عندما يرفض المشغّل الإعلان. لا يتم استدعاء هذا الحدث إلا إذا أغلق المشغّل الإعلان قبل اكتماله. في هذه الحالة، يجب عدم منح المكافأة.
adViewed	دالة	يتم استدعاء هذه الطريقة فقط للإعلانات مقابل مكافأة عندما يكمل المشغّل الإعلان ويجب منحه المكافأة.

adBreakDone() and placementInfo

إذا لم يتضمّن Ad Placement API إعلانًا لعرضه، لن يتم استدعاء عمليات الرجوع المختلفة قبل/بعد التي تمرّرها. ومع ذلك، إذا قدّمت adBreakDone() دالّة ردّ اتصال، سيتم استدعاؤها دائمًا، حتى إذا لم يتم عرض إعلان. يتيح لك ذلك تنفيذ أي عمل إضافي قد تحتاج إليه لموضع الإعلان، مثل تسجيل إحصاءات إضافية حول موضع الإعلان.

تتلقّى الدالة adBreakDone() كمعلَمة عنصر placementInfo معرَّف على النحو التالي:

{
  breakType: '<type>',
  breakName: '<name>',
  breakFormat: 'interstitial|reward',
  breakStatus: 'notReady|timeout|error|noAdPreloaded|frequencyCapped|ignored|other|dismissed|viewed',
}

حيث تكون دلالات الحقول داخل هذا العنصر كما يلي:

• ‫breakType هو وسيط النوع الذي تم تمريره إلى adBreak()
• ‫breakName هي وسيطة الاسم التي تم تمريرها إلى adBreak()
• breakStatus هي حالة موضع الإعلان هذا، ويمكن أن تكون إحدى القيم التالية:

breakStatus	السبب
'notReady'	لم يتم إعداد واجهة برمجة التطبيقات لموضع الإعلان
'timeout'	انتهت مهلة موضع إعلان لأنّ واجهة برمجة التطبيقات لموضع الإعلان استغرقت وقتًا طويلاً جدًا للردّ
'invalid'	كان موضع الإعلان غير صالح وتم تجاهله، على سبيل المثال، يجب أن يكون هناك موضع إعلان واحد فقط قبل عرض الفيديو لكل عملية تحميل للصفحة، ويتم رفض الإعلانات اللاحقة قبل عرض الفيديو بهذه الحالة
'error'	حدث خطأ في JavaScript في ردّ اتصال
'noAdPreloaded'	لم يتم تحميل إعلان مسبقًا، لذا تم تخطّي موضع الإعلان هذا
'frequencyCapped'	لم يتم عرض الإعلان لأنّه تم تطبيق تحديد عدد مرات الظهور على موضع الإعلان هذا
'ignored'	لم ينقر المستخدم على طلب مكافأة قبل الوصول إلى موضع الإعلان التالي، أي لم يتم استدعاء showAdFn() قبل adBreak() التالي.
'other'	لم يتم عرض الإعلان لسبب آخر. (مثال: كان لا يزال يتم جلب الإعلان، أو تم التخلص من إعلان تم تخزينه مؤقتًا سابقًا لأنّه تم تغيير حجم الشاشة أو تدويرها).
'dismissed'	أغلق المستخدم إعلانًا مقابل مكافأة قبل مشاهدته بالكامل
'viewed'	تم عرض الإعلان للمستخدم

ملاحظة: تكون adBreakDone() دائمًا هي آخر دالة ردّ نداء تستدعيها adBreak().

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