מתחילים

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

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

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

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

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

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

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

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

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

OnNativeAdLoaded

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

OnAdFailedToLoad

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

טעינת המודעה

אחרי שמסיימים ליצור AdLoader, מפעילים את השיטה 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;
}

שימו לב: הגישה לנכסים שמצורפים למודעות צריכה להתבצע רק בשרשור הראשי, למשל מהשיטה 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;
}