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 iOS SDK API

Access the Unity Ads SDK public API reference to view available classes, methods, and properties you can use in Objective-C or Swift to integrate and control ad behavior in your iOS app.
Thời gian đọc 14 phútCập nhật lần cuối a day ago
Sử dụng thư viện 
UnityAds.h
để 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. 
#import "UnityAds.h"
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ê Lệnh ủy quyền

Lớp

UnityAds

#import <UnityAds/UnityAds.h>
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

+ (void) initialize: (NSString *)gameId
  testMode: (BOOL)testMode
  initializationDelegate: (nullable id<UnityAdsInitializationDelegate>)initializationDelegate;
}
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à lệnh ủy quyền khởi chạy.

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ó 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.
initializationDelegate
Tùy chọn bật SDK với lệnh gọi lại 
UnityAdsInitializationDelegate
 (phiên bản 3.7.0 trở lên).

load

+ (void)load: (NSString *)placementId options: (UADSLoadOptions *)options loadDelegate: (nullable id<UnityAdsLoadDelegate>)loadDelegate {
  [UADSLoadModule.sharedInstance loadForPlacementID: placementId
                                            options: options
                                       loadDelegate: loadDelegate];
}
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ả

placementId
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.
options
Một tập hợp các tùy chọn để sửa đổi hành vi tải quảng cáo.
loadDelegate
Tùy chọn tải nội dung quảng cáo với lệnh gọi lại 
UnityAdsLoadDelegate
 (phiên bản 3.7.0 trở lên).

isReady

+ (BOOL)isReady: (NSString *)adUnitId {
  return [UnityServices isSupported] && [UnityServices isInitialized] && [UADSPlacement isReady: adUnitId];
}
Trả về 
YES
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

+ (void)show: (UIViewController *)viewController placementId: (NSString *)placementId showDelegate: (nullable id<UnityAdsShowDelegate>)showDelegate {
  [self show: viewController
    adUnitId: placementId
     options: [UADSShowOptions new]
showDelegate: showDelegate];
}
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ả

placementId
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 hiển thị.
showDelegate
Tùy chọn hiển thị nội dung với lệnh gọi lại 
UnityAdsShowDelegate
 (phiên bản 3.7.0 trở lên).

addDelegate

+ (void)addDelegate: (__nullable id<UnityAdsDelegate>)delegate {
  [UADSProperties addDelegate: delegate];
}
Thêm lệnh ủy quyền 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ả

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

removeDelegate

+ (void)removeDelegate: (id<UnityAdsDelegate>)delegate {
  [UADSProperties removeDelegate: delegate];
}
Xóa hàm lắng nghe sự kiện 
UnityAdsDelegate
 đang hoạt động.

Tham số

Mô tả

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

setDebugMode

+ (BOOL)getDebugMode {
  return [UnityServices getDebugMode];
}
Kiểm soát số lượng đầu ra bản ghi được xuất từ SDK. Đặt thành 
YES
để tạo bản ghi mạnh hơn.

getDebugMode

+ (void)getDebugMode: (BOOL)enableDebugMode {
  [UnityServices setDebugMode: enableDebugMode];
}
Trả về 
YES
nếu SDK đang ở chế độ gỡ lỗi và 
NO
nếu SDK không ở chế độ gỡ lỗi.

getVersion

+ (NSString *)getVersion {
  return [UnityServices getVersion];
}
Trả về phiên bản SDK Unity Ads hiện tại.

isInitialized

+ (BOOL)isInitialized {
  return [USRVSdkProperties isInitialized];
}
Trả về 
YES
nếu SDK được khởi chạy thành công và 
NO
nếu SDK không được khởi chạy thành công.

UADSLoadOptions

#import <UnityAds/UADSBaseOptions.h>

@interface UADSLoadOptions : UADSBaseOptions

@property (nonatomic, readwrite) NSString *adMarkup;

@end
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

- (void)setAdMarkup: (NSString *)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.

UADSBannerView

@interface UADSBannerView : UIView
Sử dụng lớp này để triển khai banner quảng cáo. Unity Ads phiên bản 3.3 trở lên hỗ trợ nhiều phiên bản banner thông qua một Đơn vị Quảng cáo.

initWithPlacementId

