מיקומי מודעות

במדריך הזה מוסבר איך להשתמש בתכונה Ad Placements (מיקומי מודעות) של הפלאגין Google Mobile Ads Unity כדי ליצור מודעות ולהציג אותן באפליקציה.

דרישות מוקדמות

הפעלה של Google Mobile Ads SDK

לפני טעינת המודעות, צריך להפעיל את Google Mobile Ads SDK באמצעות הקריאה ל-MobileAds.Initialize(), עם קריאה חוזרת (callback) ל-Action<InitializationStatus>. צריך לבצע את הפעולה הזו רק פעם אחת, ועדיף בזמן הפעלת האפליקציה.

using GoogleMobileAds.Api;
using System.Collections.Generic;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    ...
    public void Start()
    {
        // Initialize Google Mobile Ads SDK.
        MobileAds.Initialize((initStatus) =>
        {
            // SDK initialization is complete
        });
        ...
    }
}

יצירת מיקומי מודעות

השלב הראשון בהצגת באנר באמצעות Google Mobile Ads הוא ליצור מיקום מודעה ולהגדיר אותו. אפשר לבחור מיקום להצגת מודעה בפורמט באנר, מעברון או מתגמלת דרך Assets > Google Mobile Ads > Ad Placements (נכסים > מודעות לנייד של Google > מיקומים להצגת מודעות) בכלי Unity Editor. לאחר מכן, מוגדרים שלושה מיקומי מודעות לדוגמה שמוכנים לשימוש.

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

הגדרת מיקומי מודעות

לכל מיקום יש את המאפיינים הבאים:

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

בצילום המסך הבא אפשר לראות דוגמה למיקום מודעה בשם My Awesome Banner.

הוספת AdGameObject לסצנה

אפשר להוסיף AdGameObject לפורמטים של מודעות באנר, מודעות מעברון או מודעות מתגמלות לסצנה באמצעות GameObject > Google Mobile Ads ב-Unity Editor. בוחרים את הפורמט כדי להוסיף מיקום להצגת מודעות לסצנה הפעילה.

אחרי שמוסיפים AdGameObject לסצנה, מופיע GameObject שמייצג את המודעה בתצוגת ההיררכיה של Unity Editor.

אפשר לשנות את השם של מיקום המודעה על ידי שינוי השם של GameObject עצמו. בצילום המסך הבא מוצגת דוגמה ל-AdGameObject בשם Banner Ad.

הגדרות של AdGameObject

אפשר להגדיר את AdGameObject בסצנה מתצוגת Inspector בהגדרות של הרכיב Ad Game Object (Script).

מיקום מודעה

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

הגדרה של BannerAdGameObject (באנר בלבד)

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

התקשרות חזרה

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

  1. יוצרים פונקציה שתואמת לקריאה החוזרת של המודעה.

    public void OnBannerAdFailedToLoad(string reason) {
    Debug.Log("Banner ad failed to load: " + reason);
}

  2. מצרפים את הסקריפט שמכיל את הפונקציה שלמעלה לכל GameObject בסצנה.

  3. לוחצים על הלחצן +, ואז גוררים ושומטים את GameObject שאליו צירפתם את הסקריפט.

  4. בוחרים את הפונקציה שרוצים לקשר לשיחת החזרה בנושא מודעות. במקרה של קריאות חוזרות למודעות עם פרמטרים, בוחרים את הפונקציה לקבלת המשתנה הדינמי כדי לקבל את ערך הפרמטר מ-SDK.

שימוש ב-AdGameObject מסקריפט

קבלת מופע AdGameObject מהסקריפט

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

כדי לקבל את המופע של AdGameObject, משתמשים בשיטה הבאה לכל פורמט:

MobileAds.Instance.GetAd<BannerAdGameObject>("AD_GAMEOBJECT_NAME");

האובייקט BannerAdGameObject שמוחזר כולל גם את השיטות הנוחות Hide() ו-Show().

מעברון

