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

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

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

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

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

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

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

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

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

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

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

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

Assets/AdPub/Editor/AdPubDependencies.xml

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

אם ארטיפקט של האירוע המותאם אישית כבר תלוי במודעה הנדרשת Network 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 ל-Native יישומי פלאגין.

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

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

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

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

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

הקטע הבא מראה איך השלבים האלה מיושמים עבור מודל היפותטי רשת מודעות בשם "AdPub" ב-API של C# שיכול לשלוח קריאה ל-methods ב-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() שהוגדרה למעלה. יצירת AdPubClientBridge.m עם אמצעי תשלום 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 helper כיתות כדי לקרוא לשיטה הסטטית של Android setHasUserConsent().

כי כיתות העוזר של Android Java זמינות רק במהלך Android זמן ריצה, ניתן למנוע שגיאות הידור באמצעות המהדר (compiler) UNITY_ANDROID הוראה ל-wrap הכיתה כפי שמוצג בקטע הקוד. לחלופין, אפשר להשתמש ב-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, בהתאם לפלטפורמת זמן הריצה. בכיתה הזו משתמשים מהדר (compiler) הוראות כדי מחזירה את לקוח 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 ציבורי לכל method של ממשק

ליצור מחלקה ב-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 לנייד ב-Unity מאגר לדוגמאות נוספות של מתאמים לבחירת רשת (Mediation) של צד שלישי שמטמיעים ממשקי API של C# כדי לארוז שיחות לשיטות iOS ו-Android.