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

1. מבוא

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

מה תפַתחו

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

6338548c3f73e7cf.gif

אם נתקלתם בבעיות (באגים בקוד, שגיאות דקדוק, ניסוח לא ברור וכן הלאה) במהלך העבודה ב-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

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

  • android_studio_folder.png סימן לתחילת פעולה: קוד ההתחלה שתיצרו ב-Codelab הזה.
  • android_studio_folder.png הושלם: הקוד הושלם עבור ה-Codelab הזה.

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

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

הגדרה ל-Android

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

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

  1. במסוף AdMob, לוחצים על הוספת אפליקציה בתפריט אפליקציות.
  2. בוחרים את Android כפלטפורמה. כשמוצגת השאלה האם האפליקציה רשומה בחנות אפליקציות נתמכת?, לוחצים על לא.
  3. מזינים AdMob app open ad בשדה של שם האפליקציה.
  4. אין צורך להפעיל מדדי משתמשים כדי להשלים את ה-Codelab הזה. עם זאת, מומלץ לעשות זאת כי כך תוכלו להבין את התנהגות המשתמשים בצורה מפורטת יותר. לוחצים על הוספה כדי להשלים את התהליך.

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

  1. בוחרים באפשרות מודעה בפתיחת אפליקציה ב-AdMob (Android) בתפריט אפליקציות במסוף AdMob.
  2. לוחצים על התפריט יחידות של מודעות.

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

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

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

הגדרה ל-iOS

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

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

  1. במסוף AdMob, לוחצים על הוספת אפליקציה בתפריט אפליקציות.
  2. בוחרים את iOS כפלטפורמה. כשמוצגת השאלה האם האפליקציה רשומה בחנות אפליקציות נתמכת?, לוחצים על לא.
  3. מזינים AdMob app open ad בשדה של שם האפליקציה.
  4. אין צורך להפעיל מדדי משתמשים כדי להשלים את ה-Codelab הזה. עם זאת, מומלץ לעשות זאת כי כך תוכלו להבין את התנהגות המשתמשים בצורה מפורטת יותר. לוחצים על הוספה כדי להשלים את התהליך.

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

  1. בוחרים באפליקציה מודעות מוטבעות ב-AdMob (iOS) בתפריט אפליקציות במסוף AdMob.
  2. לוחצים על התפריט יחידות של מודעות.

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

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

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

אופציונלי: שימוש באפליקציה וביחידות המודעות של 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

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

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

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

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

פתיחת הפרויקט לתחילת העבודה

  1. מפעילים את Unity Hub.
  2. בכרטיסייה פרויקטים, לוחצים על הלחצן הוספה.
  3. עוברים אל התיקייה שממנה חילצתם את הקוד שהורדתם בשלב 'הגדרת סביבת פיתוח'.
  4. פותחים את התיקייה מתחילים.
  5. הפרויקט להתחלה יופיע ברשימת הפרויקטים. לוחצים על הפרויקט כדי לפתוח אותו ב-Unity Editor.

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

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

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

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

8890521e199b1090.png

5. יצירת מחלקה של שירותים

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

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 של ההשלמה. מטמיעים את השיטה 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 כדי לטעון מודעה בפתיחת אפליקציה כשהסצנה מתחילה.

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

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();
        }
    }
}

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

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

6338548c3f73e7cf.gif

7. הכול מוכן!

סיימתם את ה-Codelab. הקוד שהושלם עבור Codelab הזה מופיע בתיקייה android_studio_folder.pngcomplete.