-(instancetype)initWithPlacementId:(NSString *)placementId size:(CGSize)size;
Triển khai khung nhìn banner bằng cách sử dụng ID Đơn vị Quảng cáo và kích thước banner. Đặt lệnh gọi 
initWithPlacementId
để khởi chạy đối tượng, sau đó 
load
 để tải nội dung quảng cáo. Lưu ý rằng đối tượng banner truy cập các sự kiện vòng đời thông qua hàm lắng nghe sự kiện 
UADSBannerViewDelegate
 của chúng.

Tham số

Mô tả

placementId
ID Đơn vị Quảng cáo của banner.
size
Kích thước
 của đối tượng banner. Kích thước tối thiểu được hỗ trợ là 320 pixel x 50 pixel.

load

- (void)load;
Phương thức cơ bản để yêu cầu quảng cáo cho banner.

Kiểu liệt kê

UnityAdsPlacementState

typedef NS_ENUM(NSInteger, UnityAdsPlacementState)
Các trạng thái được liệt kê của Đơn vị Quảng cáo.

Giá trị

Mô tả

kUnityAdsPlacementStateReady
Đơn vị Quảng cáo đã sẵn sàng để hiển thị quảng cáo.
kUnityAdsPlacementStateNotAvailable
Đơn vị Quảng cáo không khả dụng.
kUnityAdsPlacementStateDisabled
Đơn vị Quảng cáo đã bị tắt.
kUnityAdsPlacementStateWaiting
Đơn vị Quảng cáo đang ở trạng thái chờ.
kUnityAdsPlacementStateNoFill
Đơn vị Quảng cáo không có quảng cáo để hiển thị.

UnityAdsFinishState

typedef NS_ENUM(NSInteger, UnityAdsFinishState)
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 
unityAdsDidFinish
 sau khi quảng cáo hoàn tất.

Giá trị

Mô tả

kUnityAdsFinishStateError
Cho biết quảng cáo không thể hoàn thành do lỗi của Unity.
kUnityAdsFinishStateSkipped
Cho biết người dùng đã bỏ qua quảng cáo.
kUnityAdsFinishStateCompleted
Cho biết đã phát xong quảng cáo.

UnityAdsInitializationError

typedef NS_ENUM (NSInteger, UnityAdsInitializationError)
Các lý do liệt kê cho việc không khởi chạy được SDK.

Giá trị

Mô tả

kUnityInitializationErrorInternalError
Lỗi xảy ra do môi trường hoặc dịch vụ nội bộ.
kUnityInitializationErrorInvalidArgument
Lỗi xảy ra do các đối số không hợp lệ trong phương thức Initialize.
kUnityInitializationErrorAdBlockerDetected
Xảy ra lỗi do URL bị chặn.

UnityAdsLoadError

