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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

(מומלץ) ייבוא פריטי מידע שנוצרו מראש מ-Android או מ-iOS

ייבוא של פריטי מידע שנוצרו מראש מ-Maven או CocoaPods באמצעות External Dependency Manager for Unity. פלאגין זה כלול בפלאגין GoogleMobileAds.

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

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

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

Assets/AdPub/Editor/AdPubDependencies.xml

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

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

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

Assets > External Dependency Manager > Android Resolver > Force Resolve

ייבוא של יישומי פלאגין של AAR וספריות Android

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

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

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

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

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

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

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

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

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

1. הגדרת ממשק משותף ללקוחות הפלטפורמה
2. הטמעה של לקוח ברירת מחדל בפלטפורמות לא נתמכות
3. הטמעת לקוח Android להפעלת שיטות Android
4. יישום לקוח iOS לקריאת שיטות iOS
5. מטמיעים יצרן לקוח כדי לעבור באופן מותנה בין לקוחות 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 שפשוט מתעדת את שם ה-method. השתמשו בהטמעה הזו בעורך 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() שהוגדרה למעלה. כדי לטפל בקריאות ל-method מ-Unity, צריך ליצור את AdPubClientBridge.m עם ה-method C GADUAdPubSetHasUserConsent() ולהפעיל את 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 הסטטי של 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

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

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

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

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