Trang này được dịch bởi Cloud Translation API.

Tạo sự kiện tuỳ chỉnh

Sự kiện tuỳ chỉnh cho phép nhà xuất bản sử dụng tính năng dàn xếp AdMob để thêm chế độ dàn xếp kiểu thác nước cho một mạng quảng cáo bên thứ ba không thuộc danh sách mạng quảng cáo được hỗ trợ. Hướng dẫn này giải thích cách sử dụng một sự kiện tuỳ chỉnh hiện có được tạo cho Android và iOS trong một dự án Unity.

Điều kiện tiên quyết

Hoàn tất phần Bắt đầu. Bạn phải nhập sẵn trình bổ trợ Google Mobile Ads cho Unity vào ứng dụng Unity.
Bộ chuyển đổi sự kiện tuỳ chỉnh đã được tạo cho Android và iOS. Để tạo bộ chuyển đổi sự kiện tuỳ chỉnh, hãy tham khảo hướng dẫn về sự kiện tuỳ chỉnh của chúng tôi trên Android và iOS.

Xác định sự kiện tuỳ chỉnh

Để một sự kiện tuỳ chỉnh tham gia vào hoạt động dàn xếp, bạn phải xác định sự kiện tuỳ chỉnh đó trong giao diện web của AdMob. Thêm một sự kiện tuỳ chỉnh vào cả nhóm dàn xếp Android và iOS.

Ảnh chụp màn hình này cho thấy một số chế độ cài đặt sự kiện tuỳ chỉnh mẫu:

Cách điền thông số
Tên lớp (iOS)	Đối với iOS, hãy nhập tên của lớp triển khai sự kiện tuỳ chỉnh. Nếu lớp được triển khai trong Swift, bạn cần thêm tên của ứng dụng / mô-đun khung (ví dụ: `appName.className`) vào trước tên lớp. Bạn phải nhập tên mục tiêu nếu có nhiều mục tiêu trong dự án hoặc nếu tên dự án khác với tên mục tiêu. Tên mục tiêu sẽ có dạng như sau: `appName_targetName.className`. Ngoài ra, hãy nhớ thay thế mọi ký tự không phải chữ-số (ví dụ như thay thế dấu gạch ngang bằng dấu gạch dưới).
Tên lớp (Android)	Đối với Android, hãy đảm bảo giá trị mà bạn cung cấp cho `Class Name` là tên lớp đủ điều kiện cho Android (ví dụ: `com.google.ads.mediation.sample.customevent.SampleCustomEvent`).
Hãng nhạc	Nhập một tên duy nhất cho sự kiện này.
Thông số	Nếu bạn muốn chuyển một đối số chuỗi vào sự kiện tuỳ chỉnh, ví dụ: mã đơn vị quảng cáo.

Nhập thư viện sự kiện tuỳ chỉnh

Sự kiện tuỳ chỉnh có thể yêu cầu bạn phải đưa thêm thư viện vào để hoạt động đúng cách. Ví dụ: bạn có thể cần thêm các thư viện sau:

SDK của bên thứ ba dành cho Android
Sự kiện tuỳ chỉnh của bên thứ ba dành cho Android
SDK quảng cáo của bên thứ ba dành cho iOS
Sự kiện tuỳ chỉnh của bên thứ ba dành cho iOS

Các loại thư viện

Có nhiều cách để nhập mã Android hoặc iOS vào dự án Unity, bao gồm:

Nhập các cấu phần phần mềm Android hoặc iOS được tạo sẵn bằng cách sử dụng Trình quản lý phần phụ thuộc bên ngoài cho Unity
Nhập trình bổ trợ AAR và thư viện Android
Nhập tệp nguồn Java và Kotlin
Nhập tệp nguồn iOS và thư viện tĩnh

Tuỳ thuộc vào cách đóng gói các thư viện mà bạn sử dụng, bạn có thể cần sử dụng cách nhập khác nhau cho từng thư viện. Mỗi tuỳ chọn sẽ được thảo luận chi tiết hơn sau.

(Nên dùng) Nhập các cấu phần phần mềm Android hoặc iOS được tạo sẵn

