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

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

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

• أكمِل الخطوات في البدء. يجب أن يكون تطبيق 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. يمكنك الاطّلاع على قواعد ضبط عمليات الاستيراد في مقالة بدء استخدام External Dependency Manager for 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) المطلوبة لشبكة الإعلانات، لن تحتاج إلى تحديد تبعية حزمة تطوير البرامج (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 مباشرةً. في ما يلي خطوات استدعاء هذه الطرق مباشرةً:

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

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

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

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

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

أمثلة إضافية على محوّلات شبكات الإعلانات التابعة لجهات خارجية

يمكنك الانتقال إلى مستودع Google Mobile Ads Unity الإضافي على Github للاطّلاع على أمثلة إضافية لمحوّلات التوسّط التابعة لجهات خارجية التي تنفّذ واجهات برمجة تطبيقات C# لتضمين طلبات إلى طرق iOS وAndroid.