Skip to content

integration guide ios

Yasuyuki Kamata edited this page Apr 9, 2021 · 1 revision

/* Title: Hướng dẫn tích hợp cho iOS (Objective-C) Mô tả: Hướng dẫn tích hợp Unity Ads SDK cho iOS
Phân loại: 1
*/

LƯU Ý: Tài liệu này đang trong quá trình cập nhật nhằm mô tả thiết kế mẫu Bảng điều khiển tập trung hợp nhất mới. Tham khảo [Hướng dẫn sử dụng bảng điều khiển mới] (https://unityads.unity3d.com/help/The-New-Dashboard)để tìm hiểu về các điểm nổi bật và cách sử dụng bảng điều khiển mới.

Tổng quan

Hướng dẫn này bao gồm việc tích hợp cơ bản triển khai Unity Ads trong trò chơi được tạo với Unity của bạn.

Lưu ý: Nếu bạn chỉ có ý định triển khai quảng cáo video, quảng cáo xen kẽ và quảng cáo banner cho chiến lược kiếm tiền của mình, Unity khuyên bạn nên sử dụng [UnityAdsAPI] (https://unityads.unity3d.com/help/ios/api-ios#unityads) để đơn giản hóa trải nghiệm tích hợp. Tuy nhiên, nếu định triển khai Vị trí Cá nhân hóa, bạn phải tích hợp Unity Ads với [UnityMonetizationAPI] (https://unityads.unity3d.com/help/ios/api-ios#unitymonetization). Để biết thêm thông tin, vui lòng tham khảo phần Tích hợp cho Vị trí Cá nhân hóa.

Trong hướng dẫn này:

Triển khai quảng cáo cơ bản

Tạo Dự án trong Bảng điều khiển Nhà phát triển Unity

Nếu bạn chưa có tài khoản Nhà phát triển Unity (UDN), hãy tạo tài khoản mới tại đây. Khi đã có tài khoản, thực hiện theo những bước tiếp theo để tạo Dự án Unity:

  1. Đăng nhập vào [Bảng điều khiển Nhà phát triển] (https://operate.dashboard.unity3d.com/)và điều hướng đến tab Hoạt động.
  2. Từ thanh điều hướng bên trái, chọn Dự án.
  3. Nhấp vào nút **DỰ ÁN MỚI ** ở góc trên bên phải.

Xác định ID Trò chơi trong Dự án của bạn bằng cách chọn Dự án của bạn, sau đó từ thanh điều hướng bên trái, chọn Kiếm tiền > Nền tảng. Sao chép ID App Store của Apple vì bạn cần nó để kích hoạt dịch vụ Unity Ads trong trò chơi của mình.

Tạo một Vị trí

[Vị trí] (https://unityads.unity3d.com/help/monetization/placements)là các sự kiện được kích hoạt trong trò chơi của bạn, hiển thị nội dung kiếm tiền. Quản lý Vị trí từ tab Hoạt động của [Bảng điều khiển dành cho nhà phát triển] (https://operate.dashboard.unity3d.com/)bằng cách chọn Dự án của bạn, sau đó từ thanh điều hướng bên trái, chọn Kiếm tiền> Vị trí.

Nhấp vào nút THÊM VỊ TRÍ để hiển thị dấu nhắc Tạo Vị trí. Đặt tên cho Vị trí của bạn và chọn loại của nó:

  • Chọn Không tặng thưởng để hiển thị quảng cáo xen kẽ cơ bản hoặc nội dung khuyến mại. Vị trí không tặng thưởng cho phép người chơi bỏ qua quảng cáo sau một khoảng thời gian nhất định.
  • Chọn Có tặng thưởng cho phép người chơi chọn tham gia xem quảng cáo để đổi lấy các ưu đãi. Vị trí có thưởng không cho phép người chơi bỏ qua quảng cáo.
  • Lựa chọn Banner để tạo Vị trí đặt Banner quảng cáo chuyên dụng.

Theo mặc định, mọi dự án hỗ trợ Unity Ads đều có Vị trí (không tặng thưởng) 'video'và (có tặng thưởng)'rewardedVideo'. Vui lòng sử dụng một trong những yếu tố này cho lần triển khai đầu tiên nếu chúng phù hợp với nhu cầu của bạn hoặc tạo ra một phiên bản của riêng bạn.

Nhập khung Unity Ads

Tải xuống khung Unity Ads tại đây.

  1. Kéo và thả khung vào thư mục Dự án Unity của bạn và sao chép nó.
  2. Trong tiêu đề ViewController (.h), thêm Unity Ads và đặt đại diện cho nó:
#import <UIKit/UIKit.h>
#import <UnityAds/UnityAds.h>

@interface ViewController : UIViewController<UnityAdsDelegate>
@end

Sửa đổi danh sách thuộc tính

ID mạng quảng cáo

Những người dùng mục tiêu của trò chơi sử dụng iOS 14 trở lên phải triển khai ID mạng của Unity Ads trong tệp danh sách thuộc tính thông tin. (Info.plist):

  1. Trong trình điều hướng dự án Xcode, chọn Info.plist.
  2. Trong trình chỉnh sửa danh sách thuộc tính, nhấp vào nút thêm (+) bên cạnh bất kỳ khóa nào để tạo khóa thuộc tính mới.
  3. Nhập tên khóaSKAdNetworkItems .
  4. Đối với loại giá trị, hãy chọn Mảng.
  5. Thêm từ điển vào mảng, với SKAdNetworkIdentifierkhóa và chuỗi ID mạng 4DZT52R2T5.skadnetworkUnity Ads.
  6. Bao gồm một từ điển bổ sung vào mảng cho mỗi mạng bổ sung trong [danh sách các ID SKAdNetwork có sẵn] (https://unityads.unity3d.com/help/ios/skadnetwork-ids)(lưu ý rằng Unity sẽ cập nhật danh sách định kỳ).

Để biết thêm thông tin về cách chỉnh sửa danh sách thuộc tính, tham khảo Tài liệu Xcode.

Ví dụ dưới đây hiển thị mảng với các từ điển đại diện cho Unity Ads.

<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>4DZT52R2T5.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>bvpn9ufa9b.skadnetwork</string>
    </dict>
</array>

Mô tả theo dõi người dùng

iOS 14 trở lên yêu cầu đơn vị phát hành phải có quyền theo dõi thiết bị của người dùng trên các ứng dụng. Unity khuyên bạn nên triển khai tiến trình phân quyền tùy chỉnh. Để đưa ra thông báo cho người dùng biết tại sao bạn yêu cầu quyền sử dụng dữ liệu theo dõi thiết bị:

  1. Trong trình điều hướng dự án Xcode, chọn Info.plist.
  2. Trong trình chỉnh sửa danh sách thuộc tính, nhấp vào nút thêm (+) bên cạnh bất kỳ khóa nào để tạo khóa thuộc tính mới.
  3. Nhập tên khóa NSUserTrackingUsageDescription .
  4. Chọn loại giá trị chuỗi.
  5. Nhập thông báo theo dõi ứng dụng một cách rõ ràng vào trường giá trị. Một số ví dụ bao gồm:

    Your data will be used to provide you a better and personalized ad experience.

    We try to show ads for apps and products that will be most interesting to you based on the apps you use, the device you are on, and the country you are in.

    We try to show ads for apps and products that will be most interesting to you based on the apps you use.

    Quan trọng: Unity không cung cấp dịch vụ tư vấn pháp lý. Do đó, thông tin trên trang này không thể thay thế việc tìm kiếm cố vấn pháp lý của riêng bạn để xác định các yêu cầu pháp lý doanh nghiệp và quy trình của bạn cũng như cách giải quyết chúng.

Để biết thêm thông tin, hãy xem [tài liệu dành cho nhà phát triển] của Apple(https://developer.apple.com/documentation/bundleresources/information_property_list/nsusertrackingusagedescription).

Khởi tạo SDK Unity Ads

Để khởi tạo SDK, bạn phải tham chiếu ID Trò chơi của Dự án lên nền tảng thích hợp. Bạn có thể xác định vị trí ID trên tab Hoạt động của Bảng điều khiển dành cho nhà phát triển bằng cách chọn Dự án, sau đó từ thanh điều hướng bên trái, chọn **Cài đặt **> Cài đặt dự án (xem mục hướng dẫn Bảng điều khiển trong **Cài đặt dự án **để biết thêm chi tiết).

Trong phần ViewControllertriển khai của mình (.m), bạn sẽ cần triển khai [UnityAdsDelegategiao diện] (https://unityads.unity3d.com/help/ios/api-ios#unityadsdelegate) xử lý các lệnh gọi lại quảng cáo và tham chiếu nó như một tham số trong initializephương thức. Khởi tạo SDK sớm trong vòng đời thời gian vận hành trò chơi của bạn trước khi cần hiển thị quảng cáo. Ví dụ:

#import "ViewController.h"

@implementation ViewController

// Initialize the SDK:
- (void) viewDidLoad {
    [super viewDidLoad];
    [UnityAds initialize : @"1234567" delegate : self testMode : true];
}

// Implement the ads listener callback methods:
- (void)unityAdsReady:(NSString *)placementId {
    // Perform logic for ads being available to show.
}

- (void)unityAdsDidStart:(NSString *)placementId {
    // Perform logic for a user starting an ad.
}

- (void)unityAdsDidFinish:(NSString *)placementId
withFinishState:(UnityAdsFinishState)state {
    // Perform logic for a user finishing an ad.    
}

- (void)unityAdsDidError:(UnityAdsError)error withMessage:(NSString *)message {
    // Perform logic for a Unity Ads service error.   
}
@end

Lưu ý: Bạn phải triển khai từng phương thức gọi lại trong giao diện người nghe, ngay cả khi hiện tại chúng là các hàm trống. Bạn sẽ điền chúng với logic thích hợp nếu cần trong các phần sau. Để biết thêm thông tin về từng phương pháp gọi lại người nghe, hãy xem tài liệu về [UnityAdsDelegate API giao diện] (https://unityads.unity3d.com/help/ios/api-ios#unityadsdelegate).

Quảng cáo hiển thị xen kẽ

Để hiển thị quảng cáo xen kẽ toàn màn hình bằng [UnityAdsAPI] (https://unityads.unity3d.com/help/ios/api-ios#unityads), khởi chạy SDK và sử dụng showchức năng.

Ví dụ về quảng cáo xen kẽ

#import "ViewController.h"

@implementation ViewController

- (instancetype)init {
    self = [super init];
    if (self) {
        [UnityAds initialize:@"1234567" delegate:self testMode:YES];
    }
    return self;
}

// Implement a function to display an ad for the specified Placement if available:
- (void)showAd:(NSString *)placementId {
    if ([UnityAds isReady:placementId]) {
        [UnityAds show:self placementId:placementId];
    }
}

// Implement the UnityAdsDelegate methods:

- (void)unityAdsReady:(NSString *)placementId {
    // Implement functionality for an ad being ready to show.
}

- (void)unityAdsDidStart:(NSString *)placementId {
    // Implement functionality for a user starting to watch an ad.
}

- (void)unityAdsDidFinish:(NSString *)placementId
withFinishState:(UnityAdsFinishState)state {
    // Implement functionality for a user finishing an ad.    
}

- (void)unityAdsDidError:(UnityAdsError)error withMessage:(NSString *)message {
    // Implement functionality for a Unity Ads service error occurring.   
}
@end

Trong ví dụ này, bạn có thể gọi quảng cáo xen kẽ showAdtừ bất kỳ đâu trong trò chơi nếu muốn hiển thị.

Quảng cáo video có tặng thưởng

Thưởng cho người chơi khi xem quảng cáo giúp tăng mức độ tương tác của người dùng, dẫn đến doanh thu cao hơn. Ví dụ, người chơi có thể được thưởng tiền trong trò chơi, vật phẩm tiêu hao, lượt chơi bổ sung hoặc hệ số kinh nghiệm. Để tìm hiểu thêm về cách thiết kế quảng cáo có tặng thưởng sao cho hiệu quả, tham khảo tài liệu về Các phương pháp quảng cáo hay nhất.

Để thưởng cho người chơi vì đã hoàn thành quảng cáo video, hãy thêm logic cho phương thức unityAdsDidFinishgọi lại để kiểm tra xem người dùng đã hoàn thành quảng cáo hay chưa và có nên được thưởng hay không.

Ví dụ về video có tặng thưởng

#import "ViewController.h"

@implementation ViewController

- (instancetype)init {
    self = [super init];
    if (self) {
        [UnityAds initialize:@"1234567" delegate:self testMode:YES];
    }
    return self;
}

// Implement a function to display an ad for the specified Placement:
- (void)showRewardedAd:(NSString *)placementId {
    // If the Placement is rewarded:
    if ([self.placementId isEqualToString:placementId]) {
        // Show an ad if the Placement has content available:
        if ([UnityAds isReady:placementId]) {
            [UnityAds show:self placementId:placementId];
        }
    }
}

// Implement the UnityAdsDelegate methods, filling out unityAdsDidFinish:

- (void)unityAdsReady:(NSString *)placementId {
    // Implement functionality for an ad being ready to show.
}

- (void)unityAdsDidStart:(NSString *)placementId {
    // Implement functionality for a user starting to watch an ad.
}

- (void)unityAdsDidFinish:(NSString *)placementId
withFinishState:(UnityAdsFinishState)state {
    // Conditional logic dependent on whether the player finished the ad:
    if ([self.placementId isEqualToString:placementId]) {
        if (state == kUnityAdsFinishStateCompleted) {
            // Reward the user for watching the ad to completion:
            [self.delegate giveReward:placementId finishState:state];
        } else if (state == kUnityAdsFinishStateSkipped) {
            // Do not reward the user for skipping the ad.
        } else if (state == kUnityAdsFinishStateError) {
            Debug.LogWarning (“The ad did not finish due to an error.);
        }
    }    
}

- (void)unityAdsDidError:(UnityAdsError)error withMessage:(NSString *)message {
    // Implement functionality for a Unity Ads service error occurring.   
}
@end

Banner quảng cáo

Cấu hình vị trí

Quảng cáo banner yêu cầu một loại [Vị trí đặt banner] chuyên dụng cụ thể(#creating-a-placement).

Triển khai tập lệnh

Lưu ý: Bạn phải khởi tạo Unity Ads trước khi hiển thị quảng cáo banner.

Thêm mã banner của bạn khiViewController triển khai (.m). Mẫu tập lệnh sau đây là ví dụ triển khai để hiển thị hai quảng cáo banner trên màn hình. Để biết thêm thông tin về các lớp được tham chiếu, tham khảo [UADSBannerView] (https://unityads.unity3d.com/help/ios/api-ios#uadsbannerview) phần API.

@interface ViewController () <UADSBannerViewDelegate>
​
// This is the Placement that will display banner ads:
@property (strong) NSString* bannerPlacementId;
// This banner view object will be placed at the top of the screen:
@property (strong, nonatomic) UADSBannerView *topBannerView;
// This banner view object will be placed at the bottom of the screen:
@property (strong, nonatomic) UADSBannerView *bottomBannerView;
​
@end
​
@implementation ViewController
​
- (void)viewDidLoad {
    [super viewDidLoad];
    self.bannerPlacementId = @"banner";
    [UnityAds initialize: @"1234567" delegate: self testMode: YES];
}
​
// Example method for creating and loading the top banner view object: 
- (void)loadTopBanner{
    // Instantiate a banner view object with Placement ID and size:
    self.topBannerView = [[UADSBannerView alloc] initWithPlacementId: _bannerPlacementId size: CGSizeMake(320, 50)];
    // Set the banner delegate for event callbacks:
    self.topBannerView.delegate = self;
    // Add the banner view object to the view hierarchy:
    [self addBannerViewToTopView:self.topBannerView];
    // Load ad content to the banner view object:
    [_topBannerView load];
}
​
// Example method for creating and loading the bottom banner view object: 
- (void)loadBottomBanner{
    self.bottomBannerView = [[UADSBannerView alloc] initWithPlacementId: _bannerPlacementId size: CGSizeMake(320, 50)];
    self.bottomBannerView.delegate = self;
    [self addBannerViewToTopView:self.bottomBannerView];
    [_bottomBannerView load];
}
​
// Example method for discarding the top banner view object (e.g. if there's no fill):
- (void)unLoadTopBanner{
    // Remove the banner view object from the view hierarchy:
    [self.topBannerView removeFromSuperview];
    // Set it to nil:
    _topBannerView = nil;
}
​
// Example method for discarding the bottom banner view object:
- (void)unLoadBottomBanner{
    [self.bottomBannerView removeFromSuperview];
    _bottomBannerView = nil;
}
​
​// Example method for placing the top banner view object:
- (void)addBannerViewToTopView:(UIView *)bannerView {
    bannerView.translatesAutoresizingMaskIntoConstraints = NO;
    [self.view addSubview:bannerView];
    [self.view addConstraints:@[
                               [NSLayoutConstraint constraintWithItem:bannerView
                                                            attribute:NSLayoutAttributeTop
                                                            relatedBy:NSLayoutRelationEqual
                                                               toItem:self.topLayoutGuide
                                                            attribute:NSLayoutAttributeBottom
                                                           multiplier:1
                                                             constant:0],
                               [NSLayoutConstraint constraintWithItem:bannerView
                                                            attribute:NSLayoutAttributeCenterX
                                                         r   elatedBy:NSLayoutRelationEqual
                                                               toItem:self.view
                                                            attribute:NSLayoutAttributeCenterX
                                                           multiplier:1
                                                             constant:0]
                               ]];
}

​// Example method for placing the bottom banner view object:
- (void)addBannerViewToBottomView: (UIView *)bannerView {
    bannerView.translatesAutoresizingMaskIntoConstraints = NO;
    [self.view addSubview:bannerView];
    [self.view addConstraints:@[
                               [NSLayoutConstraint constraintWithItem:bannerView
                                                            attribute:NSLayoutAttributeBottom
                                                            relatedBy:NSLayoutRelationEqual
                                                               toItem:self.bottomLayoutGuide
                                                            attribute:NSLayoutAttributeTop
                                                           multiplier:1
                                                             constant:0],
                               [NSLayoutConstraint constraintWithItem:bannerView
                                                            attribute:NSLayoutAttributeCenterX
                                                            relatedBy:NSLayoutRelationEqual
                                                               toItem:self.view
                                                            attribute:NSLayoutAttributeCenterX
                                                           multiplier:1
                                                             constant:0]
                               ]];
}

​// Implement the delegate methods:
#pragma mark : UADSBannerViewDelegate

- (void)bannerViewDidLoad:(UADSBannerView *)bannerView {
    // Called when the banner view object finishes loading an ad.
    NSLog(@"Banner loaded for Placement: %@", bannerView.placementId);
}

- (void)bannerViewDidClick:(UADSBannerView *)bannerView {
    // Called when the banner is clicked.
    NSLog(@"Banner was clicked for Placement: %@", bannerView.placementId);
}

- (void)bannerViewDidLeaveApplication:(UADSBannerView *)bannerView {
    // Called when the banner links out of the application.
}


- (void)bannerViewDidError:(UADSBannerView *)bannerView error:(UADSBannerError *)error{
    // Called when an error occurs showing the banner view object.
    NSLog(@"Banner encountered an error for Placement: %@ with error message %@", bannerView.placementId, [error localizedDescription]);
    // Note that the UADSBannerError can indicate no fill (see API documentation).
}
@end

Vị trí banner

Bạn có thể đặt đối tượng khung nhìn banner vào hệ thống phân cấp khung nhìn của mình, cũng như với bất kỳ khung nhìn nào khác. Điều này cho phép bạn tùy chỉnh vị trí của từng trường hợp banner hoặc hiển thị nhiều banner.

Thử nghiệm

Trước khi xuất bản trò chơi, hãy bật chế độ thử nghiệm bằng cách làm theo các bước sau:

  1. Từ tab Hoạt động trong Bảng điều khiển dành cho nhà phát triển, hãy chọn Dự án của bạn.
  2. Từ thanh điều hướng bên trái, chọn Kiếm tiền > Nền tảng.
  3. Chọn nền tảng mong muốn, sau đó chọn tab CÀI ĐẶT.
  4. Kéo xuống phần CHẾ ĐỘ THỬ NGHIỆM và chuyển đổi chế độ kiểm tra ghi đè ứng dụng khách, sau đó chọn nút BẬT Chế độ kiểm tra bắt buộc.

Chạy dự án và kiểm tra việc triển khai quảng cáo của bạn.

Lưu ý: Bạn phải bật chế độ thử nghiệm trước khi thử nghiệm tích hợp quảng cáo, để tránh bị gắn cờ gian lận.

Clone this wiki locally