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

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

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

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

นำเข้าอาร์ติแฟกต์ที่สร้างไว้ล่วงหน้าจาก Maven หรือ CocoaPods โดยใช้เครื่องมือจัดการ Dependency ภายนอกสำหรับ 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>

หากอาร์ติแฟกต์เหตุการณ์ที่กำหนดเองมีทรัพยากร Dependency ใน SDK เครือข่ายโฆษณาที่จำเป็นอยู่แล้ว คุณไม่จำเป็นต้องกำหนดทรัพยากร Dependency ของ 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. ใช้factory ไคลเอ็นต์เพื่อสลับระหว่างไคลเอ็นต์ 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 การติดตั้งใช้งานนี้ใช้คลาส ตัวช่วย Java ของ Android เพื่อเรียกใช้เมธอดแบบคงที่ของ Android setHasUserConsent()

เนื่องจากคลาสตัวช่วย 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 โดยขึ้นอยู่กับแพลตฟอร์มรันไทม์ คลาสนี้ใช้ คำสั่งคอมไพเลอร์เพื่อ แสดงผล IAdPubClientclient ที่ถูกต้อง

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

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

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