Sự kiện tuỳ chỉnh cho phép nhà xuất bản sử dụng Ad Manager để thêm chế độ dàn xếp kiểu thác nước cho một mạng quảng cáo của bên thứ ba không phải là một mạng trong số 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 thành các bước Bắt đầu. Sự thống nhất của bạn ứng dụng của bạn phải nhập trình bổ trợ Unity của 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 tùy chỉnh bộ chuyển đổi sự kiện, hãy tham khảo hướng dẫn về sự kiện tuỳ chỉnh của chúng tôi về Android và iOS
Xác định sự kiện tuỳ chỉnh
Để một sự kiện tuỳ chỉnh tham gia vào quá trình dàn xếp, sự kiện tuỳ chỉnh đó phải được xác định trong Ad Manager giao diện web. Thêm vào cả hai sự kiện tuỳ chỉnh Nhóm dàn xếp trên Android và iOS.
| 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 tiền tố tên lớp vào
tên của ứng dụng / mô-đun khung (ví dụ:
Bắt buộc phải có tên mục tiêu nếu bạn 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. Với tên mục tiêu,
sẽ có dạng như sau: |
| 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).
|
| Hãng nhạc | Nhập tên duy nhất cho sự kiện. |
| Thông số | Nếu bạn muốn chuyển một đối số chuỗi đến 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 thêm thư viện bổ sung để hoạt động đúng cách. Ví dụ: Bạn có thể cần bao gồm các thư viện sau:
- SDK Android của bên thứ ba
- 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 trên 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ấu phần phần mềm Android hoặc iOS tạo sẵn bằng Phần phụ thuộc bên ngoài Người quản lý 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 thư viện mà bạn sử dụng, bạn có thể cần đến cho mỗi 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 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 phương thức Trình quản lý phần phụ thuộc 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 dữ liệu nhập. Tên tệp và đường dẫn phải đáp ứng 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. Quy tắc
để định cấu hình lệnh nhập tại
Trình quản lý phần phụ thuộc bên ngoài để lấy Unity
Đã bắt đầu. Chiến lược phát hành đĩa đơn
đoạn mã sau bao gồm SDK Android và iOS cùng với sự kiện tuỳ chỉnh
cho một "AdPub" giả định mạng quảng cáo.
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ó phần phụ thuộc vào quảng cáo bắt buộc SDK mạng, 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à phân giải các phần phụ thuộc. Bạn cũng có thể thực hiện giải pháp 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 tùy chỉnh Android của bạn được đóng gói theo cách này, hãy xem trình bổ trợ AAR và Android
Thư viện để xem hướng dẫn về cách
cách đưa những 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ủa bạn bao gồm
trong số các tệp *.java hoặc *.kt chưa được biên dịch, bạn có thể sử dụng tệp nguồn Java hoặc Kotlin
dưới dạng trình bổ trợ.
Nhập tệp nguồn và thư viện tĩnh dành cho iOS
Unity hỗ trợ cấu phần phần mềm *.framework, tệp nguồn *.h và *.m. Đang nhập
Cấu phần phần mềm iOS và tệp nguồn được giải thích trong Hướng dẫn của Unity về mã gốc
trình bổ trợ.
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 để thử nghiệm các sự kiện tùy chỉnh đó đã được nhập chính xác vào ứng dụng của bạn. Quảng cáo có thể mở trình kiểm tra chỉ bằng 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 đòi hỏi gọi trực tiếp các phương thức Android hoặc iOS. Quy trình gọi các phương thức này trực tiếp như sau:
- Xác định giao diện chung cho ứng dụng nền tảng
- Triển khai một ứ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 một ứng dụng factory thành có điều kiện chuyển đổi giữa các ứng dụng iOS và Android
- Xác định 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 trình bày cách triển khai các bước này cho một giả định mạng quảng cáo có tên là "AdPub" trong API C# có thể gọi vào 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 ứ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 cơ sở
API Android và 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);
}
}
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ỉ cần ghi nhật ký tên phương thức. Sử dụng phương thức triển khai này cho trình chỉnh sửa Unity và tất cả
nền tảng khác 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. Phương thức triển khai này sử dụng
InteropServices cần 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 rồi 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ề mã gốc
trình bổ trợ.
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. Phương thức triển khai này sử dụng trình trợ giúp Android Java
lớp học
để gọi phương thức tĩnh của Android setHasUserConsent().
Vì các lớp trợ giúp Android Java chỉ có sẵn trong thời gian Android
trong thời gian chạy, bạn có thể ngăn các lỗi biên dịch bằng trình biên dịch UNITY_ANDROID
lệnh để gói
lớp như minh hoạ trong đoạn mã. Ngoài ra, bạn có thể sử dụng tuỳ chọn Lắp ráp
định nghĩa
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ề phương thức 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
trình biên dịch
lệnh thành
trả về đúng ứng dụng 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
}
}
}
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 từng 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 đó cho 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 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 trình bổ trợ Unity của Google dành cho quảng cáo trên thiết bị di động trên GitHub kho lưu trữ để xem thêm các ví dụ về bộ chuyển đổi dàn xếp của bên thứ ba triển khai API C# để gói lệnh gọi đến phương thức iOS và Android.