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

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

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

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

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

• הגדרה של Google Mobile Ads Unity Plugin התוסף Google Mobile Ads Unity צריך להיות כבר מיובא לאפליקציית 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 באמצעות 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 וספריות של 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

לאחר מכן, מטמיעים את ה-method‏ GADUAdPubSetHasUserConsent() שהוגדר למעלה. יוצרים AdPubClientBridge.m באמצעות method‏ CGADUAdPubSetHasUserConsent() כדי לטפל בקריאה ל-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.