Buat peristiwa kustom

Pilih platform: Android Android iOS Unity

Peristiwa kustom memungkinkan penayang yang menggunakan mediasi Ad Manager menambahkan mediasi waterfall untuk jaringan iklan pihak ketiga yang bukan salah satu dari jaringan iklan yang didukung. Panduan ini menjelaskan cara menggunakan peristiwa kustom yang ada yang dibuat untuk Android dan iOS dalam project Unity.

Prasyarat

Sebelum melanjutkan, lakukan hal berikut:

• Siapkan Google Mobile Ads Unity Plugin. Aplikasi Unity Anda harus sudah mengimpor plugin Google Mobile Ads Unity.

• Adaptor peristiwa kustom sudah dibuat untuk Android dan iOS. Untuk membuat adaptor peristiwa kustom, lihat panduan peristiwa kustom kami di Android dan iOS.

Menentukan peristiwa kustom

Agar peristiwa kustom dapat berpartisipasi dalam mediasi, peristiwa kustom harus ditentukan di antarmuka web Ad Manager. Tambahkan peristiwa kustom ke grup mediasi Android dan iOS Anda.

Mengimpor library peristiwa kustom

Peristiwa kustom mungkin memerlukan library tambahan untuk disertakan agar berfungsi dengan baik. Misalnya, Anda mungkin perlu menyertakan library berikut:

• SDK pihak ketiga Android
• Peristiwa kustom pihak ketiga Android
• SDK iklan pihak ketiga iOS
• Peristiwa kustom pihak ketiga iOS

Jenis library

Ada beberapa cara untuk mengimpor kode Android atau iOS ke project Unity, termasuk:

• Mengimpor artefak Android atau iOS yang telah dibuat sebelumnya menggunakan Pengelola Dependensi Eksternal untuk Unity
• Mengimpor plugin AAR dan library Android
• Mengimpor file sumber Java dan Kotlin
• Mengimpor file sumber iOS dan library statis

Bergantung pada cara library yang Anda gunakan dikemas, Anda mungkin memerlukan strategi impor yang berbeda untuk setiap library. Setiap opsi akan dibahas lebih mendetail nanti.

(Direkomendasikan) Mengimpor artefak Android atau iOS yang telah dibuat sebelumnya

Impor artefak yang telah dibuat sebelumnya dari Maven atau CocoaPods menggunakan Pengelola Dependensi Eksternal untuk Unity. Plugin ini disertakan dengan plugin GoogleMobileAds.

Untuk mengimpor artefak yang ada, buat file konfigurasi untuk menentukan impor Anda. Nama file dan jalur memiliki persyaratan berikut:

• File harus ada di folder /Editor/.
• Nama file harus diakhiri dengan Dependencies.xml.

Misalnya, untuk mengimpor adaptor peristiwa kustom untuk jaringan iklan hipotetis bernama AdPub, buat file:

Assets/AdPub/Editor/AdPubDependencies.xml

Selanjutnya, tentukan dependensi Anda di dalam file AdPubDependencies.xml. Aturan untuk mengonfigurasi impor dapat ditemukan di Pengelola Dependensi Eksternal untuk Unity Mulai Cuplikan kode berikut menyertakan SDK Android dan iOS serta library peristiwa kustom untuk jaringan iklan hipotetis "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>

Jika artefak peristiwa kustom Anda sudah memiliki dependensi pada SDK jaringan iklan yang diperlukan, Anda tidak perlu menentukan dependensi SDK secara eksplisit: Contoh

Pengelola Dependensi Eksternal secara otomatis memantau perubahan konfigurasi dan mengatasi dependensi. Anda juga dapat menjalankan resolusi manual dengan perintah menu berikut:

Assets > External Dependency Manager > Android Resolver > Force Resolve

Mengimpor plugin AAR dan library Android

Unity mendukung pengimporan file *.aar serta project library Android. Jika peristiwa kustom Android Anda dikemas dengan cara ini, lihat Plugin AAR dan Android Library untuk mengetahui petunjuk cara menyertakan file tersebut dalam project Unity Anda.

Mengimpor file sumber Java dan Kotlin

Mulai Unity 2018.2 atau yang lebih baru, jika kode peristiwa kustom Android Anda terdiri dari file *.java atau *.kt yang tidak dikompilasi, Anda dapat menggunakan file sumber Java atau Kotlin sebagai plugin.

Mengimpor file sumber iOS dan library statis

