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

اختيار النظام الأساسي: Android Android iOS Unity

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

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

قبل المتابعة، يُرجى تنفيذ ما يلي:

• إعداد Google Mobile Ads Unity Plugin يجب أن يكون تطبيق Unity قد استورد مكوّن Google Mobile Ads Unity الإضافي.

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

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

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

استيراد مكتبات الأحداث المخصّصة

قد تتطلّب الأحداث المخصّصة تضمين مكتبات إضافية لكي تعمل بشكلٍ صحيح. على سبيل المثال، قد تحتاج إلى تضمين المكتبات التالية:

• حزمة تطوير البرامج (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 بهذه الطريقة، يُرجى الاطّلاع على المكوّنات الإضافية 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:

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. يستخدم هذا التنفيذ فئات المساعد Android Java لاستدعاء الطريقة الثابتة setHasUserConsent() على Android.

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