استخدام واجهة برمجة تطبيقات موضع الإعلان

تحتوي واجهة برمجة التطبيقات لموضع الإعلان على وظيفتين: 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() قد لا يعرض إعلانًا على الإطلاق. فما عليك سوى تحديد مكان يمكن عرض عرضه.

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

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

نريدك أن تكون قادرًا على تغيير إعدادات تحقيق الدخل والتحكم في تجربة المستخدم دون الحاجة إلى تعديل إصدار جديد من لعبتك وإصداره، في البداية من خلال تحديد تلميحات في العلامة. ولكن في الإصدارات المستقبلية، سنتمكن من توفير عناصر تحكم مباشرةً في واجهتي 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	واجهة برمجة تطبيقات موضع الإعلان
	إعداد الإعلانات وتحميلها مسبقًا
تشغيل اللعبة
فرصة جيدة لعرض إعلان... adBreak() ←
	يتوفر إعلان، والآن هو الوقت المناسب لعرضه... ← beforeAd()
تتوقف اللعبة مؤقتًا وتكتم الصوت وتستعد لعرض الإعلان. return إلى واجهة برمجة التطبيقات →
	تعرض واجهة برمجة تطبيقات موضع الإعلان الإعلان البيني. يمكن للمشغل النقر على الإعلان (الذي يظهر في علامة تبويب جديدة). عليه إغلاق الإعلان لمواصلة تشغيل اللعبة.
	←يتم استدعاء afterAd() في حالة عرض أحد الإعلانات
تعيد اللعبة إلغاء الإيقاف المؤقت وتعيد الصوت.
	← adBreakDone()يتم دائمًا استدعاء adBreakDone() (حتى في حالة عدم عرض الإعلان)
تسجِّل اللعبة إحصاءات حول هذا الموضع.

ملاحظات

• adBreak() هي دالة غير متزامنة يتم عرضها على الفور.
• إذا لم يكن هناك أي إعلان لعرضه لموضع معين، فلن يتم استدعاء أيٍّ من استدعاءات العرض، أي "beforeAd()"،afterAd().
• ولضمان عدم استمرار تشغيل لعبتك أثناء عرض الإعلان، يمكنك استخدام معاودة الاتصال من beforeAd() لكتم الصوت وإيقاف اللعبة مؤقتًا.
• beforeAd() متزامن، ولن تعرض واجهة برمجة التطبيقات لموضع الإعلان أي إعلان حتى يعود.
• يمكنك إعادة تشغيل اللعبة وإلغاء كتم الصوت عند تلقّي مكالمة 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	واجهة برمجة تطبيقات موضع الإعلان
	بدء تشغيل واجهة برمجة التطبيقات والتخزين المؤقت المسبق للإعلانات
قيد التشغيل ولكنه لم يبدأ ولم يعرض واجهة مستخدم
adBreak(type:'preroll',…) ←
	تنتهي واجهة برمجة تطبيقات موضع الإعلان من إعداد الإعلانات وتحميلها. إذا كان هناك إعلان معروض. يمكن للمشغل النقر على الإعلان (الذي يظهر في علامة تبويب جديدة). يجب أن يغلقها حتى تبدأ اللعبة.
	← يتم دائمًا استدعاء adBreakDone() (حتى في حالة عدم عرض أحد الإعلانات)
يتم عرض واجهة مستخدم اللعبة على الشاشة ويمكن للاعب التفاعل معها الآن. يمكن أن تستخدم اللعبة العنصر placementInfo الذي يتم تمريره إلى adBreakDone() حسب الحاجة (لتسجيل إحصاءات إضافية مثلاً).

ملاحظات

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

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

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

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

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

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

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

ونهدف مرة أخرى هنا إلى السماح لك بدمج لعبتك مع واجهة برمجة تطبيقات موضع الإعلان مرة واحدة، ثم - بمرور الوقت باستخدام عناصر التحكم في العلامة أو في 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	واجهة برمجة تطبيقات موضع الإعلان
	إعداد الإعلانات والتخزين المؤقت مسبقًا للإعلانات
تشغيل اللعبة
adBreak(type:'reward', ... ) ←
	يتوفر إعلان؛ لذا ابدأ موضع إعلان بمكافأة. يتم استدعاء beforeReward() بشكل متزامن فورًا بعد المكالمة إلى adBreak() ← beforeReward(showAdFn)
تعرض اللعبة رسالة طلب المكافأة. يمنح هذا اللاعب الفرصة للحصول على مكافأة من خلال مشاهدة إعلان. يمكن تقديم أكثر من نوع واحد من المكافآت (على سبيل المثال، حياة جديدة أو عملة ذهبية). ويمكن للاعب النقر على رسالة طلب المكافأة أو تجاهلها أو تجاهلها. في حال النقر على رسالة مطالبة، تخزّن اللعبة نوع المكافأة التي طلبتها وتتصل بـ showAdFn()... وبخلاف ذلك، في حال تم رفض طلب المكافأة أو تجاهلها، لن يتم تنفيذ أي إجراء حتى يتم إجراء استدعاء آخر إلى adBreak() باستخدام نوع موضع المكافأة الذي ستتم عنده إعادة ضبط واجهة برمجة التطبيقات لموضع الإعلان وتنظيف الحالة من هذه المكالمة. إذا طلب التطبيق showAdFn من فاصل إعلاني سابق، لن يكون لذلك أي تأثير.
showAdFn() ←
	← beforeAd()
تتوقف اللعبة مؤقتًا وتكتم الصوت وتستعد لعرض الإعلان return إلى واجهة برمجة التطبيقات →
	تعرض واجهة برمجة التطبيقات الإعلان. ويحتوي هذا الزر على زر إغلاق وعد تنازلي يوضح مقدار الوقت المتبقي في الإعلان.
في حال إغلاق المشغّل للإعلان...
	← adDismissed()
أغلق اللاعب الإعلان ولا تُصدر اللعبة المكافأة.
أخرى يشاهد اللاعب الإعلان حتى نهايته...
	← adViewed()
شاهد اللاعب الإعلان حتى نهايته وأصدرت اللعبة المكافأة. (عادةً ما يحدث ذلك من خلال ضبط حالة اللعبة التي يتم اختيارها بعد ذلك عندما تتم إعادة تشغيل اللعبة مع الاتصال بـ afterAd() أدناه).
بعد مشاهدة الإعلان أو رفضه...
	← يتم استدعاء afterAd() في حالة عرض أحد الإعلانات
تعيد اللعبة إلغاء الإيقاف المؤقت وتعيد الصوت.
	← adBreakDone()يتم دائمًا استدعاء adBreakDone() (حتى في حالة عدم عرض الإعلان)
تسجِّل اللعبة إحصاءات حول هذا الموضع.

ملاحظات

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