Nhập các cấu phần phần mềm được tạo sẵn từ Maven hoặc CocoaPods bằng cách sử dụng Trình quản lý phần phụ thuộc bên ngoài cho Unity. Trình bổ trợ này đi kèm với trình bổ trợ GoogleMobileAds.

Để nhập các cấu phần phần mềm hiện có, hãy tạo một tệp cấu hình để xác định các mục nhập của bạn. Tên tệp và đường dẫn có các yêu cầu sau:

Tệp phải tồn tại trong thư mục /Editor/.
Tên tệp phải kết thúc bằng Dependencies.xml.

Ví dụ: Để nhập bộ chuyển đổi của sự kiện tuỳ chỉnh cho một mạng quảng cáo giả định có tên là AdPub, hãy tạo tệp:

Assets/AdPub/Editor/AdPubDependencies.xml

Tiếp theo, hãy xác định các phần phụ thuộc bên trong tệp AdPubDependencies.xml. Bạn có thể xem các quy tắc định cấu hình mục nhập trong phần Hướng dẫn bắt đầu sử dụng Trình quản lý phần phụ thuộc bên ngoài cho Unity. Đoạn mã sau đây bao gồm SDK Android và iOS cũng như các thư viện sự kiện tuỳ chỉnh cho mạng quảng cáo "AdPub" giả định.

`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>

Nếu cấu phần phần mềm sự kiện tuỳ chỉnh của bạn đã có một phần phụ thuộc của SDK mạng quảng cáo bắt buộc, thì bạn không cần xác định rõ ràng phần phụ thuộc SDK: Ví dụ

Trình quản lý phần phụ thuộc bên ngoài tự động theo dõi các thay đổi về cấu hình và giải quyết các phần phụ thuộc. Bạn cũng có thể thực hiện theo cách thủ công bằng lệnh trong trình đơn sau đây:

Assets > External Dependency Manager > Android Resolver > Force Resolve

Nhập trình bổ trợ AAR và thư viện Android

Unity hỗ trợ việc nhập tệp *.aar và các dự án thư viện Android. Nếu sự kiện tuỳ chỉnh Android được đóng gói theo cách này, hãy xem các trình bổ trợ AAR và Thư viện Android để biết hướng dẫn về cách đưa các tệp đó vào dự án Unity.

Nhập tệp nguồn Java và Kotlin

Kể từ Unity 2018.2 trở lên, nếu mã sự kiện tuỳ chỉnh Android có các tệp *.java hoặc *.kt chưa được biên dịch, bạn có thể sử dụng các tệp nguồn Java hoặc Kotlin làm trình bổ trợ.

Nhập tệp nguồn iOS và thư viện tĩnh

Unity hỗ trợ cấu phần phần mềm *.framework, tệp nguồn *.h và *.m. Bạn có thể xem phần giải thích về cách nhập các cấu phần phần mềm và tệp nguồn trên iOS trong Hướng dẫn của Unity về trình bổ trợ gốc.

Thử nghiệm sự kiện tuỳ chỉnh bằng công cụ kiểm tra quảng cáo

Bạn có thể sử dụng Công cụ kiểm tra quảng cáo để kiểm tra xem các sự kiện tuỳ chỉnh đã được nhập đúng cách vào ứng dụng của bạn hay chưa. Bạn có thể mở Công cụ kiểm tra quảng cáo chỉ bằng các cử chỉ hoặc theo phương thức lập trình mà không cần dùng quá nhiều mã.

(Không bắt buộc) Gọi phương thức gốc SDK của bên thứ ba từ tập lệnh C#

SDK của mạng quảng cáo bên thứ ba có thể có các yêu cầu đặc biệt bắt buộc gọi trực tiếp các phương thức Android hoặc iOS. Quy trình gọi trực tiếp các phương thức này như sau:

Xác định giao diện chung cho ứng dụng nền tảng
Triển khai ứng dụng mặc định cho các nền tảng không được hỗ trợ
Triển khai ứng dụng Android để gọi các phương thức Android
Triển khai ứng dụng iOS để gọi các phương thức iOS
Triển khai nhà máy ứng dụng để chuyển đổi có điều kiện giữa ứng dụng iOS và ứng dụng Android
Xác định một API để sử dụng tất cả chức năng của SDK của mạng quảng cáo bên thứ ba

Phần sau đây cho thấy cách triển khai các bước này cho một mạng quảng cáo giả định có tên là "AdPub" trong một API C# có thể gọi vào các phương thức trên Android và iOS:

AndroidiOS

package com.adpub.android;

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

@interface AdPubSdk : NSObject
+ (void)setHasUserConsent:(BOOL)hasUserConsent;
@end

Xác định giao diện chung cho ứng dụng nền tảng

Tạo giao diện IAdPubClient bằng một phương thức đại diện cho API Android và iOS cơ bản.

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

Xác định ứng dụng mặc định cho các nền tảng không được hỗ trợ

Tạo một lớp DefaultClient triển khai giao diện IAdPubClient chỉ ghi nhật ký tên phương thức. Sử dụng cách triển khai này cho trình chỉnh sửa Unity và tất cả nền tảng ngoại trừ Android hoặc iOS.

`Assets/AdPub/Common/DefaultClient.cs`

namespace AdPub.Common
{
    public class DefaultClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
            Debug.Log("SetHasUserConsent was called.");
        }
    }
}

Triển khai ứng dụng nền tảng iOS

Tạo một lớp iOSAdPubClient triển khai giao diện IAdPubClient trên iOS. Cách triển khai này sử dụng InteropServices để gọi phương thức setHasUserConsent() trong lớp AdPubSdk của 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

Tiếp theo, hãy triển khai phương thức GADUAdPubSetHasUserConsent() đã được xác định ở trên. Tạo AdPubClientBridge.m bằng phương thức C GADUAdPubSetHasUserConsent() để xử lý lệnh gọi phương thức từ Unity và gọi AdPubSDK.

AdPubClientBridge là tệp nguồn iOS và phải được đặt bên trong thư mục Plugins/iOS như đã giải thích trong hướng dẫn của Unity về trình bổ trợ gốc.

`Assets/AdPub/Plugins/iOS/AdPubClientBridge.m`

#import <AdPubSDK/AdPubSDK.h>

void GADUAdPubSetHasUserConsent(BOOL hasUserConsent) {
  [AdPubSDK setHasUserConsent:hasUserConsent];
}

Triển khai ứng dụng nền tảng Android

Tạo một lớp AndroidAdPubCient triển khai giao diện IAdPubClient trên Android. Cách triển khai này sử dụng lớp trình trợ giúp Android Java để gọi phương thức tĩnh Android setHasUserConsent().

Vì các lớp trình trợ giúp Android Java chỉ có trong thời gian chạy Android, nên bạn có thể ngăn các lỗi biên dịch bằng cách sử dụng lệnh của trình biên dịch UNITY_ANDROID để đóng gói lớp như minh hoạ trong đoạn mã. Ngoài ra, bạn có thể sử dụng định nghĩa Assembly trên Unity 2017.4 trở lên để giải quyết vấn đề này.

`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

