שימוש ב-Ad Placement API

‫Ad Placement API מכיל שתי פונקציות: 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() לא תציג מודעה בכלל. התג הזה פשוט מציין מקום שבו יכולה להופיע מודעה.

זה שונה מממשקי API רגילים, שבהם הקוד תמיד יודע אם מודעה זמינה, ואתם מחליטים בתוך המשחק אם להציג אותה. הגישה הזו, שבה Ad Placement API מחליט אם להציג מודעה במיקום מסוים, היא דפוס שנקרא לפעמים "היפוך שליטה".

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

אנחנו רוצים לאפשר לכם לשנות את הגדרות המונטיזציה ולשלוט בחוויית המשתמש בלי שתצטרכו לערוך ולפרסם גרסה חדשה של המשחק. בשלב הראשון, תוכלו לציין רמזים בתג. אבל בגרסאות עתידיות נוכל לספק אמצעי בקרה ישירות בממשקי הקצה של 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 Ad Placement API
  אתחול וטעינה מראש של מודעות
הפעלת המשחק  

הזדמנות טובה להצגת מודעה…

‎adBreak() →‎‏

 
 

יש מודעה זמינה ועכשיו זה זמן טוב להציג אותה…

← beforeAd()
המשחק מושהה, הצליל מושתק והמשחק מתכונן להצגת המודעה.

return אל ה-API →

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

הערות

  • ‫adBreak() היא פונקציה אסינכרונית שמוחזרת באופן מיידי.
  • אם אין מודעה להצגה במיקום מסוים, אף אחת מהפונקציות להחזרת קריאה לא מופעלת – כלומר,אף אחת מהפונקציות beforeAd(), afterAd() לא מופעלת.
  • כדי לוודא שהמשחק לא ימשיך לפעול בזמן שהמודעה מוצגת, צריך להשתמש ב-callback‏ beforeAd() כדי להשתיק את הצליל ולהשהות את המשחק.
  • ‫beforeAd() הוא סינכרוני, ולכן Ad Placement API לא יציג מודעה עד שהוא יחזיר ערך.
  • מפעילים מחדש את המשחק ומבטלים את השתקת הצליל כשמקבלים את השיחה afterAd()
  • אם הפונקציה adBreakDone() מסופקת, היא תמיד מופעלת גם אם לא הוצגה מודעה במיקום הזה.
  • התקשרות אל adBreak() בזמן שמודעה אחרת מוצגת תיכשל, ותוצג אזהרה במסוף JavaScript.

פרסומות לפני סרטון

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

רצף שיחות

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

תרשים של רצף קריאות למודעות לפני סרטון

הפעלת הקוד הבא, בשלב מוקדם בלוגיקה של המשחק, תציב מודעה לפני הצגת התוכן. הממשק לא צריך להיות מוצג לפני שהקוד הזה נקרא.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
פרסומת לפני הסרטון – רצף שיחות מפורט
משחק H5 Ad Placement API
  הפעלת ה-API ושמירה מראש במטמון של מודעות מתחילות
פועל אבל לא התחיל ולא הציג ממשק משתמש  

‎adBreak(type:'preroll',…) →‎‏

 
 

האתחול של Ad Placement API מסתיים והמודעות נטענות. אם יש מודעה, היא מוצגת. המשתמש יכול ללחוץ על המודעה (שמוצגת בכרטיסייה חדשה). הם צריכים לסגור את ההודעה כדי שהמשחק יתחיל.

 

‫← adBreakDone() תמיד מופעל (גם אם לא הוצגה מודעה)

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

  