typedef NS_ENUM (NSInteger, 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ả

kUnityAdsLoadErrorInitializeFailed
Quảng cáo không tải được do SDK chưa được khởi chạy.
kUnityAdsLoadErrorInternal
Quảng cáo không tải được do lỗi dịch vụ Unity Ads nội bộ.
kUnityAdsLoadErrorInvalidArgument
Quảng cáo không tải được do đối số không hợp lệ trong phương thức 
load
.
kUnityAdsLoadErrorNoFill
Quảng cáo không tải được do không có nội dung nào từ mạng.
kUnityAdsLoadErrorTimeout
Quảng cáo không tải được trong khung thời gian quy định.

UnityAdsShowCompletionState

typedef NS_ENUM (NSInteger, UnityAdsShowCompletionState)
Các lý do liệt kê cho quảng cáo đã kết thúc.

Giá trị

Mô tả

kUnityShowCompletionStateSkipped
Cho biết người dùng đã bỏ qua quảng cáo.
kUnityShowCompletionStateCompleted
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.

UnityAdsShowError

typedef NS_ENUM (NSInteger, 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ả

kUnityShowErrorNotInitialized
Quảng cáo không hiển thị được do chưa khởi chạy SDK.
kUnityShowErrorNotReady
Quảng cáo không hiển thị được do Đơn vị Quảng cáo chưa sẵn sàng.
kUnityShowErrorVideoPlayerError
Quảng cáo không hiển thị được do lỗi trình phát đa phương tiện.
kUnityShowErrorInvalidArgument
Quảng cáo không hiển thị được do đối số không hợp lệ trong phương thức 
show
.
kUnityShowErrorNoConnection
Quảng cáo không hiển thị được do lỗi kết nối internet.
kUnityShowErrorAlreadyShowing
Quảng cáo không hiển thị được do một quảng cáo đã hiển thị.
kUnityShowErrorInternalError
Quảng cáo không hiển thị được do lỗi dịch vụ Unity Ads nội bộ.

UnityAdsError

typedef NS_ENUM (NSInteger, UnityAdsError)
Các lý do được liệt kê của lỗi Unity Ads phát sinh thông qua lệnh gọi lại 
unityAdsDidError
.

Giá trị

Mô tả

kUnityAdsErrorNotInitialized = 0
Dịch vụ Unity Ads hiện chưa được khởi tạo.
kUnityAdsErrorInitializedFailed
Lỗi xảy ra trong quá trình khởi tạo.
kUnityAdsErrorInvalidArgument
Khởi tạo Unity Ads thất bại do tham số không hợp lệ.
kUnityAdsErrorVideoPlayerError
Lỗi xảy ra do trình phát video bị hỏng.
kUnityAdsErrorInitSanityCheckFail
Khởi tạo dịch vụ Unity Ads thất bại do môi trường không hợp lệ.
kUnityAdsErrorAdBlockerDetected
Lỗi xảy ra do trình chặn quảng cáo.
kUnityAdsErrorFileIoError
Lỗi xảy ra do không thể đọc hoặc ghi tệp.
kUnityAdsErrorDeviceIdError
Lỗi xảy ra do mã định danh thiết bị không đúng.
kUnityAdsErrorShowError
Lỗi xảy ra khi cố gắng hiển thị quảng cáo.
kUnityAdsErrorInternalError
Dịch vụ Unity Ads xảy ra lỗi nội bộ.

UnityAdsBannerPosition

Các vị trí được liệt kê mà bạn có thể đặt làm điểm neo cho quảng cáo banner.

Giá trị

Mô tả

kUnityAdsBannerPositionTopLeft
Neo banner ở phía trên bên trái của màn hình.
kUnityAdsBannerPositionTopCenter
Neo banner ở phía trên chính giữa màn hình.
kUnityAdsBannerPositionTopRight
Neo banner ở phía trên bên phải của màn hình.
kUnityAdsBannerPositionBottomLeft
Neo banner ở phía dưới bên trái của màn hình.
kUnityAdsBannerPositionBottomCenter
Neo banner ở phía dưới chính giữa màn hình.
kUnityAdsBannerPositionBottomRight
Neo banner ở phía dưới bên phải màn hình.
kUnityAdsBannerPositionCenter
Neo banner ở chính giữa màn hình.
kUnityAdsBannerPositionNone
Không neo banner.

Lệnh ủy quyền

UnityAdsInitializationDelegate

@protocol UnityAdsInitializationDelegate <NSObject>
- (void)initializationComplete;
- (void)initializationFailed: (UnityAdsInitializationError)error withMessage: (NSString *)message;
@end
Triển khai lệnh ủy quyền này để xử lý kết quả 
initialize
.

initializationComplete

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

initializationFailed

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.

UnityAdsLoadDelegate

@protocol UnityAdsLoadDelegate <NSObject>
- (void)unityAdsAdLoaded: (NSString *)placementId;
- (void)unityAdsAdFailedToLoad: (NSString *)placementId
                     withError: (UnityAdsLoadError)error
                   withMessage: (NSString *)message;
@end
Triển khai lệnh ủy quyền này để xử lý kết quả 
load
.

unityAdsAdLoaded

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ả

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

unityAdsAdFailedToLoad

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ả

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

UnityAdsShowDelegate

@protocol UnityAdsShowDelegate <NSObject>
- (void)unityAdsShowComplete: (NSString *)adUnitId withFinishState: (UnityAdsShowCompletionState)state;
- (void)unityAdsShowFailed: (NSString *)adUnitId withError: (UnityAdsShowError)error withMessage: (NSString *)message;
- (void)unityAdsShowStart: (NSString *)adUnitId;
- (void)unityAdsShowClick: (NSString *)adUnitId;
@end
Triển khai lệnh ủy quyền này để xử lý kết quả 
show
.

unityAdsShowComplete

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

unityAdsShowStart

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.

unityAdsShowClick

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.

unityAdsShowFailed

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

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.
messageThông báo liên quan đến lỗi.

UnityAdsDelegate

@protocol UnityAdsDelegate <NSObject>
- (void)unityAdsReady: (NSString *)placementId;
- (void)unityAdsDidError: (UnityAdsError)error withMessage: (NSString *)message;
- (void)unityAdsDidStart: (NSString *)placementId;
- (void)unityAdsDidFinish: (NSString *)placementId
          withFinishState: (UnityAdsFinishState)state;
@end
Triển khai lệnh ủy quyền này để xử lý các trạng thái quảng cáo khác nhau. Triển khai lệnh ủy quyền này trong tập lệnh của bạn để xác định logic cho quảng cáo có thưởng.

unityAdsReady

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ả

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

unityAdsDidError

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
UnityAdsError
 gây ra lỗi.
message
Thông báo liên quan đến lỗi.

unityAdsDidStart

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

Tham số

Mô tả

placementId
Mã định danh cho Đơn vị Quảng cáo đang hiển thị quảng cáo.

unityAdsDidFinish

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

Tham số

Mô tả

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

UADSBannerDelegate

@protocol UADSBannerViewDelegate <NSObject>

@optional
- (void)bannerViewDidLoad: (UADSBannerView *)bannerView;
- (void)bannerViewDidClick: (UADSBannerView *)bannerView;
- (void)bannerViewDidLeaveApplication: (UADSBannerView *)bannerView;
- (void)bannerViewDidError: (UADSBannerView *)bannerView error: (UADSBannerError *)error;
@end
Lệnh ủy quyền này cung cấp lệnh gọi lại từ các sự kiện banner của Unity Ads.

bannerViewDidLoad

Lệnh gọi lại này kích hoạt khi banner đã tải thành công nội dung quảng cáo.

bannerViewDidClick

Lệnh gọi lại này kích hoạt khi người dùng nhấp vào banner quảng cáo.

bannerViewDidLeaveApplication

Lệnh gọi lại này kích hoạt khi banner bị đóng do người dùng thoát khỏi ứng dụng.

bannerViewDidError

Lệnh gọi lại này kích hoạt khi UnityAdsBanner gặp lỗi.

Tham số

Mô tả

error
UADSBannerError
gây ra lỗi.

UADSBannerAdRefreshViewDelegate

@protocol UADSBannerAdRefreshViewDelegate <NSObject>

@optional
- (void)unityAdsRefreshBannerDidLoad: (UADSBannerAdRefreshView *)bannerAdRefreshView;
- (void)unityAdsRefreshBannerDidNoFill: (UADSBannerAdRefreshView *)bannerAdRefreshView;
- (void)unityAdsRefreshBannerDidShow: (UADSBannerAdRefreshView *)bannerAdRefreshView;
- (void)unityAdsRefreshBannerDidHide: (UADSBannerAdRefreshView *)bannerAdRefreshView;
- (void)unityAdsRefreshBannerDidClick: (UADSBannerAdRefreshView *)bannerAdRefreshView;
- (void)unityAdsRefreshBannerDidError: (UADSBannerAdRefreshView *)bannerAdRefreshView message: (NSString *)message;
@end
Lệnh ủy quyền này cung cấp lệnh gọi lại từ các sự kiện banner làm mới của Unity Ads.

unityAdsRefreshBannerDidLoad

Được gọi khi đã tải banner và sẵn sàng được đặt trong phân cấp khung nhìn.

unityAdsRefreshBannerDidNoFill

Được gọi khi không có nội dung quảng cáo nào cho banner.

unityAdsRefreshBannerDidShow

Được gọi khi banner hiển thị với người dùng.

unityAdsRefreshBannerDidHide

Được gọi khi banner ẩn với người dùng.

unityAdsRefreshBannerDidClick

Được gọi khi người dùng nhấp vào banner quảng cáo.

unityAdsRefreshBannerDidError

Được gọi khi 
UnityAdsBanner
gặp lỗi.

Tham số

Mô tả

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