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 الدالة (OPTIONAL) يتم دائمًا استدعاء الخطوة الأخيرة في adBreak()، حتى في حال عدم عرض أي إعلان. تستخدم الدالة كوسيطة لكائن placementInfo يتم تحديدها على النحو التالي: 
{
    breakType: '<type>',
    breakName: '<name>',
    breakFormat: 'interstitial|reward',
    breakStatus:  'error|noAdPreloaded|...|viewed',
}
يُرجى الاطّلاع على adBreakDone وplacementInfo() للحصول على شرح تفصيلي لكائن معلومات موضع الإعلان.
مواضع الإعلانات بمكافأة فقط...
beforeReward الدالة يتم الاتصال بك في حال توفّر إعلان بمكافأة. يجب أن تستخدم الدالة وسيطة واحدة – showAdFn() والتي يجب استدعاؤها لعرض الإعلان بمكافأة.
adDismissed الدالة يتم استخدامها فقط للإعلانات بمكافأة عندما يغلق المشغِّل الإعلان. ولا يتم طلبها إلا إذا غلق المشغِّل الإعلان قبل اكتماله. وفي هذه الحالة، يجب ألا يتم منح المكافأة.
adViewed الدالة يتم طلبها فقط للإعلانات بمكافأة عند إكمال المشغِّل للإعلان ويجب منح المكافأة.

adBreakDone() and placementInfo

إذا كانت واجهة برمجة التطبيقات لموضع الإعلان لا تحتوي على إعلان لعرضه، لن تستدعي الاستدعاءات المختلفة قبل/بعد الاستدعاءات التي تمرِّرها. أمّا في حال توفير معاودة الاتصال من 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().