رویدادهای سفارشی ایجاد کنید

رویدادهای سفارشی ناشران را با استفاده از میانجیگری AdMobقادر می‌سازند تا واسطه‌های آبشاری را برای یک شبکه تبلیغاتی شخص ثالث که یکی از شبکه‌های تبلیغاتی پشتیبانی‌شده نیست، اضافه کنند. این راهنما نحوه استفاده از یک رویداد سفارشی موجود برای Android و iOS را در پروژه Unity توضیح می دهد.

پیش نیازها

• کامل شروع کنید . برنامه Unity شما باید قبلاً افزونه Google Mobile Ads Unity را وارد کرده باشد.

• آداپتورهای رویداد سفارشی قبلاً برای Android و iOS ساخته شده‌اند. برای ایجاد آداپتورهای رویداد سفارشی، به راهنمای رویدادهای سفارشی ما درAndroid وiOSمراجعه کنید.

یک رویداد سفارشی را تعریف کنید

برای اینکه یک رویداد سفارشی در میانجیگری شرکت کند، رویداد سفارشی باید در رابط وب AdMob تعریف شود. یک رویداد سفارشی را به هر دو گروه میانجی اندروید و iOS خود اضافه کنید .

این اسکرین شات چند نمونه تنظیمات رویداد سفارشی را نشان می دهد:

نحوه پر کردن پارامترها
نام کلاس (iOS)	برای iOS، نام کلاسی را که رویداد سفارشی را پیاده سازی می کند، وارد کنید. اگر کلاس شما در سوئیفت پیاده سازی شده است، باید نام کلاس را با نام ماژول برنامه / چارچوب آن (مثلاً appName.className ) قرار دهید. اگر چندین هدف در پروژه خود دارید یا اگر نام پروژه با نام هدف متفاوت است، نام هدف مورد نیاز است. با نام هدف، به این صورت است: appName_targetName.className . علاوه بر این، به یاد داشته باشید که هر کاراکتر غیرالفبایی مانند خط تیره را با زیرخط جایگزین کنید.
نام کلاس (اندروید)	برای Android، مطمئن شوید که مقداری که برای Class Name می‌دهید، نام کلاس کاملاً واجد شرایط برای Android باشد (برای مثال com.google.ads.mediation.sample.customevent.SampleCustomEvent ).
برچسب	یک نام منحصر به فرد برای رویداد وارد کنید.
پارامتر	اگر می‌خواهید یک آرگومان رشته‌ای را به رویداد سفارشی خود ارسال کنید، برای مثال شناسه واحد تبلیغات.

وارد کردن کتابخانه های رویداد سفارشی

رویدادهای سفارشی ممکن است نیاز به گنجاندن کتابخانه های اضافی برای عملکرد صحیح داشته باشند. به عنوان مثال، ممکن است لازم باشد کتابخانه های زیر را اضافه کنید:

• SDK شخص ثالث اندروید
• رویداد سفارشی شخص ثالث اندروید
• SDK آگهی شخص ثالث iOS
• رویداد سفارشی شخص ثالث iOS

انواع کتابخانه ها

راه های مختلفی برای وارد کردن کد اندروید یا iOS به پروژه یونیتی وجود دارد، از جمله:

• وارد کردن مصنوعات از پیش ساخته شده اندروید یا iOS با استفاده از External Dependency Manager for Unity
• وارد کردن پلاگین های AAR و کتابخانه های اندروید
• وارد کردن فایل های منبع جاوا و کاتلین
• وارد کردن فایل های منبع iOS و کتابخانه های ثابت

بسته به نحوه بسته بندی کتابخانه هایی که استفاده می کنید، ممکن است برای هر کتابخانه به استراتژی واردات متفاوتی نیاز داشته باشید. هر گزینه بعداً با جزئیات بیشتری مورد بحث قرار می گیرد.

(توصیه می شود) مصنوعات از پیش ساخته شده اندروید یا iOS را وارد کنید

با استفاده از External Dependency Manager for Unity، مصنوعات از پیش ساخته شده را از Maven یا CocoaPods وارد کنید. این افزونه همراه با افزونه GoogleMobileAds موجود است.

برای وارد کردن مصنوعات موجود، یک فایل پیکربندی برای تعریف واردات خود ایجاد کنید. نام فایل و مسیر دارای شرایط زیر است:

• فایل باید در پوشه /Editor/ وجود داشته باشد.
• نام فایل باید به Dependencies.xml ختم شود.

به عنوان مثال، برای وارد کردن آداپتورهای رویداد سفارشی برای یک شبکه تبلیغاتی فرضی به نام AdPub ، فایل را ایجاد کنید:

Assets/AdPub/Editor/AdPubDependencies.xml

بعد، وابستگی های خود را در داخل فایل AdPubDependencies.xml تعریف کنید. قوانین پیکربندی واردات را می توان در External Dependency Manager for Unity Getting Started پیدا کرد. قطعه کد زیر شامل Android و iOS SDK و کتابخانه‌های رویداد سفارشی برای یک شبکه تبلیغاتی «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 را به صراحت تعریف کنید: مثال

