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

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