יצירת אירועים מותאים אישית

אירועים בהתאמה אישית מאפשרים לבעלי אפליקציות שמשתמשים בתהליך בחירת הרשת (Mediation) ב-AdMob להוסיף לרשימת הרשתות בתהליך בחירת הרשת רשת מודעות של צד שלישי שלא נכללת ברשימת רשתות המודעות הנתמכות. במדריך הזה מוסבר איך להשתמש באירוע מותאם אישית קיים שנוצר עבור Android ו-iOS בפרויקט Unity.

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

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

• מתאמי אירועים מותאמים אישית שכבר נוצרו ל-Android ול-iOS. כדי ליצור מתאמי אירועים מותאמים אישית, אפשר לעיין במדריכים שלנו בנושא אירועים מותאמים אישית ב-Android וב-iOS.

הגדרת אירוע מותאם אישית

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

צילום המסך הזה מציג כמה דוגמאות להגדרות של אירועים בהתאמה אישית:

איך ממלאים פרמטרים
שם הכיתה (iOS)	ב-iOS, מזינים את שם המחלקה שמטמיעה את האירוע המותאם אישית. אם הטמעתם את המחלקה ב-Swift, צריך להוסיף לשם המחלקה תחילית שתכלול את שם המודול של האפליקציה או ה-framework שלה (לדוגמה, appName.className). אם יש כמה יעדים בפרויקט או אם שם הפרויקט שונה משם היעד, צריך לציין את שם היעד. עם שם היעד, זה ייראה כך: appName_targetName.className. בנוסף, חשוב להחליף כל תו שאינו אלפאנומרי, כמו מקפים, בקו תחתון.
שם הכיתה (Android)	ב-Android, חשוב לוודא שהערך שאתם מציינים עבור Class Name הוא שם המחלקה המלא ב-Android (לדוגמה, com.google.ads.mediation.sample.customevent.SampleCustomEvent).
תווית	מזינים שם ייחודי לאירוע.
פרמטר	אם רוצים להעביר ארגומנט מחרוזת לאירוע מותאם אישית, למשל מזהה של יחידת מודעות.

ייבוא ספריות של אירועים מותאמים אישית

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

• ‫Android third-party SDK
• אירוע בהתאמה אישית של צד שלישי ב-Android
• ‫iOS third-party ad SDK
• אירוע מותאם אישית של צד שלישי ב-iOS

סוגים של ספריות

יש כמה דרכים לייבא קוד של Android או iOS לפרויקט Unity, כולל:

• ייבוא של ארטיפקטים מוכנים מראש של Android או iOS באמצעות External Dependency Manager ל-Unity
• ייבוא פלאגינים של AAR וספריות Android
• ייבוא של קובצי מקור ב-Java וב-Kotlin
• ייבוא קובצי מקור וספריות סטטיות של iOS

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

(מומלץ) ייבוא של ארטיפקטים מוכנים מראש של Android או iOS

אפשר לייבא ארטיפקטים מוכנים מראש מ-Maven או מ-CocoaPods באמצעות מנהל התלות החיצוני ל-Unity. התוסף הזה כלול בתוסף GoogleMobileAds.

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

• הקובץ חייב להיות בתיקייה /Editor/.
• שם הקובץ צריך להסתיים ב-Dependencies.xml.

לדוגמה, כדי לייבא מתאמים של אירועים מותאמים אישית לרשת מודעות היפותטית בשם AdPub, יוצרים את הקובץ:

Assets/AdPub/Editor/AdPubDependencies.xml

לאחר מכן, מגדירים את יחסי התלות בקובץ AdPubDependencies.xml. כללים להגדרת הייבוא מפורטים במאמר External Dependency Manager for Unity Getting Started. קטע הקוד הבא כולל את ה-SDK ל-Android ול-iOS ואת ספריות האירועים המותאמים אישית עבור רשת המודעות ההיפותטית AdPub.

Assets/AdPub/Editor/AdPubDependencies.xml

<dependencies>
  <androidPackages>
    <androidPackage spec="com.adpub.android:adpub-sdk:1.0.0" />
    <androidPackage spec="com.adpub.android:adpub-custom-event:1.0.0">
      <repositories>
        <repository>https://repo.maven.apache.org/maven2/</repository>
        <repository>https://dl.google.com/dl/android/maven2/</repository>
      </repositories>
    </androidPackage>
  </androidPackages>
  <iosPods>
    <iosPod name="AdPubSDK" version="1.0" />
    <iosPod name="AdPubCustomEvent" version="1.0">
      <sources>
        <source>https://github.com/CocoaPods/Specs</source>
      </sources>
    </iosPod>
  </iosPods>