External Dependency Manager به طور خودکار تغییرات پیکربندی را کنترل می کند و وابستگی ها را حل می کند. همچنین می توانید وضوح دستی را با دستور منوی زیر اجرا کنید:

Assets > External Dependency Manager > Android Resolver > Force Resolve

افزونه‌های AAR و کتابخانه‌های Android را وارد کنید

Unity از وارد کردن فایل های *.aar و همچنین پروژه های کتابخانه اندروید پشتیبانی می کند. اگر رویداد سفارشی اندروید شما به این شکل بسته بندی شده است، برای دستورالعمل هایی در مورد نحوه گنجاندن آن فایل ها در پروژه Unity خود، به پلاگین های AAR و کتابخانه های Android مراجعه کنید.

فایل های منبع جاوا و کاتلین را وارد کنید

از Unity 2018.2 یا بالاتر، اگر کد رویداد سفارشی Android شما از فایل های *.java یا *.kt کامپایل نشده تشکیل نشده است، می توانید از فایل های منبع جاوا یا Kotlin به عنوان افزونه استفاده کنید.

فایل‌های منبع iOS و کتابخانه‌های استاتیک را وارد کنید

Unity از آرتیفکت های *.framework ، *.h و *.m فایل های منبع پشتیبانی می کند. وارد کردن مصنوعات iOS و فایل های منبع در راهنمای Unity برای افزونه های بومی توضیح داده شده است.

رویدادهای سفارشی را با بازرس آگهی آزمایش کنید

Ad Inspector می تواند برای آزمایش اینکه رویدادهای سفارشی به درستی به برنامه شما وارد شده اند استفاده شود. Ad Inspector می تواند فقط با حرکات حرکتی یا برنامه نویسی با حداقل کد باز شود.

(اختیاری) روش های بومی SDK شخص ثالث را از اسکریپت های C# فراخوانی کنید

SDK های شبکه تبلیغاتی شخص ثالث ممکن است شرایط خاصی داشته باشند که مستلزم فراخوانی مستقیم روش های Android یا iOS است. فرآیند فراخوانی مستقیم این متدها به شرح زیر است:

1. یک رابط مشترک برای مشتریان پلتفرم تعریف کنید
2. یک کلاینت پیش فرض برای پلتفرم های پشتیبانی نشده پیاده سازی کنید
3. یک کلاینت اندروید برای فراخوانی متدهای اندروید پیاده سازی کنید
4. یک کلاینت iOS برای فراخوانی متدهای iOS پیاده سازی کنید
5. برای جابه‌جایی مشروط بین کلاینت‌های iOS و Android، یک کارخانه کلاینت اجرا کنید
6. یک API برای دسترسی به همه عملکردهای SDK شبکه تبلیغاتی شخص ثالث تعریف کنید

بخش زیر نشان می دهد که چگونه این مراحل برای یک شبکه تبلیغاتی فرضی به نام "AdPub" در یک API C# اجرا می شود که می تواند متدهای موجود در Android و iOS را فراخوانی کند:

اندروید

package com.adpub.android;

public class AdPubSdk
{
    public static void setHasUserConsent(boolean hasUserConsent);
}

iOS

@interface AdPubSdk : NSObject
+ (void)setHasUserConsent:(BOOL)hasUserConsent;
@end

یک رابط مشترک برای مشتریان پلتفرم تعریف کنید

یک رابط IAdPubClient با روشی ایجاد کنید که نمایانگر API اصلی 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 و همه پلتفرم های غیر از اندروید یا 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];
}

یک کلاینت پلتفرم اندروید را پیاده سازی کنید

یک کلاس AndroidAdPubCient ایجاد کنید که رابط IAdPubClient را در اندروید پیاده سازی کند. این پیاده سازی از کلاس های کمکی جاوا اندروید برای فراخوانی متد استاتیک اندروید setHasUserConsent() استفاده می کند.

از آنجایی که کلاس‌های کمکی جاوا Android فقط در طول زمان اجرای Android در دسترس هستند، می‌توانید با استفاده از دستورالعمل کامپایلر UNITY_ANDROID از خطاهای کامپایل جلوگیری کنید تا کلاس را همانطور که در قطعه کد نشان داده شده است بپیچید. همچنین، می‌توانید از تعاریف Assembly در 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
        }
    }
}

برای هر روش رابط یک API عمومی تعریف کنید

یک کلاس 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);
        }
    }
}

با API تازه تعریف شده خود تماس بگیرید

در اینجا نحوه فراخوانی API تعریف شده در بالا آمده است:

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);
    }
}

نمونه‌های آداپتور شبکه آگهی شخص ثالث اضافی

برای مشاهده نمونه‌های اضافی از آداپتورهای واسطه شخص ثالث که APIهای C# را برای بسته‌بندی تماس‌ها با روش‌های iOS و Android پیاده‌سازی می‌کنند، از مخزن Github افزونه Google Mobile Ads Unity دیدن کنید.