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

אירועים בהתאמה אישית מאפשרים לבעלי אפליקציות שמשתמשים בתהליך בחירת הרשת (Mediation) של AdMob להוסיף תהליך בחירת רשת (Mediation) ב-Waterfall לרשת מודעות של צד שלישי שאינה אחת מרשתות המודעות הנתמכות. במדריך הזה נסביר איך להשתמש באירוע מותאם אישית קיים שנוצר ל-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 SDK של צד שלישי
• אירוע בהתאמה אישית של צד שלישי ב-Android
• SDK של מודעות של צד שלישי ל-iOS
• אירוע מותאם אישית של צד שלישי ב-iOS

סוגי ספריות

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

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

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

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

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

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

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

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

Assets/AdPub/Editor/AdPubDependencies.xml

בשלב הבא, מגדירים את יחסי התלות בקובץ AdPubDependencies.xml. הכללים להגדרת הייבוא מפורטים במאמר תחילת השימוש ב-External Dependency Manager ב-Unity. קטע הקוד הבא כולל את ה-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

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

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

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

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

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

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

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

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

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

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

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

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

AndroidiOS

package com.adpub.android;

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

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

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

יוצרים ממשק IAdPubClient עם method שמייצג את ה-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 כדי לקרוא ל-method הסטטי setHasUserConsent() של Android.

מאחר שכיולות העזר של Java ב-Android זמינות רק במהלך זמן הריצה של 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

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

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

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

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