สร้างเหตุการณ์ที่กำหนดเอง

เลือกแพลตฟอร์ม: Android Android iOS Unity

เหตุการณ์ที่กำหนดเองช่วยให้ผู้เผยแพร่โฆษณาที่ใช้สื่อกลาง AdMob เพิ่มการแสดงโฆษณาสื่อกลางตามลำดับขั้น (Waterfall Mediation) สำหรับเครือข่ายโฆษณาของบุคคลที่สามที่ไม่ใช่หนึ่งใน เครือข่ายโฆษณาที่รองรับได้ คู่มือนี้อธิบายวิธีใช้เหตุการณ์ที่กำหนดเองที่มีอยู่ซึ่งสร้างขึ้นสำหรับ Android และ iOS ในโปรเจ็กต์ Unity

ข้อกำหนดเบื้องต้น

ก่อนดำเนินการต่อ ให้ทำดังนี้

• ตั้งค่าGoogle Mobile Ads Unity Plugin แอป Unity ควรนำเข้าปลั๊กอิน Google Mobile Ads Unity ไว้แล้ว

• อะแดปเตอร์เหตุการณ์ที่กำหนดเองที่สร้างขึ้นสำหรับ Android และ iOS แล้ว หากต้องการสร้างอะแดปเตอร์เหตุการณ์ที่กำหนดเอง โปรดดูคู่มือเหตุการณ์ที่กำหนดเองใน Android และ iOS

กำหนดเหตุการณ์ที่กำหนดเอง

เหตุการณ์ที่กำหนดเองต้องกำหนดไว้ในอินเทอร์เฟซเว็บของ AdMob จึงจะเข้าร่วมสื่อกลางได้ เพิ่ม เหตุการณ์ที่กำหนดเองลงในกลุ่มสื่อกลางทั้ง 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 ที่สร้างไว้ล่วงหน้าโดยใช้ External Dependency Manager for Unity
• การนำเข้าปลั๊กอิน AAR และไลบรารี Android
• การนำเข้าไฟล์ต้นฉบับ Java และ Kotlin
• การนำเข้าไฟล์ต้นฉบับ iOS และไลบรารีแบบคงที่

คุณอาจต้องใช้กลยุทธ์การนำเข้าที่แตกต่างกันสำหรับไลบรารีแต่ละรายการ ทั้งนี้ขึ้นอยู่กับวิธีแพ็กเกจไลบรารีที่คุณใช้ เราจะอธิบายแต่ละตัวเลือกโดยละเอียดในภายหลัง

(แนะนำ) นำเข้าอาร์ติแฟกต์ Android หรือ iOS ที่สร้างไว้ล่วงหน้า

นำเข้าอาร์ติแฟกต์ที่สร้างไว้ล่วงหน้าจาก Maven หรือ CocoaPods โดยใช้ External Dependency Manager for Unity ปลั๊กอินนี้รวมอยู่ในปลั๊กอิน GoogleMobileAds

หากต้องการนำเข้าอาร์ติแฟกต์ที่มีอยู่ ให้สร้างไฟล์การกำหนดค่าเพื่อกำหนดการนำเข้า ชื่อไฟล์และเส้นทางต้องเป็นไปตามข้อกำหนดต่อไปนี้

• ไฟล์ต้องอยู่ในโฟลเดอร์ /Editor/
• ชื่อไฟล์ต้องลงท้ายด้วย Dependencies.xml

ตัวอย่างเช่น หากต้องการนำเข้าอะแดปเตอร์ของเหตุการณ์ที่กำหนดเองสำหรับเครือข่ายโฆษณาเสมือนชื่อ AdPub ให้สร้างไฟล์ต่อไปนี้

Assets/AdPub/Editor/AdPubDependencies.xml

จากนั้นกำหนดทรัพยากร Dependency ภายในไฟล์ AdPubDependencies.xml คุณดูข้อมูลเกี่ยวกับกฎสำหรับการกำหนดค่าการนำเข้าได้ที่ External Dependency Manager for Unity Getting Started ข้อมูลโค้ดต่อไปนี้มี 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>

หากอาร์ติแฟกต์เหตุการณ์ที่กำหนดเองมีทรัพยากร Dependency ใน SDK ของเครือข่ายโฆษณาที่จำเป็นอยู่แล้ว คุณไม่จำเป็นต้องกำหนดทรัพยากร Dependency ของ SDK อย่างชัดเจน: ตัวอย่าง

External Dependency Manager จะตรวจสอบการเปลี่ยนแปลงการกำหนดค่าและแก้ไขทรัพยากร Dependency โดยอัตโนมัติ นอกจากนี้ คุณยังดำเนินการแก้ไขด้วยตนเองได้ด้วยคำสั่งเมนูต่อไปนี้

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. ใช้ Factory ของไคลเอ็นต์เพื่อสลับระหว่างไคลเอ็นต์ iOS และ Android แบบมีเงื่อนไข
6. กำหนด API สำหรับการเข้าถึงฟังก์ชันการทำงานทั้งหมดของ SDK เครือข่ายโฆษณาของบุคคลที่สาม

ส่วนต่อไปนี้แสดงวิธีใช้ขั้นตอนเหล่านี้สำหรับเครือข่ายโฆษณาเสมือนชื่อ "AdPub" ใน API 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 ด้วยเมธอดที่แสดงถึง 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 และแพลตฟอร์มอื่นๆ ทั้งหมดที่ไม่ใช่ 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 เพื่อเรียกใช้เมธอดแบบคงที่ setHasUserConsent() ของ Android

เนื่องจากคลาสตัวช่วย Java ของ 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

สร้างเมธอด 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);
    }
}

ตัวอย่างอะแดปเตอร์เครือข่ายโฆษณาของบุคคลที่สามเพิ่มเติม

ไปที่ที่เก็บ Github ของปลั๊กอิน Google Mobile Ads Unity เพื่อดูตัวอย่างเพิ่มเติมของอะแดปเตอร์สื่อกลางของบุคคลที่สามที่ใช้ API C# เพื่อรวมการเรียกใช้เมธอด iOS และ Android