אני רוצה לנסות

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

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

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

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

טעינת פורמטים של מודעות מותאמות

מודעות מותאמות נטענות דרך הכיתה AdLoader. יש לה מחלקה AdLoader.Builder משלה, שאפשר להתאים אישית במהלך היצירה. ה-method ForNativeAd() מגדירה את AdLoader לטיפול במודעות מותאמות.

private void RequestNativeAd() {
    AdLoader adLoader = new AdLoader.Builder(INSERT_AD_UNIT_HERE)
        .ForNativeAd()
        .Build();
}

הרשמה לאירועי מודעות של AdLoader

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

OnNativeAdLoaded

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

OnAdFailedToLoad

מופעל כשמודעה מותאמת לא נטענת.

טעינת המודעה

אחרי שמסיימים ליצור את ה-AdLoader, קוראים ל-method LoadAd() כדי לבקש מודעה:

adLoader.LoadAd(new AdRequest.Builder().Build());

מאחדים את הבקשה להצגת מודעה

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

private void RequestNativeAd() {
    AdLoader adLoader = new AdLoader.Builder(INSERT_AD_UNIT_HERE)
        .ForNativeAd()
        .Build();
    adLoader.OnNativeAdLoaded += this.HandleNativeAdLoaded;
    adLoader.OnAdFailedToLoad += this.HandleAdFailedToLoad;
    adLoader.LoadAd(new AdRequest.Builder().Build());
}

טיפול בטעינות מודעות שנכשלו

האירוע OnAdFailedToLoad הוא מסוג EventHandle<AdFailedToLoadEventArgs>. בהמשך מוצג ניתוח של הסיבה לכשל בטעינת המודעות מהאירוע הזה.

private void RequestNativeAd() {
    ...
    adLoader.OnAdFailedToLoad += this.HandleNativeAdFailedToLoad;
}

private void HandleNativeAdFailedToLoad(object sender, AdFailedToLoadEventArgs args) {
    Debug.Log("Native ad failed to load: " + args.Message);
}

הצגת מודעה מותאמת

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

טיפול בכמות המודעות

האירוע OnNativeAdLoaded הוא מסוג EventHandler<NativeAdEventArgs>. אפשר לאחזר את המודעה, בתוך אובייקט NativeAd, מ-NativeAdEventArgs באופן הבא:

private NativeAd nativeAd;
...
private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) {
    Debug.Log("Native ad loaded.");
    this.nativeAd = args.nativeAd;
}

אחזור נכסים שמצורפים למודעות מותאמות

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

private bool nativeAdLoaded;
private NativeAd nativeAd;

void Update() {
    ...

    if (this.nativeAdLoaded) {
        this.nativeAdLoaded = false;
        // Get Texture2D for the icon asset of native ad.
        Texture2D iconTexture = this.nativeAd.GetIconTexture();

        // Get string for headline asset of native ad.
        string headline = this.nativeAd.GetHeadlineText();
    }
}

private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) {
    Debug.Log("Native ad loaded.");
    this.nativeAd = args.nativeAd;
    this.nativeAdLoaded = true;
}

שימו לב שצריך לגשת לנכסים שמצורפים למודעות רק ב-thread הראשי. לדוגמה, באמצעות ה-method Update() של סקריפט ב-Unity. כמו כן, לא בטוח שהנכסים הבאים יהיו קיימים, וצריך לבדוק אותם לפני שהם מוצגים:

  • GetStarRating()
  • GetStore()
  • GetPrice()
  • GetAdvertiser()
  • GetIconTexture()

נכס AdChoices

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

רישום GameObjects עבור נכס מודעה

כדי שהנכס שמצורף למודעה יוצג באפליקציה ל-Unity, צריך לרשום את השדה GameObject. אם הרישום יבוצע בהצלחה, השיטה שמשמשת לרישום GameObject תחזיר את הערך bool. בשביל List<GameObject>, ה-method מחזירה int שמציין את הספירה של GameObject שנרשמה בהצלחה.

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

if (!this.nativeAd.RegisterIconImageGameObject(icon))
{
    // Handle failure to register the icon ad asset.
}

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

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

// Create GameObject that will display the headline ad asset.
GameObject headline = new GameObject();
headline.AddComponent<TextMesh>();
headline.GetComponent<TextMesh>().characterSize = 0.5 f;
headline.GetComponent<TextMesh>().anchor = TextAnchor.MiddleCenter;
headline.GetComponent<TextMesh>().color = Color.black;

// Get string of the headline asset.
string headlineText = this.nativeAd.GetHeadlineText();
headline.GetComponent<TextMesh>().text = headlineText;

// Add box collider to the GameObject which will automatically scale.
headline.AddComponent<BoxCollider>();

הדגמה (דמו)

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

private GameObject icon;
private bool nativeAdLoaded;
private NativeAd nativeAd;
...
void Update() {
    ...

    if (this.nativeAdLoaded) {
        this.nativeAdLoaded = false;
        // Get Texture2D for icon asset of native ad.
        Texture2D iconTexture = this.nativeAd.GetIconTexture();

        icon = GameObject.CreatePrimitive(PrimitiveType.Quad);
        icon.transform.position = new Vector3(1, 1, 1);
        icon.transform.localScale = new Vector3(1, 1, 1);
        icon.GetComponent<Renderer>().material.mainTexture = iconTexture;

        // Register GameObject that will display icon asset of native ad.
        if (!this.nativeAd.RegisterIconImageGameObject(icon))
        {
            // Handle failure to register ad asset.
        }
    }
}
...

private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) {
    Debug.Log("Native ad loaded.");
    this.nativeAd = args.nativeAd;
    this.nativeAdLoaded = true;
}