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 AdMob dàn xếp để thêm chế độ dàn xếp kiểu thác nước cho 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ó dành cho Android và iOS trong một dự án Unity.

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

Hoàn thành các bước trong phần Bắt đầu. Ứng dụng Unity của bạn phải nhập trình bổ trợ Unity dành cho quảng cáo trên thiết bị di động của Google.
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ênAndroid vàiOS.

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

Để một sự kiện tuỳ chỉnh tham gia quá trình dàn xếp, bạn phải xác định sự kiện tuỳ chỉnh đó trong AdMob giao diện web. 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 của 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ào trước tên lớp (ví dụ: `appName.className`). 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ữ và số (ví dụ: 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ị 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`).
Nhãn	Nhập tên dành riêng 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

Các 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 đưa vào 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 trên 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 Trình quản lý phần phụ thuộc bên ngoài dành 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 chiến lược 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 ở phầ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 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 dành 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 các 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 tại bài viết Trình quản lý phần phụ thuộc bên ngoài dành cho Unity Bắt đầu. Đ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ột 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 trên SDK mạng quảng cáo bắt buộc, thì bạn không cần xác định rõ 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à phân giải các phần phụ thuộc. Bạn cũng có thể thực thi độ phân giải thủ công bằng lệnh trong trình đơn sau:

Assets > External Dependency Manager > Android Resolver > Force Resolve

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

Unity hỗ trợ nhập tệp *.aar cũng như 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 của bạn.

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ủa bạn bao gồm các tệp *.java hoặc *.kt chưa được biên dịch, thì bạn có thể sử dụng 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 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 mình 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 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 mạng quảng cáo của bên thứ ba có thể có các yêu cầu đặc biệt bắt buộc phải 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 các ứ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 ứng dụng gốc để chuyển đổi có điều kiện giữa ứng dụng iOS và ứng dụng Android
Xác định API để sử dụng tất cả chức năng của SDK mạng quảng cáo bên thứ ba

Phần sau đây cho biết 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 API C#. API này có thể gọi các phương thức trên Android và iOS:

Android

package com.adpub.android;

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

iOS

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

Xác định giao diện chung cho các ứ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. Hãy sử dụng phương thức triển khai này cho trình chỉnh sửa Unity và tất cả các nền tảng ngoài 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 một 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 các lớp trợ giúp Android Java để gọi phương thức tĩnh Android setHasUserConsent().

Vì các lớp trợ giúp Java cho Android chỉ có trong Thời gian chạy Android, nên bạn có thể ngăn lỗi biên dịch bằng cách dùng lệnh của trình biên dịch UNITY_ANDROID để gói lớp như trong đoạn mã. Ngoài ra, bạn có thể sử dụng Định nghĩa tập hợp 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 phương thức ban đầu để trả về cấu hình triển khai ứng dụng chính xác

Giờ đây, khi 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ó cá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 thực thể của IAdPubClient và gọi ứng dụng đó để sử dụng các chức năng cơ bản của 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);
        }
    }
}

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

Dưới đâ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

Hãy 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# để gói các lệnh gọi đến phương thức iOS và Android.