Tài liệu

Hỗ trợ

Unity Ads Monetization

Android developer monetization guide

iOS developer monetization guide

Privacy consent setup

Unity Ads Monetization

Tài liệu tham khảo về Unity Ads SDK API

Access the Unity Ads SDK public API reference to view available classes, methods, and properties you can use in C# to integrate and control ad behavior in your Unity project.
Thời gian đọc 13 phútCập nhật lần cuối a day ago
Sử dụng vùng chứa tên 
Advertisements
để triển khai nội dung quảng cáo cơ bản, chẳng hạn như video quảng cáo có thưởng hoặc không có thưởng, quảng cáo xen kẽ hoặc banner quảng cáo. 
using UnityEngine.Advertisements;
Bài viết này bao gồm những tài liệu sau đây về API: Lớp Kiểu liệt kê Giao diện

Lớp

Advertisement

initialize

public static void Initialize(string gameId, bool testMode, IUnityAdsInitializationListener initializationListener)
Khởi chạy dịch vụ quảng cáo, với ID Trò chơi được chỉ định, trạng thái chế độ thử nghiệm và cài đặt tải Đơn vị Quảng cáo.

Tham số

Mô tả

gameId
Mã định danh trò chơi Unity theo nền tảng cụ thể cho dự án của bạn, được tìm thấy trong bảng điều khiển dành cho nhà phát triển.
testMode
Sử dụng chế độ Thử nghiệm để thử nghiệm tích hợp mà không phân phối quảng cáo trực tiếp. Sử dụng giá trị 
true
để khởi chạy ở chế độ thử nghiệm.
initializationListener
Tùy chọn bật SDK với lệnh gọi lại 
IUnityAdsInitializationListener
 (phiên bản 3.7.0 trở lên).

Load

public static void Load (string adUnitId, IUnityAdsLoadListener loadListener)
Tải nội dung quảng cáo cho một Đơn vị Quảng cáo được chỉ định.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo bạn muốn tải cùng với nội dung quảng cáo.
loadListener
Tùy chọn tải nội dung quảng cáo với lệnh gọi lại 
IUnityAdsLoadListener
 (phiên bản 3.7.0 trở lên).

isReady

static bool IsReady (string adUnitId)
Trả về 
true
nếu quảng cáo đã sẵn sàng hiển thị trong Đơn vị Quảng cáo được chỉ định. Nếu bạn khởi chạy SDK khi 
enablePerPlacementLoad
đang được bật, bạn phải đặt lệnh gọi 
Load
 trước khi đặt lệnh gọi 
Show
.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo bạn muốn truy vấn.

show

public static void Show(string adUnitId, ShowOptions showOptions, IUnityAdsShowListener showListener)
Hiển thị nội dung quảng cáo đã tải trong Đơn vị Quảng cáo được chỉ định.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo bạn muốn hiển thị.
showOptions
Một tập hợp các tùy chọn, bao gồm 
resultCallback
, để sửa đổi hành vi quảng cáo.
showListener
Tùy chọn hiển thị nội dung với lệnh gọi lại 
IUnityAdsShowListener
 (phiên bản 3.7.0 trở lên).

addListener

public static void AddListener(IUnityAdsListener listener)
Thêm hàm lắng nghe sự kiện sẽ nhận được lệnh gọi lại Unity Ads. Trong phiên bản 3.1.0 trở lên, bạn có thể đăng ký nhiều hàm lắng nghe sự kiện. Điều này đặc biệt hữu ích đối với các khách hàng hệ thống phân phối quảng cáo.

Tham số

Mô tả

listener
Hàm lắng nghe sự kiện cho lệnh gọi lại Unity Ads.

removeListener

public static void RemoveListener(IUnityAdsListener listener)
Xóa 
IUnityAdsListener
 đang hoạt động.

Tham số

Mô tả

listener
Hàm lắng nghe sự kiện cho lệnh gọi lại Unity Ads.

GetPlacementState

public static PlacementState GetPlacementState(string adUnitId)
Trả về trạng thái của Đơn vị Quảng cáo được chỉ định.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo bạn muốn truy vấn

isInitialized

public static bool isInitialized
Trả về 
true
nếu SDK được khởi chạy và 
false
nếu SDK không được khởi chạy.