MobileAds.Instance.GetAd<InterstitialAdGameObject>("AD_GAMEOBJECT_NAME");

לאובייקט InterstitialAdGameObject שמוחזר יש שיטת נוחות ShowIfLoaded().

ההטבה הופעלה

MobileAds.Instance.GetAd<RewardedAdGameObject>("AD_GAMEOBJECT_NAME");

לאובייקט RewardedAdGameObject שמוחזר יש שיטת נוחות ShowIfLoaded().

לדוגמה, אפשר לקבל מופע של BannerAdGameObject ולטעון אותו באופן הבא:

using UnityEngine;

using GoogleMobileAds.Api;
using GoogleMobileAds.Placement;

public class BannerTestScript : MonoBehaviour
{
    BannerAdGameObject bannerAd;

    void Start()
    {
        bannerAd = MobileAds.Instance
            .GetAd<BannerAdGameObject>("AD_GAMEOBJECT_NAME");

        bannerAd.LoadAd();
        ...
    }
    ...
}

אם יש BannerAdGameObject בשם BannerAd, אפשר לקבל מופע שלו כך:

MobileAds.Instance.GetAd<BannerAdGameObject>("BannerAd");

גישה לאובייקט הבסיסי של המודעה ב-AdGameObject

קטעי הקוד האלה מדגימים איך לגשת לאובייקט המודעה הבסיסי שמשויך ל-AdGameObject.

BannerAdGameObject bannerAd = MobileAds.Instance
    .GetAd<BannerAdGameObject>("AD_GAMEOBJECT_NAME");

// Access BannerView object
BannerView bannerView = bannerAd.BannerView;

מעברון

InterstitialAdGameObject interstitialAdGameObject = MobileAds.Instance
    .GetAd<InterstitialAdGameObject>("AD_GAMEOBJECT_NAME");

// Access InterstitialAd object
InterstitialAd interstitialAd = interstitialAdGameObject.InterstitialAd;

ההטבה הופעלה

RewardedAdGameObject rewardedAdGameObject = MobileAds.Instance
    .Get<RewardedAdGameObject>("AD_GAMEOBJECT_NAME");

// Access RewardedAd object
RewardedAd rewardedAd = rewardedAdGameObject.RewardedAd;

דוגמאות

הצגת מודעת מעברון

הנה דוגמה להגדרת משחק לטעינה ולהצגה של מודעת מעברון באמצעות AdGameObject.

מוסיפים InterstitialAdGameObject לסצנה ומפעילים את התכונה Auto Load Enabled כדי שהמודעה תיטען אוטומטית כשהסצנה תיטען.

לאחר מכן, מוודאים שהפעלתם את ה-SDK באופן הבא. חשוב לזכור שהתכונה Auto Load ב-AdGameObject לא תפעל אם תשכחו לאתחל את ה-SDK.

לאחר מכן מציגים מודעת מעברון בין מעבר מסך לקריאה לפונקציה InterstitialAdGameObject.ShowIfLoaded(). בדוגמה הבאה מוצג קוד להצגת מודעת מעברון בין מעבר מסצנה אחת לאחרת.

using UnityEngine;
using UnityEngine.SceneManagement;

using GoogleMobileAds.Api;
using GoogleMobileAds.Placement;

public class MainScene : MonoBehaviour
{
    InterstitialAdGameObject interstitialAd;

    void Start()
    {
        interstitialAd = MobileAds.Instance
            .GetAd<InterstitialAdGameObject>("interstitial");

        MobileAds.Initialize((initStatus) => {
            Debug.Log("Initialized MobileAds");
        });
    }

    public void OnClickShowGameSceneButton()
    {
        // Display an interstitial ad
        interstitialAd.ShowIfLoaded();

        // Load a scene named "GameScene"
        SceneManager.LoadScene("GameScene");
    }
}

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

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

public class MainScene : MonoBehaviour
{
    InterstitialAdGameObject interstitialAd;

