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

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

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

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

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

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

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

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

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

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

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

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

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

Assets/AdPub/Editor/AdPubDependencies.xml

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

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

สร้างเมธอดจากโรงงานเพื่อส่งคืนการติดตั้งใช้งานไคลเอ็นต์ที่ถูกต้อง

เมื่อคุณติดตั้งใช้งานไคลเอ็นต์ในทุกแพลตฟอร์มแล้ว ให้สร้าง 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 ที่มีการเรียกใช้เมธอดสำหรับเมธอด Client แต่ละเมธอดใน 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 ที่เก็บ ดูตัวอย่างเพิ่มเติมของอะแดปเตอร์สื่อกลางของบุคคลที่สามที่ใช้ C# API เพื่อรวมการโทรไปยังเมธอดของ iOS และ Android