הוספת מודעה בפתיחת אפליקציה ב-AdMob לאפליקציית Unity

1. מבוא

ב-Codelab הזה מטמיעים מודעה בפתיחת אפליקציה ב-AdMob באפליקציית Unity.

מה תפַתחו

ב-codelab הזה מוסבר איך להטמיע מודעה בפתיחת אפליקציה ב-AdMob באפליקציית Unity באמצעות הפלאגין Google Mobile Ads Unity.

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

מה תלמדו

איך מגדירים את הפלאגין Google Mobile Ads Unity
איך מטמיעים מודעה בפתיחת אפליקציה באפליקציית Unity

מה תצטרכו

Unity 2018.4 ואילך
‫Xcode 12 ואילך ו-CocoaPods (לפריסה ב-iOS)

מה רמת הניסיון שלך ב-AdMob?

מתחילים

ביניים

מומחים

2. הגדרת סביבת הפיתוח

הורדת הקוד

אחרי שמורידים את קובץ ה-ZIP, מחלצים את התוכן שלו. תיקייה בשם admob-appopen-unity-main תיווצר.

אפשר גם לשכפל את מאגר GitHub משורת הפקודה:

$ git clone https://github.com/googlecodelabs/admob-appopen-unity

המאגר מכיל שתי תיקיות:

‫ starter: קוד התחלתי שתיצרו ב-Codelab הזה.
‫ complete: קוד מלא ל-Codelab הזה.

3. הגדרת אפליקציה שמקושרת ל-AdMob ויחידות מודעות

מכיוון ש-Unity הוא SDK מרובה פלטפורמות, צריך להוסיף אפליקציה ויחידות מודעות גם ל-Android וגם ל-iOS ב-AdMob.

הגדרה ב-Android

כדי להגדיר את האפליקציה ל-Android, צריך להוסיף אפליקציית Android וליצור יחידות של מודעות.

הוספת אפליקציה ל-Android

ב-AdMob console, בתפריט Apps, לוחצים על ADD APP.
בוחרים באפשרות Android בתור הפלטפורמה. כשמוצגת השאלה האם האפליקציה רשומה בחנות אפליקציות נתמכת?, לוחצים על לא.
מזינים AdMob app open ad בשדה של שם האפליקציה.
אין צורך להפעיל את מדדי המשתמשים כדי להשלים את ה-codelab הזה. עם זאת, מומלץ לעשות זאת כדי להבין את התנהגות המשתמשים בצורה מפורטת יותר. לוחצים על הוספה כדי להשלים את התהליך.

יצירה של יחידת מודעות

בתפריט Apps במסוף AdMob, בוחרים באפשרות AdMob app open ad (מודעה בפתיחת האפליקציה ב-AdMob) (Android).
לוחצים על התפריט יחידות של מודעות.

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

בדרך כלל חולפות כמה שעות עד שיחידת מודעות חדשה יכולה להציג מודעות.

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

הגדרה ל-iOS

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

הוספת אפליקציה ל-iOS

ב-AdMob console, בתפריט Apps, לוחצים על ADD APP.
בוחרים באפשרות iOS כפלטפורמה. כשמוצגת השאלה האם האפליקציה רשומה בחנות אפליקציות נתמכת?, לוחצים על לא.
מזינים AdMob app open ad בשדה של שם האפליקציה.
אין צורך להפעיל את מדדי המשתמשים כדי להשלים את ה-codelab הזה. עם זאת, מומלץ לעשות זאת כדי להבין את התנהגות המשתמשים בצורה מפורטת יותר. לוחצים על הוספה כדי להשלים את התהליך.

יצירה של יחידת מודעות

בתפריט Apps במסוף AdMob, בוחרים באפליקציה AdMob inline ads‏ (iOS).
לוחצים על התפריט יחידות של מודעות.

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

בדרך כלל חולפות כמה שעות עד שיחידת מודעות חדשה יכולה להציג מודעות.

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

אופציונלי: שימוש באפליקציית בדיקה וביחידות מודעות של AdMob

אם אתם רוצים לעקוב אחרי ה-codelab במקום ליצור אפליקציה חדשה ויחידות מודעות בעצמכם, אתם יכולים להשתמש במזהה האפליקציה שמקושרת ל-AdMob ובמזהים של יחידות המודעות לבדיקה שמפורטים בטבלאות הבאות.

מזהה אפליקציה ל-Android או מזהה יחידת מודעות

