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

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

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

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

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

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

لكي يشارك حدث مخصّص في التوسّط، يجب أن أن يتم تحديدها في Ad Manager واجهة الويب. إضافة الحدث المخصص لكل من مجموعات التوسط على نظامي التشغيل 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
• استيراد ملفات المصدر بلغة Kotlin وJava
• استيراد ملفات المصدر لنظام التشغيل iOS والمكتبات الثابتة

بناءً على كيفية حزم المكتبات التي تستخدمها، قد تحتاج إلى ملف شخصي استراتيجية استيراد البيانات لكل مكتبة. وتتم مناقشة كل خيار بمزيد من التفصيل في وقت لاحق.

(يُنصَح به) استيراد عناصر Android أو iOS المنشأة مسبقًا

استيراد العناصر المنشأة مسبقًا من Maven أو CocoaPods باستخدام عنصر التحكّم مدير تبعية في Unity. يتم تضمين هذا المكوّن الإضافي مع المكون الإضافي GoogleMobileAds.

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

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

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

Assets/AdPub/Editor/AdPubDependencies.xml

بعد ذلك، حدِّد التبعيات ضمن ملف AdPubDependencies.xml. القواعد لضبط عمليات الاستيراد، يمكن العثور على مدير التبعية الخارجية في Unity Get تم البدء. تشير رسالة الأشكال البيانية يتضمن مقتطف الرمز التالي حزمة تطوير البرامج (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 يستخدم هذا التنفيذ مساعد Java لنظام التشغيل Android الصفوف لاستدعاء طريقة Android الثابتة setHasUserConsent().

نظرًا لأن صفوف مساعد 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);
    }
}

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

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