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

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

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

• ดำเนินการตามเริ่มต้นใช้งานให้เสร็จสมบูรณ์ แอป Unity ของคุณควรมีการนำเข้าปลั๊กอิน Unity สำหรับโฆษณาในอุปกรณ์เคลื่อนที่ของ Google แล้ว

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

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

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

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

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

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

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

Assets/AdPub/Editor/AdPubDependencies.xml

ถัดไป ให้กำหนดทรัพยากร Dependency ภายในไฟล์ AdPubDependencies.xml ดูกฎสำหรับการกำหนดค่าการนำเข้าได้ที่ External Dependency Manager สำหรับการเริ่มต้นใช้งาน 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 เครือข่ายโฆษณาที่จำเป็นอยู่แล้ว คุณไม่จำเป็นต้องกำหนดทรัพยากร Dependency ของ SDK อย่างชัดแจ้ง ดังนี้ ตัวอย่าง

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

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

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

เนื่องจากคลาสตัวช่วยของ Android Java พร้อมใช้งานระหว่างรันไทม์ของ 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);
    }
}

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

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