Unity mendukung artefak *.framework, file sumber *.h, dan *.m. Pengimporan artefak dan file sumber iOS dijelaskan dalam panduan Unity untuk plugin native.

Menguji peristiwa kustom dengan pemeriksa iklan

Pemeriksa iklan dapat digunakan untuk menguji apakah peristiwa kustom telah diimpor dengan benar ke dalam aplikasi Anda. Pemeriksa iklan dapat dibuka hanya dengan gestur atau secara terprogram dengan kode minimal.

(Opsional) Memanggil metode native SDK pihak ketiga dari skrip C#

SDK jaringan iklan pihak ketiga mungkin memiliki persyaratan khusus yang mengharuskan pemanggilan metode Android atau iOS secara langsung. Proses untuk memanggil metode ini secara langsung adalah sebagai berikut:

1. Menentukan antarmuka umum untuk klien platform
2. Menerapkan klien default untuk platform yang tidak didukung
3. Menerapkan klien Android untuk memanggil metode Android
4. Menerapkan klien iOS untuk memanggil metode iOS
5. Menerapkan factory klien untuk beralih secara kondisional antara klien iOS dan Android
6. Menentukan API untuk mengakses semua fungsi SDK jaringan iklan pihak ketiga

Bagian berikut menunjukkan cara langkah-langkah ini diterapkan untuk jaringan iklan hipotetis bernama "AdPub" dalam API C# yang dapat memanggil metode di Android dan iOS:

package com.adpub.android;

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

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

Menentukan antarmuka umum untuk klien platform

Buat antarmuka IAdPubClient dengan metode yang mewakili API Android dan iOS yang mendasarinya.

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

Menentukan klien default untuk platform yang tidak didukung

Buat class DefaultClient yang menerapkan antarmuka IAdPubClient yang hanya mencatat nama metode. Gunakan implementasi ini untuk editor Unity dan semua platform selain Android atau iOS.

Assets/AdPub/Common/DefaultClient.cs

namespace AdPub.Common
{
    public class DefaultClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
            Debug.Log("SetHasUserConsent was called.");
        }
    }
}

Menerapkan klien platform iOS

Buat class iOSAdPubClient yang menerapkan antarmuka IAdPubClient di iOS. Implementasi ini menggunakan InteropServices untuk memanggil metode setHasUserConsent() di class 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

Selanjutnya, terapkan metode GADUAdPubSetHasUserConsent() yang ditentukan di atas. Buat AdPubClientBridge.m dengan metode C GADUAdPubSetHasUserConsent() untuk menangani panggilan metode dari Unity, dan panggil AdPubSDK.

AdPubClientBridge adalah file sumber iOS dan harus ditempatkan di dalam folder Plugins/iOS seperti yang dijelaskan dalam panduan Unity's untuk plugin native.

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

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

Menerapkan klien platform Android

Buat class AndroidAdPubCient yang menerapkan antarmuka IAdPubClient di Android. Implementasi ini menggunakan class helper Java Android untuk memanggil metode statis Android setHasUserConsent().

Karena class helper Java Android hanya tersedia selama runtime Android, Anda dapat mencegah error kompilasi menggunakan UNITY_ANDROID direktif pengompilasi untuk menggabungkan class seperti yang ditunjukkan dalam cuplikan kode. Atau, Anda dapat menggunakan definisi Assembly di Unity 2017.4 dan yang lebih baru untuk mengatasi masalah ini.

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

Membuat metode factory untuk menampilkan implementasi klien yang benar

Setelah memiliki implementasi klien untuk setiap platform, buat class AdPubClientFactory untuk menampilkan implementasi antarmuka IAdPubClient yang benar, bergantung pada platform runtime. Class ini menggunakan direktif pengompilasi untuk menampilkan klien yang benar 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
        }
    }
}

Menentukan API publik untuk setiap metode antarmuka

Buat class AdPubApi yang memiliki panggilan metode untuk setiap metode klien di antarmuka IAdPubClient Anda. Class ini menggunakan AdPubClientFactory untuk mendapatkan instance IAdPubClient dan memanggil klien tersebut untuk fungsi SDK yang mendasarinya.

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

Memanggil API yang baru ditentukan

Berikut cara memanggil API yang ditentukan di atas:

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

Contoh adaptor jaringan iklan pihak ketiga tambahan

Buka repositori Github plugin Google Mobile Ads Unity untuk mengetahui contoh tambahan adaptor mediasi pihak ketiga yang menerapkan API C# untuk menggabungkan panggilan ke metode iOS dan Android.