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' לא בוצעה הפעלה של 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().