שימוש ב-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 מסורתיים שבהם הקוד תמיד יודע אם מודעה זמינה, ומחליטים בתוך המשחק אם להציג אותה. הגישה הזו של אישור ה-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 שלך	ממשק API של מיקום מודעה
	אתחול וטעינה מראש של מודעות
המשחק פועל
הזדמנות טובה להציג מודעה... adBreak() ←
	קיימת מודעה זמינה והגיע הזמן להציג אותה... ← beforeAd()
המשחק מושהה, משתיק את הצליל ומתכונן להצגת המודעה. return ל-API ←
	ממשק ה-API של מיקום מודעה מציג את מודעת הביניים. הנגן יכול ללחוץ על המודעה (מוצגת בכרטיסייה חדשה). הם חייבים לסגור את המודעה כדי להמשיך לשחק במשחק.
	← afterAd() מתבצעת קריאה אם מודעה הוצגה
המשחק יושהה וההשתקה תבוטל.
	← adBreakDone()adBreakDone() תמיד נקרא (גם אם לא הוצגה מודעה)
המשחק מתעד ניתוח נתונים לגבי המיקום הזה.

הערות

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

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

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

רצף שיחות

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

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

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})

קדם-סרטון – רצף שיחות מפורט
משחק H5 שלך	ממשק API של מיקום מודעה
	התחלת אתחול ושמירה במטמון של מודעות.
פועל, אבל לא התחיל ולא הציג ממשק משתמש
adBreak(type:'preroll',…) ←
	ה-API של מיקום המודעה מסיים את הטעינה והטעינה של מודעות. אם יש מודעה שהיא מוצגת. הנגן יכול ללחוץ על המודעה (שמוצגת בכרטיסייה חדשה). הם חייבים לסגור את המשחק כדי שיתחיל המשחק.
	← adBreakDone() תמיד קוראים (גם אם לא הוצגה מודעה)
ממשק המשתמש של המשחק מוצג במסך והנגן יכול לקיים איתו אינטראקציה. המשחק יכול להשתמש באובייקט placementInfo שמועבר אל adBreakDone() לפי הצורך (לדוגמה, כדי לתעד ניתוחי נתונים נוספים).

הערות

• המערכת תמיד תנסה לטעון מראש מודעות לפני הסרטון:
  • לא צריך להתקשר אל adConfig(preloadAds: ‘on') באמצעות מודעות לפני סרטון.
• בדומה למיקומי מודעה אחרים, ייתכן שמודעת הקדם-הצגה לא תציג מודעה.
• אין להעביר את beforeAd() ואת afterAd() לקדם-סרטון.
  • מאחר שמודעות לפני סרטון מוצגות לפני שהמשחק מתחיל, אין צורך להשהות או להשתיק את הצליל שלו.
  • אם עוברים את beforeAd() או afterAd() עם מודעה לפני סרטון, השיחה תיכשל ותירשם שגיאה במסוף JavaScript.
• מודעה לפני סרטון ממתינה באופן אוטומטי ש-Ad Placement API יפעיל וטען מראש מודעות:
  • עם זאת, יש זמן קצוב לתפוגה שמשבית את השיחה ללא הגבלת זמן. כך תוכלו להבטיח שההתקשרות אל adBreakDone() תתבצע בזמן הנכון והמשחק יתחיל.
  • adBreakDone() תמיד מקבל קריאה, גם אם אין מודעה.
• אנו ממליצים להשתמש במודעות קדם-סרטון כדי למקם מודעות לפני תחילת המשחק.
  • לחלופין, אפשר להשתמש בקריאה החוזרת (callback) של onReady() ל-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 שלך	ממשק API של מיקום מודעה
	אתחול ושמירה מראש של מודעות
המשחק פועל
adBreak(type:'reward', ... ) ←
	יש מודעה זמינה ולכן צריך ליצור מודעה מתגמלת. beforeReward() נקרא באופן סינכרוני – מיד אחרי השיחה אל adBreak() ← beforeReward(showAdFn)
המשחק מעבד את בקשת התגמול. זוהי הצעה שמאפשרת לשחקן לקבל פרס על צפייה במודעה. אפשר להציע יותר מסוג אחד של פרס (לדוגמה, חיים חדשים או מטבע זהב). הנגן יכול ללחוץ על הודעת תגמול, לסגור אותה או פשוט להתעלם ממנה. אם הוא לוחץ על הודעה, המשחק מאחסן את סוג הפרס שהוא ביקש ומתקשר אל showAdFn()... אחרת, אם הדחייה של ההודעה תבוטל או שהמערכת תתעלם ממנה, לא יקרה דבר עד שתבצעו שיחה נוספת ל-adBreak() עם סוג של מיקום מודעה בפרס. לאחר מכן, ה-API של מיקום המודעה יאופס וינקה את המצב מהשיחה הזו. אם באפליקציה מופעלת קריאה ל-showAdFn מהפסקה קודמת למודעה, אין לה השפעה.
showAdFn() ←
	← beforeAd()
המשחק מושהה, משתיק את הצליל ומתכונן להציג את המודעה return ל-API ←
	ה-API מציג את המודעה. מופיע בה לחצן סגירה וספירה לאחור שמציגה כמה זמן נשאר במודעה.
אם הנגן סוגר את המודעה...
	← adDismissed()
השחקן סגר את המודעה והמשחק לא מנפיק את הפרס.
אחרת הנגן צופה במודעה עד סופה...
	← adViewed()
השחקן צפה במודעה עד סופה והמשחק מנפיק את הפרס. (לרוב, הכלל הזה יוגדר על ידי הגדרה מסוימת של מצב המשחק, אשר תזוהה כשהמשחק יופעל מחדש על ידי קריאה ל-afterAd() שבהמשך).
אחרי שהמודעה נצפתה או נסגרת...
	← afterAd() נקרא אם הוצגה מודעה
המשחק יושהה וההשתקה תבוטל.
	← adBreakDone()adBreakDone() תמיד נקרא (גם אם לא הוצגה מודעה)
המשחק מתעד ניתוח נתונים לגבי המיקום הזה.

הערות

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