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

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

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

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

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

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

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

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

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

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

Assets/AdPub/Editor/AdPubDependencies.xml

จากนั้นให้กําหนดทรัพยากรที่ต้องพึ่งพาภายในไฟล์ AdPubDependencies.xml ดูกฎสำหรับการกำหนดค่าการนําเข้าได้ที่เครื่องมือจัดการทรัพยากรภายนอกสําหรับการเริ่มต้นใช้งาน Unity ข้อมูลโค้ดต่อไปนี้ประกอบด้วย 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 เป็นแบบนี้ โปรดดูวิธีการรวมไฟล์เหล่านั้นในโปรเจ็กต์ Unity ที่หัวข้อปลั๊กอิน AAR และไลบรารี Android

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

ส่วนต่อไปนี้แสดงวิธีใช้ขั้นตอนเหล่านี้กับเครือข่ายโฆษณาสมมติชื่อ "AdPub" ใน C# API ที่เรียกใช้เมธอดใน Android และ iOS ได้

AndroidiOS

package com.adpub.android;

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

@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 คําสั่งคอมไพเลอร์เพื่อรวมคลาสดังที่แสดงในตัวอย่างโค้ด หรือจะใช้คําจํากัดความการประกอบใน 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);
    }
}

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

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