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

בחירת פלטפורמה: Android (בטא) Android iOS Unity

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

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

לפני שממשיכים, צריך:

• הגדרה של Google Mobile Ads Unity Plugin צריך לייבא את הפלאגין Google Mobile Ads Unity לאפליקציית Unity.

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

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

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

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

איך ממלאים פרמטרים
שם הכיתה (iOS)	ב-iOS, מזינים את שם המחלקה שמטמיעה את האירוע המותאם אישית. אם הטמעתם את המחלקה ב-Swift, צריך להוסיף לשם המחלקה תחילית שתכלול את שם המודול של האפליקציה או ה-framework שלה (לדוגמה, appName.className). אם יש כמה יעדים בפרויקט או אם שם הפרויקט שונה משם היעד, צריך לציין את שם היעד. אם שם היעד הוא appName_targetName.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 for 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 וספריות של Android כדי לקבל הוראות להכללת הקבצים האלה בפרויקט Unity.

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

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

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

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

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

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

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

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

1. הגדרת ממשק משותף ללקוחות הפלטפורמה
2. הטמעה של לקוח ברירת מחדל בפלטפורמות שלא נתמכות
3. הטמעה של לקוח Android לקריאה לשיטות של Android
4. הטמעה של לקוח iOS להתקשרות לשיטות 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 method להחזרת ההטמעה הנכונה של הלקוח

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