isSupported

public static bool isSupported
Trả về 
true
nếu SDK được hỗ trợ trên nền tảng hiện tại và 
false
nếu SDK không được hỗ trợ trên nền tảng hiện tại.

debugMode

public static bool debugMode
Trả về 
true
nếu SDK đang ở chế độ gỡ lỗi và 
false
nếu SDK không ở chế độ gỡ lỗi. Chế độ gỡ lỗi kiểm soát cấp độ bản ghi từ SDK.

version

public static string version
Trả về phiên bản SDK hiện tại.

isShowing

public static bool isShowing
Trả về 
true
nếu quảng cáo hiện đang hiển thị và 
false
nếu quảng cáo không hiển thị.

Banner

Sử dụng lớp này để triển khai banner quảng cáo.

Load

public static void Load(string adUnitId, BannerLoadOptions options)
Tải nội dung quảng cáo cho Đơn vị Quảng cáo Banner được chỉ định. Nếu bạn khởi chạy SDK khi 
enablePerPlacementLoad
đang được bật, bạn phải đặt lệnh gọi 
Load
trước khi đặt lệnh gọi 
Show
.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo Banner bạn muốn tải.
options
Tập hợp các tùy chọn thông báo cho SDK về sự kiện khi tải banner.

Show

public static void Show(string adUnitId, BannerOptions options)
Hiển thị nội dung quảng cáo cho Đơn vị Quảng cáo Banner được chỉ định. Bạn phải đặt lệnh gọi 
Load
 trước khi đặt lệnh gọi 
Show
.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo Banner bạn muốn tải.
options
Tập hợp các tùy chọn thông báo cho SDK về sự kiện khi hiển thị banner.

Hide

public static void Hide(bool destroy = false)
Cho phép bạn ẩn một banner quảng cáo mà không cần phá hủy hoàn toàn quảng cáo này.

SetPosition

public void SetPosition (BannerPosition bannerPosition)
Đặt vị trí cho banner quảng cáo trên thiết bị.

Tham số

Mô tả

bannerPosition
Vị trí để sử dụng làm điểm neo cho banner quảng cáo.

isLoaded

public static bool isLoaded
Trả về 
true
nếu banner quảng cáo hiện đã tải để hiển thị và 
false
nếu banner quảng cáo chưa tải để hiển thị.

ShowOptions

Triển khai các tùy chọn này để thông báo cho SDK về sự kiện khi hiển thị nội dung trong Đơn vị Quảng cáo. Sử dụng 
ShowOptions.resultCallback
để chuyển kiểu liệt kê 
ShowResult
 về lại Show khi quảng cáo kết thúc.

resultCallback

public ShowResult resultCallback { get; set; }
Lệnh gọi lại này nhận được kết quả của một quảng cáo.

gamerSid

public string gamerSid { get; set; }
Chỉ định mã định danh cho một người dùng cụ thể trong trò chơi.

BannerLoadOptions

Triển khai các tùy chọn này để thông báo cho SDK về những sự kiện khi tải banner quảng cáo.

loadCallback

public LoadCallback loadCallback { get; set; }
Lệnh gọi lại này kích hoạt khi Đơn vị Quảng cáo Banner tải thành công nội dung sẵn sàng hiển thị.

errorCallback

public ErrorCallback errorCallback { get; set; }
Lệnh gọi lại này kích hoạt khi Đơn vị Quảng cáo Banner không tải được nội dung.

BannerOptions

Triển khai các tùy chọn này để thông báo cho SDK về những sự kiện khi hiển thị banner quảng cáo.

bannerCallback

public BannerCallback bannerCallback { get; set; }
Lệnh gọi lại này kích hoạt khi người dùng có thể nhìn thấy banner.

hideCallback

public BannerCallback hideCallback { get; set; }
Lệnh gọi lại này kích hoạt khi banner bị ẩn khỏi người dùng.

clickCallback

public BannerCallback clickCallback { get; set; }
Lệnh gọi lại này kích hoạt khi người dùng nhấp vào banner.

Kiểu liệt kê

PlacementState

Các trạng thái được liệt kê của Đơn vị Quảng cáo.

Giá trị

Mô tả