</dependencies>

אם לארטיפקט של האירוע המותאם אישית כבר יש תלות ב-SDK הנדרש של רשת המודעות, לא צריך להגדיר את התלות ב-SDK באופן מפורש: דוגמה

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

Assets > External Dependency Manager > Android Resolver > Force Resolve

ייבוא פלאגינים של AAR וספריות Android

‫Unity תומך בייבוא של קובצי *.aar וגם בפרויקטים של ספריות Android. אם אירוע מותאם אישית ב-Android ארוז בצורה הזו, במאמר AAR plug-ins and Android Libraries מוסבר איך לכלול את הקבצים האלה בפרויקט Unity.

ייבוא קובצי מקור של Java ו-Kotlin

החל מ-Unity 2018.2 ואילך, אם קוד האירוע המותאם אישית של Android כולל קובצי *.java או *.kt לא מהודרים, אפשר להשתמש בקבצים של Java או Kotlin כמקורות כפלאגינים.

ייבוא קובצי מקור וספריות סטטיות של iOS

‫Unity תומך בפריטי מידע שנוצרו בתהליך פיתוח (Artifact) מסוג *.framework, *.h וקבצי מקור מסוג *.m. הסבר על ייבוא של ארטיפקטים וקבצי מקור של iOS מופיע במדריך של Unity בנושא תוספים מקוריים.

בדיקת אירועים בהתאמה אישית באמצעות הכלי לבדיקת מודעות

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

(אופציונלי) קריאה לשיטות מקומיות של SDK של צד שלישי מסקריפטים של C# ‎

יכול להיות שלערכות SDK של רשתות מודעות מצד שלישי יש דרישות מיוחדות שדורשות קריאה ישירה לשיטות של Android או iOS. כך קוראים ל-methods האלה ישירות:

1. הגדרת ממשק משותף ללקוחות הפלטפורמה
2. הטמעה של לקוח ברירת מחדל בפלטפורמות שלא נתמכות
3. הטמעה של לקוח Android לקריאה לשיטות של Android
4. הטמעה של לקוח iOS להתקשרות ל-methods של iOS
5. הטמעה של client factory כדי לעבור באופן מותנה בין לקוחות iOS ו-Android
6. הגדרת API לגישה לכל הפונקציות של ערכות SDK של רשתות מודעות של צד שלישי

בקטע הבא מוסבר איך השלבים האלה מיושמים ברשת פרסום היפותטית בשם AdPub ב-API של C# שיכול להפעיל את השיטות ב-Android וב-iOS:

Android

package com.adpub.android;

public class AdPubSdk
{
    public static void setHasUserConsent(boolean hasUserConsent);
}

iOS

@interface AdPubSdk : NSObject
+ (void)setHasUserConsent:(BOOL)hasUserConsent;
@end

הגדרת ממשק משותף ללקוחות הפלטפורמה

יוצרים ממשק IAdPubClient עם שיטה שמייצגת את ה-API הבסיסי של Android ו-iOS.

Assets/AdPub/Common/IAdPubClient.cs

namespace AdPub.Common
{
    public interface IAdPubClient
    {
        ///<summary>
        /// Sets a flag indicating if the app has user consent for advertisement.
        ///</summary>
        void SetHasUserConsent(bool hasUserConsent);
    }
}

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

יוצרים מחלקה DefaultClient שמטמיעה את הממשק IAdPubClient ופשוט רושמת ביומן את שם השיטה. משתמשים בהטמעה הזו בעורך Unity ובכל הפלטפורמות מלבד Android או iOS.

Assets/AdPub/Common/DefaultClient.cs

namespace AdPub.Common
{
    public class DefaultClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
            Debug.Log("SetHasUserConsent was called.");
        }
    }
}

הטמעה של לקוח פלטפורמת iOS

יוצרים מחלקה iOSAdPubClient שמטמיעה את הממשק IAdPubClient ב-iOS. ההטמעה הזו משתמשת ב-InteropServices כדי לקרוא ל-method‏ setHasUserConsent() במחלקה AdPubSdk ב-iOS.

Assets/AdPub/Platforms/iOS/iOSAdPubClient.cs

// Wrap this class in a conditional operator to make sure it only runs on iOS.
#if UNITY_IOS

// Reference InteropServices to include the DLLImportAttribute type.
using System.Runtime.InteropServices;

using AdPub.Common;

