إنشاء أحداث مخصّصة

تتيح الأحداث المخصّصة للناشرين الذين يستخدمون توسّط AdMob إضافة توسّط العرض الإعلاني بدون انقطاع لشبكة مواقع إعلانية تابعة لجهة خارجية ليست من شبكات المواقع الإعلانية المتوافقة. يوضّح هذا الدليل كيفية استخدام حدث مخصّص حالي تم إنشاؤه لنظامَي التشغيل Android و iOS في مشروع Unity.

المتطلبات الأساسية

• أكمِل البدء. يجب أن يكون قد تم استيراد المكوّن الإضافي لإعلانات Google على الأجهزة الجوّالة في Unity تطبيقك.

• محوِّلات الأحداث المخصّصة التي تم إنشاؤها مسبقًا لنظامَي التشغيل Android وiOS لإنشاء محوِّلات أحداث مخصّصة، يُرجى الرجوع إلى أدلة الأحداث المخصّصة على Android و iOS.

تحديد حدث مخصّص

لكي يشارك حدث مخصّص في التوسّط، يجب تحديده في واجهة ويب AdMob. أضِف حدثًا مخصّصًا إلى كلٍّ من مجموعة التوسّط على Android ومجموعة التوسّط على iOS.

تعرض لقطة الشاشة هذه بعض نماذج إعدادات الأحداث المخصّصة:

كيفية ملء المَعلمات
اسم الفئة (iOS)	بالنسبة إلى نظام التشغيل iOS، أدخِل اسم الفئة التي تنفِّذ الحدث المخصّص. في حال تنفيذ فئتك باستخدام Swift، عليك إضافة بادئة إلى اسم الفئة باسم وحدة إطار العمل / التطبيق (مثل 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 باستخدام مدير الملحقات الخارجي في Unity. يتم تضمين هذا المكوّن الإضافي مع المكوّن الإضافي GoogleMobileAds.

لاستيراد العناصر الحالية، أنشئ ملفّ إعدادات لتحديد عمليات الاستيراد. يجب استيفاء المتطلبات التالية لملف الترجمة والمسار:

• يجب أن يكون الملف متوفّرًا في المجلد /Editor/.
• يجب أن ينتهي اسم الملف بـ Dependencies.xml.

على سبيل المثال، لاستيراد محوِّلات الأحداث المخصّصة لشبكة مواقع إعلانية افتراضية اسمها AdPub، أنشئ الملف:

Assets/AdPub/Editor/AdPubDependencies.xml

بعد ذلك، حدِّد التبعيات داخل ملف AdPubDependencies.xml. يمكن العثور على قواعد ضبط عمليات الاستيراد في مقالة بدء استخدام "مدير التبعيات الخارجية" في 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 المطلوبة لشبكة المواقع الإعلانية، لن تحتاج إلى تحديد هذا الاعتماد صراحةً: مثال

يتتبّع "مدير التبعيات الخارجية" تلقائيًا تغييرات الإعدادات ويحلّ التبعيات. يمكنك أيضًا تنفيذ الدقة اليدوية باستخدام الأمر التالي في القائمة:

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. يمكنك الاطّلاع على دليل Unity الخاص بالمكونات المضمّنة الأصلية للتعرّف على كيفية استيراد مواد عرض وملفّات المصدر في نظام التشغيل iOS.

اختبار الأحداث المخصّصة باستخدام "أداة فحص الإعلانات"

يمكن استخدام أداة فحص الإعلانات لاختبار ما إذا تم استيراد الأحداث المخصّصة بشكل صحيح إلى تطبيقك. يمكن فتح أداة Ad inspector باستخدام الإيماءات فقط أو آليًا باستخدام الحد الأدنى من الرموز البرمجية.

(اختياري) استدعاء طرق حزمة تطوير البرامج (SDK) الأصلية التابعة لجهة خارجية من النصوص البرمجية C#

قد يكون لحِزم SDK لشبكات الإعلانات التابعة لجهات خارجية متطلبات خاصة تتطلّب استدعاء طرق Android أو iOS مباشرةً. في ما يلي عملية استدعاء هذه الطرق بشكل مباشر:

1. تحديد واجهة مشتركة لعملاء المنصة
2. تنفيذ برنامج عميل تلقائي للمنصات غير المتوافقة
3. تنفيذ برنامج Android client لاستدعاء طُرق Android
4. تنفيذ برنامج تشغيل iOS لاستدعاء طرق iOS
5. تنفيذ عميل مصنع للتبديل مشروطًا بين عملاء iOS وAndroid
6. تحديد واجهة برمجة تطبيقات للوصول إلى جميع وظائف حزمة تطوير البرامج (SDK) لشبكة الإعلانات التابعة لجهة خارجية

يوضّح القسم التالي كيفية تنفيذ هذه الخطوات لشبكة إعلانية افتراضية تدعى "AdPub" في واجهة برمجة تطبيقات 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 باستخدام طريقة تمثّل واجهة برمجة التطبيقات الأساسية لنظامَي التشغيل 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 للاتصال بالطريقة 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() لمعالجة طلب الطريقة من 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. يستخدم هذا التنفيذ فئات مساعدة Java لنظام التشغيل Android لاستدعاء الطريقة الثابتة setHasUserConsent() في Android.

بما أنّ فئات Java المساعِدة لنظام التشغيل Android لا تتوفّر إلا أثناء وقت تنفيذ Android، يمكنك منع أخطاء الترجمة باستخدام UNITY_ANDROID توجيه compiler لتغليف الفئة كما هو موضّح في مقتطف الرمز. بدلاً من ذلك، يمكنك استخدام تعريفات التجميع في 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
        }
    }
}

تحديد واجهة برمجة تطبيقات عامة لكل طريقة واجهة

أنشئ فئة 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);
        }
    }
}

استدعاء واجهة برمجة التطبيقات المحدّدة حديثًا

في ما يلي كيفية طلب البيانات من واجهة برمجة التطبيقات المحدّدة أعلاه:

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 plug-in للاطّلاع على أمثلة إضافية لمحوِّلات التوسّط التابعة لجهات خارجية التي تُنفِّذ واجهات برمجة التطبيقات C# لتغليف طلبات الاتصال بأساليب iOS وAndroid.