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

پلتفرم مورد نظر: اندروید، iOS و یونیتی

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

پیش‌نیازها

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

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

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

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

این تصویر نمونه‌ای از تنظیمات رویداد سفارشی را نشان می‌دهد:

نحوه پر کردن پارامترها
نام کلاس (iOS)

برای iOS، نام کلاسی که رویداد سفارشی را پیاده‌سازی می‌کند را وارد کنید.

اگر کلاس شما در Swift پیاده‌سازی شده است، باید نام کلاس را با نام ماژول app/framework آن (مثلاً appName.className ) پیشوند کنید.

اگر چندین هدف در پروژه خود دارید یا اگر نام پروژه با نام هدف متفاوت است، نام هدف الزامی است. با نام هدف، به این شکل خواهد بود: appName_targetName.className . علاوه بر این، به یاد داشته باشید که هر کاراکتر غیرحرفی-عددی مانند خط تیره را با زیرخط جایگزین کنید.

نام کلاس (اندروید) برای اندروید، مطمئن شوید مقداری که برای Class Name می‌دهید، نام کامل کلاس برای اندروید باشد (برای مثال com.google.ads.mediation.sample.customevent.SampleCustomEvent ).
برچسب یک نام منحصر به فرد برای رویداد وارد کنید.
پارامتر اگر می‌خواهید یک آرگومان رشته‌ای، مثلاً یک شناسه واحد تبلیغاتی، را به رویداد سفارشی خود ارسال کنید.

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

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

  • SDK شخص ثالث اندروید
  • رویداد سفارشی شخص ثالث اندروید
  • کیت توسعه نرم‌افزاری تبلیغات شخص ثالث iOS
  • رویداد سفارشی شخص ثالث iOS

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

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

  • وارد کردن مصنوعات از پیش ساخته شده اندروید یا iOS با استفاده از مدیر وابستگی خارجی برای یونیتی
  • وارد کردن افزونه‌های AAR و کتابخانه‌های اندروید
  • وارد کردن فایل‌های منبع جاوا و کاتلین
  • وارد کردن فایل‌های منبع iOS و کتابخانه‌های استاتیک

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

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

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

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

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

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

Assets/AdPub/Editor/AdPubDependencies.xml

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

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

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

از نسخه ۲۰۱۸.۲ یا بالاتر یونیتی، اگر کد رویداد سفارشی اندروید شما شامل فایل‌های *.java یا *.kt کامپایل نشده باشد، می‌توانید از فایل‌های منبع جاوا یا کاتلین به عنوان افزونه استفاده کنید.

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

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

رویدادهای سفارشی را با بازرس تبلیغات آزمایش کنید

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

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

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

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

بخش زیر نحوه پیاده‌سازی این مراحل را برای یک شبکه تبلیغاتی فرضی به نام "AdPub" در یک API سی‌شارپ که می‌تواند متدهای اندروید و iOS را فراخوانی کند، نشان می‌دهد:

اندروید 

package com.adpub.android;

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

آی‌او‌اس 

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

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

یک رابط IAdPubClient با متدی که نشان‌دهنده‌ی API اصلی اندروید و 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() در کلاس iOS AdPubSdk استفاده می‌کند.

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 با متد GADUAdPubSetHasUserConsent() C ایجاد کنید تا فراخوانی متد از Unity را مدیریت کند و AdPubSDK فراخوانی کند.

AdPubClientBridge یک فایل منبع iOS است و باید همانطور که در راهنمای Unity برای افزونه‌های بومی توضیح داده شده است، در پوشه Plugins/iOS قرار گیرد.

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m 

#import <AdPubSDK/AdPubSDK.h>

void GADUAdPubSetHasUserConsent(BOOL hasUserConsent) {
  [AdPubSDK setHasUserConsent:hasUserConsent];
}

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

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

از آنجایی که کلاس‌های کمکی جاوای اندروید فقط در زمان اجرای اندروید در دسترس هستند، می‌توانید با استفاده از دستورالعمل کامپایلر 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

یک متد factory برای بازگرداندن پیاده‌سازی صحیح کلاینت ایجاد کنید.

حالا که پیاده‌سازی‌های کلاینت را برای هر پلتفرم دارید، یک کلاس 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 و اندروید پیاده‌سازی می‌کنند ، از مخزن گیت‌هاب افزونه‌ی Google Mobile Ads Unity دیدن کنید.