הערות

  • מודעה לפני סרטון תמיד תנסה לבצע טעינה מראש של מודעות:
    • אין צורך להתקשר אל adConfig(preloadAds: ‘on') כשמשתמשים בסרטוני פרסום לפני התוכן.
  • בדומה למיקומים אחרים להצגת מודעות, יכול להיות שתוצג מודעה לפני הסרטון ויכול להיות שלא.
  • אין להעביר את beforeAd() ו-afterAd() למודעה שלפני הסרטון.
    • מודעות לפני הסרטון (pre-roll) מוצגות לפני שהמשחק מתחיל, ולכן אין צורך להשהות את המשחק או להשתיק את הצליל שלו.
    • אם מעבירים את הערכים beforeAd() או afterAd() עם פרסומת לפני הסרטון, הקריאה תיכשל ושגיאה תירשם במסוף JavaScript.
  • מודעה לפני הסרטון ממתינה אוטומטית עד להפעלת Ad Placement API ולטעינה מראש של מודעות:
    • עם זאת, יש פסק זמן (2 שניות) שמונע את העיכוב של השיחה לזמן בלתי מוגבל. כך אפשר לוודא שהפונקציה adBreakDone() מופעלת בזמן והמשחק מתחיל.
    • המערכת תמיד קוראת ל-adBreakDone() גם אם אין מודעה.
  • מומלץ להשתמש במודעה שלפני הסרטון כדי להציג מודעות לפני שהמשחק מתחיל.
    • אפשרות נוספת היא להשתמש בonReady() קריאה חוזרת (callback) אל adConfig() כמנגנון להרצת הלוגיקה של המשחק ברצף עם ההפעלה של ה-API והטעינה מראש של המודעות.

מודעות מתגמלות

מודעה מתגמלת מאפשרת לכם לתגמל את השחקנים בפריטים מתוך האפליקציה אם הם בוחרים לצפות במודעה. מודעות מעברון הן אופציית ביטול הסכמה, כלומר המודעה מוצגת למשתמש והוא יכול לבחור לסגור אותה. הצפייה במודעות מתגמלות היא אופציונלית. השחקנים בוחרים אם ומתי הם רוצים לצפות במודעה כדי לקבל תגמול.

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

השחקנים יכולים לבחור אם לצפות במודעות מתגמלות, ולכן צריך לשלב אותן בצורה חלקה יותר בתהליך המשחק. אתם צריכים לספק פונקציות להצגת הנחיה לקבלת תגמול במשחק, ולהקצאת התגמול לשחקן אם הוא צופה במודעה.

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

השחקנים יכולים לבחור אם לצפות במודעות מתגמלות או לא, ולכן אפשר להוסיף אותן בכל מקום במשחק שנראה לכם מתאים, וגם להשתמש בהן בנוסף למודעות מעברון. בדומה למודעות מעברון, המיקומים האלה הם הזדמנויות להצגת מודעות מתגמלות. ה-Ad Placement API יפעיל את הקוד רק אם בפועל תוצג מודעה מתגמלת בנקודה מסוימת במשחק.

המטרה היא לאפשר לכם לשלב את המשחק עם Ad Placement API פעם אחת, ואז, לאורך זמן, להשתמש באמצעי בקרה בתג או ב-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 Ad Placement API
  הפעלה ראשונית וטרום-שמירה במטמון של מודעות
הפעלת המשחק  

‎adBreak(type:'reward', ... ) →‎‏

 
 

יש מודעה זמינה, לכן מתחילים להציב מודעה מתגמלת. הקריאה ל-beforeReward() מתבצעת באופן סינכרוני – מיד אחרי הקריאה ל-adBreak()

← beforeReward(showAdFn)

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

השחקן יכול ללחוץ על ההודעה על התגמול, לסגור אותה או פשוט להתעלם ממנה.

אם הם לוחצים על הנחיה, המשחק שומר את סוג התגמול שהם ביקשו ומפעיל את הפונקציה showAdFn()...

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

  

‎showAdFn() →‎‏

 
  ← beforeAd()

המשחק מושהה, הצליל מושתק והמערכת מתכוננת להצגת המודעה

return אל ה-API →

 
  המודעה מוצגת באמצעות ה-API. יש בו לחצן סגירה וספירה לאחור של הזמן שנותר להצגת המודעה.
אם הנגן סוגר את המודעה...
  ← adDismissed()
השחקן סגר את המודעה והמשחק לא העניק את התגמול.  
ELSE the player watches the ad to completion...
  ← adViewed()
השחקן צפה במודעה עד הסוף והמשחק העניק לו את התגמול. (בדרך כלל עושים זאת על ידי הגדרת מצב משחק מסוים, שמוחזר כשמפעילים מחדש את המשחק באמצעות הקריאה ל-afterAd() שבהמשך).  
אחרי שהצפייה במודעה הסתיימה או שהמודעה נסגרה...
  ‫← afterAd() מופעלת אם מודעה הוצגה
המשחק יופעל מחדש וההשתקה תבוטל.  
  ‫← adBreakDone()adBreakDone() תמיד נקראת (גם אם לא הוצגה מודעה)
המשחק מתעד נתונים סטטיסטיים לגבי מיקום המודעה הזה.  

הערות

  • ‫adBreak() היא פונקציה אסינכרונית שמוחזרת באופן מיידי.
  • אם אין מודעה להצגה במיקום מודעה, אף אחת מהפונקציות להחזרת ערך לא נקראת – כלומר, אף אחת מהפונקציות beforeAd() ו-beforeReward() לא נקראת.
  • כדי לוודא שהמשחק לא ימשיך לפעול בזמן שהמודעה מוצגת, צריך להשתמש ב-callback‏ beforeAd() כדי להשתיק את הצליל ולהשהות את המשחק.
  • ‫beforeAd() הוא סינכרוני, ולכן Ad Placement API לא יציג מודעה עד שהוא יחזיר ערך.
  • מפעילים מחדש את המשחק ומבטלים את השתקת הצליל כשמקבלים את השיחה afterAd()
  • אם הפונקציה adBreakDone() מסופקת, היא תמיד מופעלת גם אם לא הוצגה מודעה במיקום הזה.
  • התקשרות אל adBreak() בזמן שמודעה אחרת מוצגת תיכשל, ותוצג אזהרה במסוף JavaScript.