namespace AdPub.Platforms.Android
{
    public class iOSAdPubClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
            GADUAdPubSetHasUserConsent(hasUserConsent);
        }

        [DllImport("__Internal")]
        internal static extern void GADUAdPubSetHasUserConsent(bool hasUserConsent);
    }
}
#endif

לאחר מכן, מטמיעים את השיטה GADUAdPubSetHasUserConsent() שהוגדרה למעלה. יוצרים AdPubClientBridge.m עם method‏ C GADUAdPubSetHasUserConsent() כדי לטפל בקריאה ל-method מ-Unity, ומפעילים את AdPubSDK.

‫AdPubClientBridge הוא קובץ מקור ל-iOS, והוא צריך להיות בתיקייה Plugins/iOS, כמו שמוסבר במדריך של Unity לתוספים מקוריים.

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

void GADUAdPubSetHasUserConsent(BOOL hasUserConsent) {
  [AdPubSDK setHasUserConsent:hasUserConsent];
}

הטמעה של לקוח בפלטפורמת Android

יוצרים מחלקה AndroidAdPubCient שמטמיעה את הממשק IAdPubClient ב-Android. ההטמעה הזו משתמשת ב מחלקות העזר של Android Java כדי לקרוא לשיטה הסטטית של Android‏ setHasUserConsent().

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

Assets/AdPub/Platforms/Android/AndroidAdPubClient.cs

// Wrap this class in a conditional operator to make sure it only runs on Android.
#if UNITY_ANDROID

// Reference the UnityEngine namespace which contains the JNI Helper classes.
using UnityEngine;

using AdPub.Common;

namespace AdPub.Platforms.Android
{
    public class AndroidAdPubClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
             // Make a reference to the com.adpub.AdPubSDK.
            AndroidJavaClass adPubSdk = new AndroidJavaClass("com.adpub.AdPubSdk");

            // Call the native setHasUserConsent method of com.adpub.AdPubSDK.
            adPubSdk.CallStatic("setHasUserConsent", hasUserConsent);
        }
    }
}
#endif

יצירת שיטת factory כדי להחזיר את הטמעת הלקוח הנכונה

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

Assets/AdPub/Common/AdPubClientFactory.cs

namespace AdPub.Common
{
    public class AdPubClientFactory
    {
        // Return the correct platform client.
        public static IAdPubClient GetClient()
        {
#if   !UNITY_EDITOR && UNITY_ANDROID
            return new AdPub.Platforms.Android.AndroidAdPubClient();
#elif !UNITY_EDITOR && UNITY_IOS
            return new AdPub.Platforms.iOS.iOSAdPubClient();
#else
            // Returned for the Unity Editor and unsupported platforms.
            return new DefaultClient();
#endif
        }
    }
}

הגדרת API ציבורי לכל שיטת ממשק

יוצרים מחלקה AdPubApi עם קריאות ל-method לכל method של לקוח בממשק IAdPubClient. במחלקת AdPubClientFactory נעשה שימוש ב-IAdPubClient כדי לקבל מופע של IAdPubClient ולקרוא ללקוח הזה כדי להשתמש בפונקציות הבסיסיות של ה-SDK.

Assets/AdPub/AdPubApi.cs

using AdPub.Common;

namespace AdPub
{
    public class AdPubApi
    {
        private static readonly IAdPubClient client = GetAdPubClient();

        // Returns the correct client for the current runtime platform.
        private static IAdPubClient GetAdPubClient()
        {
            return AdPubClientFactory.GetClient();
        }

        // Sets the user consent using the underlying SDK functionality.
        public static void SetHasUserConsent(bool hasUserConsent)
        {
            client.SetHasUserConsent(hasUserConsent);
        }
    }
}

שליחת קריאה ל-API החדש שהגדרתם

כך אפשר להפעיל את ה-API שהוגדר למעלה:

Assets/Scripts/AdPubController.cs

using UnityEngine;
using AdPub;

public class AdPubController : MonoBehaviour
{
    // TODO: Get consent from the user and update this userConsent field.
    public bool userConsent;

    // Called on startup of the GameObject it's assigned to.
    public void Start()
    {
        // Pass the user consent to AdPub.
        AdPubApi.SetHasUserConsent(userConsent);
    }
}

דוגמאות נוספות למתאמים של רשתות מודעות של צד שלישי

במאגר Github של Google Mobile Ads Unity plug-in אפשר למצוא דוגמאות נוספות למתאמי צד שלישי של תהליך בחירת הרשת (Mediation) שמטמיעים ממשקי API של C# ‎ כדי לעטוף קריאות לשיטות של iOS ו-Android.