    void Start()
    {
        interstitialAd = MobileAds.Instance
            .GetAdGameObject<InterstitialAdGameObject>("interstitial");

        MobileAds.Initialize((initStatus) => {
            Debug.Log("MobileAds initialized");

            // Load an interstitial ad after the SDK initialization is complete
            interstitialAd.LoadAd();
        });
    }
    ...
}

טיפול במצב הלחצן 'צפייה במודעה מתגמלת'

בדוגמה הבאה מוצג אופן ההפעלה של לחצן 'צפייה במודעה מתגמלת' באמצעות מיקומי מודעות.

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

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

public class MainScene : MonoBehaviour
{
    ...
    void Start()
    {
        GameObject.Find("Button").SetActive(false);
        ...
    }
}

מוסיפים RewardedAdGameObject לסצנה ובוחרים את מיקום המודעה AdMob Demo Rewarded Ad מהתפריט הנפתח.

בקטע Callbacks (קריאות חוזרות) בכלי RewardedAdGameObject inspector, לוחצים על הלחצן + מתוך On Ad Loaded() כדי להפעיל את האפשרות לקרוא לפונקציה כשמודעה מתגמלת נטענת.

גוררים ומשחררים את אובייקט המשחק Button שנוסף בשלב הקודם לשדה None (Object). בוחרים פונקציה להפעלה מהתפריט הנפתח. לוחצים על No Function > GameObject > SetActive(bool)‎, ואז לוחצים על תיבת הסימון כדי לשלוח true כפרמטר (הפעלת SetActive(true)).

בקטע Callbacks, אפשר גם לקשר אירוע שיופעל כשאירוע RewardedAd.OnUserEarnedReward יופעל. מידע נוסף זמין בקטע הזה.

בשלב הבא, יוצרים את הלחצן להצגת מודעה מתגמלת בלחיצה. בקטע On Click() Callbacks (התקשרות חזרה), בכלי לבדיקת לחצנים, לוחצים על הלחצן + וגוררים את GameObject של מיקום המודעה המתגמלת (שנקרא Rewarded Ad בדוגמה הזו) לשדה None (Object) (ללא (אובייקט)).

לאחר מכן, מצרפים את הפונקציה RewardedAdGameObject.ShowIfLoaded() לקריאה החוזרת On Click() של הלחצן.

לבסוף, אל תשכחו להפעיל את ה-SDK. קטע הקוד הבא הוא הקוד המלא של הסצנה שמשמשת בדוגמה הזו:

using UnityEngine;

using GoogleMobileAds.Api;

public class MainScene : MonoBehaviour
{
    void Start()
    {
        GameObject.Find("Button").SetActive(false);

        MobileAds.Initialize((initStatus) => {
            Debug.Log("Initialized MobileAds");
        });
    }
}

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

הגדרת קריאה חוזרת (callback) של פרס עבור RewardedAdGameObject

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

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

using UnityEngine;
using GoogleMobileAds.Api;

class RewardedTestScript : MonoBehaviour {
    ...
    public void OnUserEarnedReward(Reward reward) {
        Debug.Log("OnUserEarnedReward: reward=" +
            reward.Type + ", amount=" + reward.Amount);
    }
    ...
}

מצרפים את סקריפט RewardedTestScript לכל GameObject (חוץ מ-GameObject של מיקום מודעה) בסצנה. בדוגמה הזו, הוא מצורף לאובייקט Main Camera GameObject.

מוסיפים RewardedAdGameObject לסצנה. בקטע Callbacks בכלי RewardedAdGameObject inspector, לוחצים על הלחצן + לצד On User Earned Reward (Reward) כדי להפעיל את הפונקציה שתופעל כשמשתמש יקבל תגמול.

גוררים ושומטים את אובייקט המשחק Main Camera שהוספתם בשלב הקודם לשדה None (Object). בוחרים פונקציה להפעלה מהתפריט הנפתח. לוחצים על No Function > RewardedTestScript > OnUserEarnedReward.

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