פריט	מזהה אפליקציה/מזהה יחידת מודעות
מזהה האפליקציה שמקושרת ל-AdMob	`ca-app-pub-3940256099942544~3347511713`
מזהה יחידת מודעות	`ca-app-pub-3940256099942544/3419835294`

מזהה אפליקציה ל-iOS או מזהה יחידת מודעות

פריט	מזהה אפליקציה/מזהה יחידת מודעות
מזהה האפליקציה שמקושרת ל-AdMob	`ca-app-pub-3940256099942544~1458002511`
מזהה יחידת מודעות	`ca-app-pub-3940256099942544/5662855259`

מידע נוסף על מודעות בדיקה זמין בתיעוד למפתחים בנושא מודעות בדיקה ל-Android ומודעות בדיקה ל-iOS.

4. הוספה של Google Mobile Ads Unity plugin

השילוב של Google Mobile Ads Unity plugin הוא השלב הראשון לקראת הצגת מודעות AdMob וייצור הכנסות.

הורדת הפלאגין Mobile Ads Unity

התוסף Google Mobile Ads Unity מאפשר למפתחים ב-Unity להציג בקלות מודעות Google Mobile Ads באפליקציות ל-Android ול-iOS. הפלאגין מספק ממשק C# לבקשת מודעות, שמשמש סקריפטים של C# בפרויקט Unity.

אפשר להשתמש בקישור שלמטה כדי להוריד את חבילת Unity של הפלאגין.

פתיחת פרויקט התחלה

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

ייבוא הפלאגין Mobile Ads Unity

בתפריט של עורך Unity, בוחרים באפשרות Assets > Import Package > Custom Package (נכסים > ייבוא חבילה > חבילה מותאמת אישית).
בוחרים את GoogleMobileAds-{VERSION}.unitypackage שהורדתם בשלב הקודם.
מוודאים שכל הקבצים מסומנים ולוחצים על ייבוא.

הגדרת מזהה האפליקציה ב-AdMob

בתפריט Unity Editor, בוחרים באפשרות Assets > Google Mobile Ads > Settings (נכסים > Google Mobile Ads > הגדרות).
מזינים את מזהה האפליקציה שמקושרת ל-AdMob ל-Android ואת מזהה האפליקציה שמקושרת ל-AdMob ל-iOS בכל שדה. אם אתם רוצים לעקוב אחרי ה-codelab במקום ליצור אפליקציה חדשה ויחידות מודעות בעצמכם, צריך להזין את מזהה אפליקציית הבדיקה שמקושרת ל-AdMob באופן הבא.

5. יצירת מחלקה של כלי עזר

יוצרים כיתה חדשה בשם AppOpenAdManager בתיקייה Scripts. המחלקה הזו מנהלת משתנה מופע כדי לעקוב אחרי מודעה שנטענה ואחרי מזהה יחידת המודעות לכל פלטפורמה.

AppOpenAdManager.cs

using System;
using GoogleMobileAds.Api;
using UnityEngine;

public class AppOpenAdManager
{
#if UNITY_ANDROID
    // Test ad unit ID: ca-app-pub-3940256099942544/3419835294
    private const string AD_UNIT_ID = "<YOUR_ANDROID_APPOPEN_AD_UNIT_ID>";
#elif UNITY_IOS
    // Test ad unit ID: ca-app-pub-3940256099942544/5662855259
    private const string AD_UNIT_ID = "<YOUR_IOS_APPOPEN_AD_UNIT_ID>";
#else
    private const string AD_UNIT_ID = "unexpected_platform";
#endif

    private static AppOpenAdManager instance;

    private AppOpenAd ad;

    private bool isShowingAd = false;

    public static AppOpenAdManager Instance
    {
        get
        {
            if (instance == null)
            {
                instance = new AppOpenAdManager();
            }

            return instance;
        }
    }

    private bool IsAdAvailable
    {
        get
        {
            return ad != null;
        }
    }

    public void LoadAd()
    {
        // TODO: Load an app open ad.
    }
}

טעינת מודעה

טעינה של מודעה מתבצעת באמצעות השיטה הסטטית AppOpenAd.LoadAd(). שיטת הטעינה דורשת מזהה יחידת מודעות, מצב ScreenOrientation, אובייקט AdRequest ו-handler של השלמה שמופעל כשטעינת המודעה מצליחה או נכשלת.