Ready
Đơn vị Quảng cáo đã sẵn sàng để hiển thị quảng cáo.
NotAvailable
Đơn vị Quảng cáo không khả dụng.
Disabled
Đơn vị Quảng cáo đã bị tắt.
Waiting
Đơn vị Quảng cáo đang ở trạng thái chờ.
NoFill
Đơn vị Quảng cáo không có quảng cáo để hiển thị.

ShowResult

Các trạng thái tương tác của người dùng với quảng cáo được liệt kê. SDK sẽ chuyển giá trị này đến phương thức gọi lại 
OnUnityAdsDidFinish
 sau khi quảng cáo hoàn tất.

Giá trị

Mô tả

Failed
Cho biết quảng cáo không thể hoàn thành do lỗi của dịch vụ Unity.
Skipped
Cho biết người dùng đã bỏ qua quảng cáo.
Finished
Cho biết người dùng đã xem hết quảng cáo.

UnityAdsInitializationError

Các lý do liệt kê cho việc không khởi chạy được SDK.

Giá trị

Mô tả

UNKNOWN
Đã xảy ra lỗi vì lý do không xác định.
INTERNAL_ERROR
Lỗi xảy ra do môi trường hoặc dịch vụ nội bộ.
INVALID_ARGUMENT
Lỗi xảy ra do các đối số không hợp lệ trong phương thức 
Initialize
.
AD_BLOCKER_DETECTED
Xảy ra lỗi do URL bị chặn.

UnityAdsLoadError

Các lý do được liệt kê cho Đơn vị Quảng cáo không tải được.

Giá trị

Mô tả

INITIALIZE_FAILED
Quảng cáo không tải được do SDK chưa được khởi chạy.
INTERNAL_ERROR
Quảng cáo không tải được do lỗi dịch vụ Unity Ads nội bộ.
INVALID_ARGUMENT
Quảng cáo không tải được do đối số không hợp lệ trong phương thức 
Load
.
NO_FILL
Quảng cáo không tải được do không có nội dung nào từ mạng.
TIMEOUT
Quảng cáo không tải được trong khung thời gian quy định.
UNKNOWN
Quảng cáo không tải được vì lý do không xác định.

UnityAdsShowCompletionState

Các lý do liệt kê cho quảng cáo đã kết thúc.

Giá trị

Mô tả

SKIPPED
Cho biết người dùng đã bỏ qua quảng cáo.
COMPLETED
Cho biết quảng cáo đã phát toàn bộ. Điều này thường cho biết người dùng có thể được thưởng khi xem toàn bộ quảng cáo.
UNKNOWN
Không xác định được lý do của việc quảng cáo kết thúc.

UnityAdsShowError

Các lý do liệt kê cho quảng cáo không hiển thị được.

Giá trị

Mô tả

NOT_INITIALIZED
Quảng cáo không hiển thị được do chưa khởi chạy SDK.
NOT_READY
Quảng cáo không hiển thị được do Đơn vị Quảng cáo chưa sẵn sàng.
VIDEO_PLAYER_ERROR
Quảng cáo không hiển thị được do lỗi trình phát đa phương tiện.
INVALID_ARGUMENT
Quảng cáo không hiển thị được do đối số không hợp lệ trong phương thức 
Show
.
NO_CONNECTION
Quảng cáo không hiển thị được do lỗi kết nối internet.
ALREADY_SHOWING
Quảng cáo không hiển thị được do một quảng cáo đã hiển thị.
INTERNAL_ERROR
Quảng cáo không hiển thị được do lỗi dịch vụ Unity Ads nội bộ.
UNKNOWN
Quảng cáo không hiển thị được vì lý do không xác định.

BannerPosition

Các vị trí được liệt kê để neo banner trên màn hình của thiết bị.

Giá trị

Mô tả

TOP_LEFT
Neo banner ở phía trên bên trái của màn hình.
TOP_CENTER
Neo banner ở phía trên chính giữa màn hình.
TOP_RIGHT
Neo banner ở phía trên bên phải của màn hình.
BOTTOM_LEFT
Neo banner ở phía dưới bên trái của màn hình.
BOTTOM_CENTER
Neo banner ở phía dưới chính giữa màn hình.
BOTTOM_RIGHT
Neo banner ở phía dưới bên phải màn hình.
CENTER
Neo banner ở chính giữa màn hình.

