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

Read time 28 minutes

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
Lớp

initialize
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
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
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
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
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
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
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
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
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
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
version

public static string version

Trả về phiên bản SDK hiện tại.

isShowing
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ị.

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

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.

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.

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

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
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
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
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
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
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
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
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
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
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
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ê
Kiểu liệt kê

PlacementState
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
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
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
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
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
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
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
Giao diện

IUnityAdsInitializationListener
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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ị.