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

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

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

אתחול Google Mobile Ads Unity Plugin

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

using GoogleMobileAds.Api;
using System.Collections.Generic;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    ...
    public void Start()
    {
        // Initialize Google Mobile Ads Unity Plugin.
        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. בוחרים את הפונקציה שרוצים לקשר לשיחת החזרה (callback) של המודעה. במקרה של קריאות חוזרות למודעות עם פרמטרים, בוחרים את הפונקציה לקבלת המשתנה הדינמי כדי לקבל את ערך הפרמטר מ-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 GameObject שהוספתם בשלב הקודם לשדה None (Object). בוחרים פונקציה מהתפריט הנפתח. לוחצים על No Function > GameObject > SetActive(bool)‎, ואז לוחצים על תיבת הסימון כדי לשלוח true כפרמטר (מתבצעת קריאה ל-SetActive(true)).

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

בשלב הבא, יוצרים את הלחצן להצגת מודעה מתגמלת בלחיצה. בקטע On Click() Callbacks (התקשרות חזרה של OnClick()) בכלי לבדיקת לחצנים, לוחצים על הלחצן + וגוררים ושומטים את 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() מופעלת כשמגיע לכם תגמול על האינטראקציה עם המודעה.