Giao diện

IUnityAdsInitializationListener

public interface IUnityAdsInitializationListener {
    void OnInitializationComplete();
    void OnInitializationFailed(UnityAdsInitializationError error, string message);
}
Triển khai giao diện này để xử lý kết quả 
Initialize
.

OnInitializationComplete

Phương thức gọi lại này xử lý logic cho SDK khởi chạy thành công.

OnInitializationFailed

Phương thức gọi lại này xử lý logic cho SDK không khởi chạy được.

Tham số

Mô tả

error
UnityAdsInitializationError
 khiến quá trình khởi chạy thất bại.
message
Thông báo liên quan đến lỗi.

IUnityAdsLoadListener

public interface IUnityAdsLoadListener {
    void OnUnityAdsAdLoaded(string adUnitId);
    void OnUnityAdsFailedToLoad(string adUnitId, UnityAdsLoadError error, string message);
}
Triển khai giao diện này để xử lý kết quả 
Load
.

OnUnityAdsLoaded

Phương thức gọi lại này xử lý logic cho Đơn vị Quảng cáo tải thành công.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo đã tải nội dung.

OnUnityAdsFailedToLoad

Phương thức gọi lại này xử lý logic cho Đơn vị Quảng cáo không tải được.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo không tải được.
error
UnityAdsLoadError
 khiến quá trình tải thất bại.
message
Thông báo liên quan đến lỗi.

IUnityAdsShowListener

public interface IUnityAdsShowListener {
    void OnUnityAdsShowFailure(string adUnitId, UnityAdsShowError error, string message);
    void OnUnityAdsShowStart(string adUnitId);
    void OnUnityAdsShowClick(string adUnitId);
    void OnUnityAdsShowComplete(string adUnitId, UnityAdsShowCompletionState showCompletionState);
}
Triển khai giao diện này để xử lý kết quả 
Show
.

OnUnityAdsShowFailure

Phương thức gọi lại này xử lý logic cho Đơn vị Quảng cáo không hiển thị được.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo không hiển thị được.
error
UnityAdsShowError
 khiến quá trình hiển thị thất bại.
message
Thông báo liên quan đến lỗi.

OnUnityAdsShowStart

Phương thức gọi lại này xử lý logic cho quảng cáo bắt đầu phát.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo hiển thị nội dung.

OnUnityAdsShowClick

Phương thức gọi lại này xử lý logic cho người dùng nhấp vào quảng cáo.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo hiển thị nội dung.

OnUnityAdsShowComplete

Phương thức gọi lại này xử lý logic cho quảng cáo kết thúc.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo hiển thị nội dung.
showCompletionState
Cho biết trạng thái cuối cùng của quảng cáo (quảng cáo đã bị bỏ qua hay đã hoàn thành).

IUnityAdsListener

public interface IUnityAdsListener
{
    void OnUnityAdsReady(string adUnitId);
    void OnUnityAdsDidError(string message);
    void OnUnityAdsDidStart(string adUnitId);
    void OnUnityAdsDidFinish(string adUnitId, ShowResult showResult);
}
Triển khai giao diện này để xử lý các trạng thái quảng cáo khác nhau. Triển khai hàm lắng nghe sự kiện này trong tập lệnh của bạn để xác định logic cho quảng cáo có thưởng.

OnUnityAdsready

Xác định logic cho nội dung quảng cáo sẵn sàng hiển thị thông qua một Đơn vị Quảng cáo được chỉ định.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo đã sẵn sàng.

OnUnityAdsDidError

Xác định logic cho nội dung quảng cáo không hiển thị được do lỗi.

Tham số

Mô tả

message
Thông báo liên quan đến lỗi.

OnUnityAdsDidsStart

Xác định logic cho người chơi kích hoạt quảng cáo để hiển thị.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo hiển thị nội dung.

OnUnityAdsDidfinished

Xác định logic cho người chơi xem toàn bộ quảng cáo.

Tham số

Mô tả

adUnitId
Mã định danh cho Đơn vị Quảng cáo hoàn tất quá trình hiển thị.
showResult
Sự kiện người dùng kết quả của quảng cáo đang hiển thị.