Tạo một phương thức gốc để trả về cấu hình triển khai ứng dụng chính xác

Bây giờ, bạn đã triển khai ứng dụng cho mọi nền tảng, hãy tạo một lớp AdPubClientFactory để trả về phương thức triển khai chính xác của giao diện IAdPubClient, tuỳ thuộc vào nền tảng thời gian chạy. Lớp này sử dụng lệnh của trình biên dịch để trả về ứng dụng IAdPubClient chính xác.

`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
        }
    }
}

Xác định API công khai cho từng phương thức giao diện

Tạo một lớp AdPubApi có lệnh gọi phương thức cho mỗi phương thức ứng dụng trong giao diện IAdPubClient. Lớp này sử dụng AdPubClientFactory để lấy một bản sao của IAdPubClient và gọi ứng dụng đó để sử dụng các chức năng của SDK cơ bản.

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

Gọi API mới được xác định

Sau đây là cách bạn có thể gọi API được xác định ở trên:

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

Các ví dụ khác về bộ chuyển đổi mạng quảng cáo bên thứ ba

Truy cập vào kho lưu trữ GitHub của trình bổ trợ Google Mobile Ads cho Unity để xem thêm ví dụ về các bộ chuyển đổi dàn xếp của bên thứ ba triển khai API C# để đóng gói các lệnh gọi đến phương thức iOS và Android.