Tham khảo về API SDK Unity Ads cho Android

Read time 31 minutes

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

UnityAds
UnityAds

Sử dụng vùng chứa tên này để triển khai nội dung quảng cáo cơ bản, chẳng hạn như quảng cáo video có tặng thưởng hoặc không tặng thưởng, quảng cáo xen kẽ hoặc banner quảng cáo.

initialize
initialize

initialize(final Context context, final String gameId, final boolean testMode, final 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à hàm lắng nghe sự kiện khởi chạy.

Tham sốMô tả
context

Ngữ cảnh Android hiện tại.

gameId

Mã định danh trò chơi Unity theo nền tảng cụ thể cho dự án của bạn, có trong bảng điều khiển Unity Ads Monetization.

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(final String adUnitId, final UnityAdsLoadOptions loadOptions, final IUnityAdsLoadListener listener)

Tải nội dung quảng cáo cho một Đơn vị Quảng cáo đượ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 bạn muốn tải cùng với nội dung quảng cáo.

loadOptions

Một tập hợp các tùy chọn để sửa đổi hành vi quảng cáo.

listener

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

show
show

public static void show(final Activity activity, final String adUnitId, final UnityAdsShowOptions options, final 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ả
activity

Hoạt động hiện tại của Android.

adUnitId

Mã định danh cho Đơn vị Quảng cáo bạn muốn hiển thị.

options

Một tập hợp các tùy chọn để 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.

getVersion
getVersion

public static String getVersion()

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

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.

setDebugMode
setDebugMode

public static void setDebugMode(boolean debugMode)

Kiểm soát số lượng đầu ra bản ghi được xuất từ SDK. Đặt thành true để tạo bản ghi mạnh hơn.

getDebugMode
getDebugMode

public static boolean getDebugMode()

Trả về true nếu SDK ở chế độ gỡ lỗi.

isInitialized
isInitialized

public static boolean isInitialized()

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

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.

UnityAdsLoadOptions
UnityAdsLoadOptions

public class UnityAdsLoadOptions extends UnityAdsBaseOptions

Lớp này chứa siêu dữ liệu tùy chọn để đưa vào bằng phương thức load. Khách hàng sử dụng tính năng đặt giá thầu theo tiêu đề trong hệ thống phân phối quảng cáo bên thứ ba nên sử dụng tính năng này trong trường hợp người đặt giá thầu từ mạng Unity thắng phiên đấu giá quảng cáo.

setAdMarkup
setAdMarkup

public void setAdMarkup(String adMarkup)

Phương thức này lấy chênh lệch giá quảng cáo được trả về từ dịch vụ cho đơn vị đặt giá. Khi đơn vị đặt giá từ mạng quảng cáo của Unity thắng phiên đấu giá thầu theo tiêu đề, SDK Unity Ads sẽ nhận được chênh lệch giá quảng cáo từ sàn giao dịch trung gian. Chuỗi chênh lệch giá quảng cáo chứa thông tin cần thiết để Unity tải và hiển thị quảng cáo.

setObjectId
setObjectId

public void setObjectId(String objectId)

Phương thức này đặt ID đối tượng quảng cáo đã tải làm ID đối tượng quảng cáo hiển thị.

BannerView
BannerView

public BannerView(Activity activity, String adUnitId, UnityBannerSize size)

String mObjectId = UUID.randomUUID().toString(); UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions(); loadOptions.setAdMarkup(markup); loadOptions.setObjectId(mObjectId); UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Tham sốMô tả
activity

Hoạt động hiện tại của Android.

adUnitId

Mã định danh cho Đơn vị Quảng cáo bạn muốn hiển thị.

size

Kích thước của đối tượng banner.

getPlacementId
getPlacementId

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
	loadOptions.setAdMarkup(markup);
	loadOptions.setObjectId(mObjectId);
	UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Trả về ID Đơn vị Quảng cáo cho Đơn vị Quảng cáo Banner.

getSize
getSize

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

size của banner.

setListener
setListener

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Đặt trình nghe đang hoạt động cho banner.

getListener
getListener

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Truy xuất trình nghe đang hoạt động cho banner.

load
load

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Phương thức cơ bản để yêu cầu quảng cáo cho banner.

destroy
destroy

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Đặt lệnh gọi phương thức này để xóa banner khỏi hệ thống phân cấp khung nhìn khi bạn không sử dụng nó nữa.

UnityBannerSize
UnityBannerSize

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Dùng lớp này để xác định chiều cao và chiều rộng của một đối tượng banner.

getWidth
getWidth

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Trả về chiều rộng của đối tượng banner tính bằng pixel.

getHeight
getHeight

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Trả về chiều cao của đối tượng banner tính bằng pixel.

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.
NOT_AVAILABLE
Đơ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ờ.
NO_FILL
Đơn vị Quảng cáo không có quảng cáo để hiển thị.

FinishState
FinishState

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ả
ERROR

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

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.

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.

UnityAdsShowError
UnityAdsShowError

Các lý do được liệt kê cho Đơn vị 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ộ.

UnityAdsError
UnityAdsError

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Các lý do liệt kê cho quảng cáo bị lỗi.

Giao diện
Giao diện

IUnityAdsInitializationListener
IUnityAdsInitializationListener

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

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

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Triển khai giao diện này để xử lý kết quả load.

onUnityAdsAdLoaded
onUnityAdsAdLoaded

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 nội dung.

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

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
	 loadOptions.setAdMarkup(markup);
	 loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

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 nội dung.

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 quảng cáo đã bị bỏ qua hay đã hoàn thành.

IUnityAdsListener
IUnityAdsListener

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

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ả
error
Lỗi khiến quảng cáo bị lỗi.
message
Thông báo liên quan đến lỗi.

onUnityAdsDidStart
onUnityAdsDidStart

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 đang hiển thị quảng cáo.

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

result

Sự kiện người dùng kết quả của quảng cáo đang hiển thị.

IListener
IListener

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

Giao diện này cấp quyền truy cập vào các sự kiện vòng đời của banner. Ngoài ra, bạn có thể triển khai các phương thức ghi đè sau:

String mObjectId = UUID.randomUUID().toString();
UnityAdsLoadOptions loadOptions = new UnityAdsLoadOptions();
		loadOptions.setAdMarkup(markup);
		loadOptions.setObjectId(mObjectId);
		UnityAds.load(mPlacementId, loadOptions, mUnityLoadListener);

onBannerLoaded
onBannerLoaded

Lệnh gọi lại này kích hoạt khi banner tải xong một quảng cáo. Tham số khung nhìn sẽ tham chiếu banner cần được chèn vào hệ thống phân cấp khung nhìn.

Tham sốMô tả
bannerAdView

banner object đã tải.

onBannerClick
onBannerClick

Lệnh gọi lại này kích hoạt khi banner được nhấp vào.

Tham sốMô tả
bannerAdView

banner object đã tải.

onBannerError
onBannerError

Lệnh gọi lại này kích hoạt khi xảy ra lỗi hiển thị banner.

Tham sốMô tả
bannerAdView

banner object đã tải.

errorInfo
Một lớp chứa thông tin về lỗi tải banner.

onBannerLeftApplication
onBannerLeftApplication

Lệnh gọi lại này kích hoạt khi banner liên kết ra ngoài ứng dụng.

Tham sốMô tả
bannerAdView

banner object đã tải.