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 string

סוג מיקום המודעה. ערכים:

  • 'preroll' לפני שהמשחק נטען (לפני עיבוד ממשק המשתמש)
  • 'start' לפני שהמשחק מתחיל (לאחר עיבוד ממשק המשתמש)
  • 'pause' השחקן משהה את המשחק
  • שחקן אחד ('next') עובר לרמה הבאה
  • 'browse' השחקן מגלה אפשרויות מחוץ למשחק
  • 'reward' מודעה מתגמלת
name string (אופציונלי) שם למיקום המודעה הזה במשחק. זהו מזהה פנימי והוא אינו מוצג בנגן. בגרסאות עתידיות, המזהה הזה ישמש להפעלת תכונות דיווח ואופטימיזציה נוספות.

מומלץ לתת שם לכל המיקומים.
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() לקריאה חוזרת (callback), המערכת תמיד תפעיל את התכונה הזו, גם אם מודעה לא מוצגת. כך תוכלו לבצע כל עבודה נוספת שאולי תרצו לבצע עבור המיקום, כמו איתור נתוני ניתוח נוספים לגבי המיקום.

הפונקציה 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' ה-Ad Placement API לא הופעל
'timeout' תם הזמן הקצוב לתפוגה של מיקום מודעה מפני של-Ad Placement API נדרש זמן רב מדי
'invalid' המיקום היה לא חוקי והמערכת התעלמה ממנו. לדוגמה, בכל דף צריכה להיות רק מודעה אחת לפני סרטון, המודעה לפני הסרטון נכשלה עם הסטטוס הזה.
'error' אירעה שגיאת JavaScript בקריאה החוזרת (callback)
'noAdPreloaded' המודעה לא נטענה מראש. המערכת דילגה על המיקום הזה
'frequencyCapped' לא הוצגה מודעה כי נקבעה מכסת תדירות למיקום הזה
'ignored' המשתמש לא לחץ על הודעת תגמול לפני שהוא הגיע למיקום הבא, כלומר showAdFn() לא נקרא לפני adBreak() הבא.
'other' המודעה לא הוצגה מסיבה אחרת. (למשל המודעה עדיין לא אוחזרה, או שמודעה שנשמרה במטמון בעבר נמחקה כי המסך השתנה או סובב.)
'dismissed' המשתמש סגר מודעה מתגמלת לפני שצפה בה עד הסוף
'viewed' המשתמש צפה במודעה

הערה: השיחה adBreakDone() היא תמיד השיחה האחרונה שנוצרה על ידי adBreak().

אם משתמשים ב-afterAd() כדי לבטל את השהיית המשחק אחרי שמודעה מוצגת, תתבצע קריאה אל adBreakDone() אחרי שהמשחק יופעל מחדש. במקרים כאלה, למשל ביומן הרישום של ניתוח הנתונים, זו עשויה להיות התאמה, אבל אם ברצונך לבצע עבודה נוספת לפני שהמשחק מופעל מחדש, מומלץ להעביר את הלוגיקה כדי לבטל את ההשהיה של המשחק מ-afterAd() אל adBreakDone().