אובייקט AppOpenAd שנטען מסופק כפרמטר ב-handler של ההשלמה. מטמיעים את ה-method‏ LoadAd() באופן הבא.

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    public void LoadAd()
    {
        AdRequest request = new AdRequest.Builder().Build();

        // Load an app open ad for portrait orientation
        AppOpenAd.LoadAd(AD_UNIT_ID, ScreenOrientation.Portrait, request, ((appOpenAd, error) =>
        {
            if (error != null)
            {
                // Handle the error.
                Debug.LogFormat("Failed to load the ad. (reason: {0})", error.LoadAdError.GetMessage());
                return;
            }

            // App open ad is loaded.
            ad = appOpenAd;
        }));
    }
}

הצגת המודעה

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

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    public void ShowAdIfAvailable()
    {
        if (!IsAdAvailable || isShowingAd)
        {
            return;
        }

        ad.OnAdDidDismissFullScreenContent += HandleAdDidDismissFullScreenContent;
        ad.OnAdFailedToPresentFullScreenContent += HandleAdFailedToPresentFullScreenContent;
        ad.OnAdDidPresentFullScreenContent += HandleAdDidPresentFullScreenContent;
        ad.OnAdDidRecordImpression += HandleAdDidRecordImpression;
        ad.OnPaidEvent += HandlePaidEvent;

        ad.Show();
    }

    private void HandleAdDidDismissFullScreenContent(object sender, EventArgs args)
    {
        Debug.Log("Closed app open ad");
        // Set the ad to null to indicate that AppOpenAdManager no longer has another ad to show.
        ad = null;
        isShowingAd = false;
        LoadAd();
    }

    private void HandleAdFailedToPresentFullScreenContent(object sender, AdErrorEventArgs args)
    {
        Debug.LogFormat("Failed to present the ad (reason: {0})", args.AdError.GetMessage());
        // Set the ad to null to indicate that AppOpenAdManager no longer has another ad to show.
        ad = null;
        LoadAd();
    }

    private void HandleAdDidPresentFullScreenContent(object sender, EventArgs args)
    {
        Debug.Log("Displayed app open ad");
        isShowingAd = true;
    }

    private void HandleAdDidRecordImpression(object sender, EventArgs args)
    {
        Debug.Log("Recorded ad impression");
    }

    private void HandlePaidEvent(object sender, AdValueEventArgs args)
    {
        Debug.LogFormat("Received paid event. (currency: {0}, value: {1}",
                args.AdValue.CurrencyCode, args.AdValue.Value);
    }
}

התייחסות לתפוגה של מודעות

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

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

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    // TODO: Add loadTime field
    private DateTime loadTime;

    private bool IsAdAvailable
    {
        get
        {
            // TODO: Consider ad expiration
            return ad != null && (System.DateTime.UtcNow - loadTime).TotalHours < 4;
        }
    }

    public void LoadAd()
    {
        if (IsAdAvailable)
        {
            return;
        }

        AdRequest request = new AdRequest.Builder().Build();
        AppOpenAd.LoadAd(AD_UNIT_ID, ScreenOrientation.Portrait, request, ((appOpenAd, error) =>
        {
            if (error != null)
            {
                Debug.LogFormat("Failed to load the ad. (reason: {0})", error.LoadAdError.GetMessage());
                return;
            }

            ad = appOpenAd;
            Debug.Log("App open ad loaded");

            // TODO: Keep track of time when the ad is loaded.
            loadTime = DateTime.UtcNow;
        }));
    }
}

6. עדכון הסצנה כדי לטעון או להציג את המודעה

מעדכנים את השיטה Start() בכיתה MainScene כדי לטעון מודעה לפתיחת אפליקציה כשהסצנה מתחילה.

כדי לקבל התראות על אירועים של העברת האפליקציה לחזית, מומלץ להאזין ל-singleton של AppStateEventNotifier. הטמעת AppStateEventNotifier.AppStateChanged delegate תאפשר לאפליקציה לקבל התראות על אירועים של הפעלת האפליקציה והעברתה לחזית, ולהציג את המודעה.

MainScene.cs

using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
using UnityEngine;

public class MainScene : MonoBehaviour
{
    public void Start()
    {
        // TODO: Request an app open ad.
        MobileAds.Initialize((initStatus) =>
        {
            AppOpenAdManager.Instance.LoadAd();
            AppStateEventNotifier.AppStateChanged += OnAppStateChanged;
        });
    }

    public void OnAppStateChanged(AppState state)
    {
        if (state == AppState.Foreground)
        {
            // TODO: Show an app open ad if available.
            AppOpenAdManager.Instance.ShowAdIfAvailable();
        }
    }
}

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

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

7. הכול מוכן!

סיימתם את ה-Codelab. אפשר למצוא את הקוד המלא של ה-Codelab הזה בתיקייה complete.