Skip to content

integration guide android

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

/*
Tiêu đề: Hướng dẫn tích hợp cho Android (Java) Mô tả: Hướng dẫn tích hợp Unity Ads trong Android (Java)
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 trình bày các kiểu tích hợp cơ bản để triển khai Unity Ads trong trò chơi Android gốc 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 [API UnityAds](https://unityads.unity3d.com/help/android/api-android#unityads) để có trải nghiệm tích hợp đơn giản hơn. Tuy nhiên, nếu dự định triển khai [Vị trí Cá nhân hóa] (https://unityads.unity3d.com/help/android/personalized-placements-android), bạn phải tích hợp Unity Ads cùng với [API UnityMonetization](https://unityads.unity3d.com/help/ios/api-ios#unitymonetization). Để biết thêm thông tin, vui lòng tham khảo mục 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 một Dự án trên 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, hãy thực hiện theo các bước sau đây để tạo Dự án Unity:

  1. Đăng nhập vào Bảng điều khiển Nhà phát triển và di chuyển đến thẻ Hoạt động.
  2. Chọn Dự ántừ thanh điều hướng bên trái.
  3. Nhấp chọn nút DỰ ÁN MỚI ở góc trên cùng 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 đó chọn Kiếm tiền > Nền tảng từ thanh điều hướng bên trái. Hãy sao chép ID Trò chơi từ App Store của Apple vì bạn sẽ cần ID này để kích hoạt dịch vụ Unity Ads trong trò chơi của bạn.

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 có hiển thị nội dung kiếm tiền. Quản lý Vị trí từ thẻ Hoạt động nằm trong [Bảng điều khiển Nhà phát triển] (https://operate.dashboard.unity3d.com/)bằng cách chọn Dự án của bạn, sau đó chọn Kiếm tiền> Vị trí từ thanh điều hướng bên trái.

Nhấp chọn 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 kiểu vị trí:

  • 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 tưở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 xem quảng cáo nhằm đổi lấy các tặng phẩm. Vị trí Có tặng thưởng sẽ không cho phép người chơi bỏ qua quảng cáo.
  • 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ó một Vị trí (không tặng thưởng) 'video 'và (có tặng thưởng) 'rewardedVideo'. Bạn có thể sử dụng một trong những cài đặ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ự tạo cài đặt của riêng bạn.

Nhập khung Unity Ads

Tải khung Unity Ads tại đây, cụ thể là unity-ads.aar.

Sử dụng Android Studio

  1. Tạo hoặc mở dự án Android hiện có của bạn trong Android Studio.
  2. Thêm một mô-đun mới và nhập vào tệp unity-ads.aar. Đặt tên cho mô-đun là "unity-ads" chẳng hạn.
  3. Nhấp chuột phải vào mô-đun này trong khung nhìn dự án, sau đó chọn Mở Cài đặt Mô-đun > ứng dụng và thêm mô-đun "unity-ads" dưới dạng phần phụ thuộc.
  4. Thêm các nội dung sau vào tệp Hoạt động java của bạn:
import com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;

Không sử dụng Android Studio

Nếu bạn không thể sử dụng các gói .aar bằng hệ thống xây dựng của mình, Unity cũng cung cấp các tài nguyên tương tự dưới dạng tệp ZIP (unity-ads.zip trong các bản phát hành trên GitHub). Thực hiện các bước sau đây để sử dụng Unity Ads:

  1. Thêm classes.jar vào hệ thống xây dựng của bạn.
  2. Hợp nhất tệp kê khai từ AndroidManifest.xml theo cách thủ công. Đảm bảo bạn thêm cả hai hoạt động AdUnitActivityAdUnitSoftwareActivity. Bạn cũng cần cấp quyền INTERNET và quyền ACCESS_NETWORK_STATE.
  3. Nếu bạn đang sử dụng ProGuard, hãy thêm tất cả các dòng lệnh từ proguard.txt vào cấu hình ProGuard của bạn.

Khởi chạy SDK Unity Ads

Để khởi chạy 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 thẻ Hoạt động nằm trong Bảng điều khiển Nhà phát triển bằng cách chọn Dự án, sau đó chọn **Cài đặt **> Cài đặt Dự án từ thanh điều hướng bên trái (xem mục hướng dẫn sử dụng Bảng điều khiển trong Cài đặt Dự án để biết thêm chi tiết).

Trong tập lệnh trò chơi của mình, bạn cần triển khai [giao diện IUnityAdsListener](https://unityads.unity3d.com/help/android/api-android#iunityadslistener) xử lý các lệnh gọi lại quảng cáo. Phương thức khởi chạy để khởi chạy SDK có yêu cầu trình nghe này làm tham số. Hãy khởi chạy 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 com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;

public class InitializeAdsScript extends AppCompatActivity implements View.OnClickListener, IUnityAdsListener {

    private String unityGameID = "1234567";
    private Boolean testMode = true;

    @Override
    protected void onCreate (Bundle savedInstanceState) {
        super.onCreate (savedInstanceState);
        setContentView (R.layout.activity_main);
        // Declare a new listener:
        final UnityAdsListener myAdsListener = new UnityAdsListener ();
        // Add the listener to the SDK:
        UnityAds.addListener(myAdsListener);
        // Initialize the SDK:
        UnityAds.initialize (this, unityGameID, testMode);
    }

    // Implement the IUnityAdsListener interface methods:
    private class UnityAdsListener implements IUnityAdsListener {

        @Override
        public void onUnityAdsReady (String placementId) {
            // Implement functionality for an ad being ready to show.
        }

        @Override
        public void onUnityAdsStart (String placementId) {
            // Implement functionality for a user starting to watch an ad.
        }

        @Override
        public void onUnityAdsFinish (String placementId, UnityAds.FinishState finishState) {
            // Implement functionality for a user finishing an ad.
        }

        @Override
        public void onUnityAdsError (UnityAds.UnityAdsError error, String message) {
            // Implement functionality for a Unity Ads service error occurring.
        }
    }
}

Đối với hàm initialize, tham số myActivity là Hoạt động Android hiện tại. Biến unityGameIDlà [ID Trò chơi Unity] (https://unityads.unity3d.com/help/resources/dashboard-guide#project-settings)cho Dự án của bạn, được tìm thấy trong bảng điều khiển nhà phát triển. Biến myAdsListenerlà trình nghe cho các lệnh gọi lại IUnityAdsListener. Boolean truecho biết trò chơi đang ở chế độ thử nghiệm và sẽ chỉ hiển thị quảng cáo thử nghiệm.

Lưu ý: Bạn phải triển khai từng phương thức gọi lại trong giao diện trình nghe, kể cả khi chúng chỉ là các hàm trống. Bạn sẽ điền chúng theo một logic phù hợp trong các mục sau nếu cần. Để biết thêm thông tin về từng phương thức gọi lại trình nghe, tham khảo tài liệu về [API IUnityAdsListener] (https://unityads.unity3d.com/help/android/api-android#iunityadslistener).

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 API Quảng cáo, bạn chỉ cần khởi chạy SDK và sử dụng chức năng Hiển thị với ID Vị trí mà bạn mong muốn.

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

import com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;

public class ShowInterstitialAds extends AppCompatActivity implements View.OnClickListener, IUnityAdsListener {

    private String unityGameID = "1234567";
    private Boolean testMode = true;
    private String placementId = "video";

    @Override
    protected void onCreate (Bundle savedInstanceState) {
        super.onCreate (savedInstanceState);
        setContentView (R.layout.activity_main);
        // Declare a new listener:
        final UnityAdsListener myAdsListener = new UnityAdsListener ();
        // Add the listener to the SDK:
        UnityAds.addListener(myAdsListener);
        // Initialize the SDK:
        UnityAds.initialize (this, unityGameID, testMode);
    }

    // Implement a function to display an ad if the Placement is ready:
    public void DisplayInterstitialAd () {
        if (UnityAds.isReady (placementId)) {
            UnityAds.show (this, placementId);
        }
    }

    // Implement the IUnityAdsListener interface methods:
    private class UnityAdsListener implements IUnityAdsListener {

        @Override
        public void onUnityAdsReady (String placementId) {
            // Implement functionality for an ad being ready to show.
        }

        @Override
        public void onUnityAdsStart (String placementId) {
            // Implement functionality for a user starting to watch an ad.
        }

        @Override
        public void onUnityAdsFinish (String placementId, UnityAds.FinishState finishState) {
            // Implement functionality for a user finishing an ad.
        }

        @Override
        public void onUnityAdsError (UnityAds.UnityAdsError error, String message) {
            // Implement functionality for a Unity Ads service error occurring.
        }
    }
}

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

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

Tặng thưởng cho người chơi khi họ xem quảng cáo giúp tăng mức độ tương tác của người dùng, đem đế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ì đã xem hết quảng cáo video, hãy sử dụng kết quả FinishState của phương thức gọi lại trình ngheonUnityAdsFinishđể kiểm tra xem liệu người dùng đã xem xong quảng cáo chưa và có nên thưởng cho họ hay không.

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

import com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;

public class ShowRewardedAds extends AppCompatActivity implements View.OnClickListener, IUnityAdsListener {

    private String unityGameID = "1234567";
    private Boolean testMode = true;
    private String placementId = "rewardedVideo";

    @Override
    protected void onCreate (Bundle savedInstanceState) {
        super.onCreate (savedInstanceState);
        setContentView (R.layout.activity_main);
        // Declare a new listener:
        final UnityAdsListener myAdsListener = new UnityAdsListener ();
        // Add the listener to the SDK:
        UnityAds.addListener(myAdsListener);
        // Initialize the SDK:
        UnityAds.initialize (this, unityGameID, testMode);
    }

    // Implement a function to display an ad if the Placement is ready:
    public void DisplayRewardedVideoAd () {
        if (UnityAds.isReady (placementId)) {
            UnityAds.show (this, placementId);
        }
    }

    // Implement the IUnityAdsListener interface methods:
    private class UnityAdsListener implements IUnityAdsListener {

        public void onUnityAdsReady (String placementId) {
            // Implement functionality for an ad being ready to show.
        }

        @Override
        public void onUnityAdsStart (String placementId) {
            // Implement functionality for a user starting to watch an ad.
        }

        @Override
        public void onUnityAdsFinish (String placementId, UnityAds.FinishState finishState) {
            // Implement conditional logic for each ad completion status:
           if (finishState.equals(UnityAds.FinishState.COMPLETED) {
              // Reward the user for watching the ad to completion.
           } else if (result == FinishState.SKIPPED) {
              // Do not reward the user for skipping the ad.
           } else if (result == FinishState.ERROR) {
              // Log an error.
           }
        }

        @Override
        public void onUnityAdsError (UnityAds.UnityAdsError error, String message) {
            // Implement functionality for a Unity Ads service error occurring.
        }
    }
}

Các nút quảng cáo video có tặng thưởng

Sử dụng nút để cho phép người chơi chọn xem quảng cáo là cách triển khai phổ biến đối với quảng cáo video có tặng thưởng. Sử dụng đoạn mã ví dụ bên dưới để tạo nút quảng cáo có tặng thưởng. Chỉ cần quảng cáo vẫn khả dụng, nó sẽ được hiển thị khi người chơi nhấn nút quảng cáo. Để biết thêm thông tin về cách cấu hình các nút, tham khảotài liệucủa Android.

Sau khi bạn triển khai nút của mình, hãy thêm một tập lệnh với đoạn mã sau, trong đó showAdButtonlà nút được cấu hình trong Khung nhìn:

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.view.View;
import android.widget.Button;
import com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;

public class MainActivity extends AppCompatActivity {

    private String unityGameID = "1234567";
    private Boolean testMode = true;
    private String placementId = "rewardedVideo";
    private Button rewardedButton;

    @Override
    protected void onCreate (Bundle savedInstanceState) {
        super.onCreate (savedInstanceState);
        setContentView (R.layout.activity_main);
        // Declare a new listener:
        final UnityAdsListener myAdsListener = new UnityAdsListener ();
        //Add the listener to the SDK:
        UnityAds.addListener(myAdsListener);
        // Initialize the SDK:
        UnityAds.initialize (this, unityGameID, testMode);

        // Find the button in the view hierarchy and set its click function to show ads:
        rewardedButton = findViewById (R.id.showAdButton);
        rewardedButton.setOnClickListener (new View.OnClickListener () {
            @Override
            public void onClick (View v) {
                DisplayRewardedAd ();
                rewardedButton.setEnabled (false);
            }
        });
    }

    // Implement a function to display an ad if the Placement is ready:
    public void DisplayRewardedAd () {
        if (UnityAds.isReady (placementId)) {
            UnityAds.show (this, placementId);
        }
    }

    // Implement the IUnityAdsListener interface methods:
    private class UnityAdsListener implements IUnityAdsListener {

        public void onUnityAdsReady (String placementId) {
            // Implement functionality for an ad being ready to show.
            rewardedButton.setEnabled (true);
        }

        @Override
        public void onUnityAdsStart (String placementId) {
            // Implement functionality for a user starting to watch an ad.
        }

        @Override
        public void onUnityAdsFinish (String placementId, UnityAds.FinishState finishState) {
            // Implement conditional logic for each ad completion status:
            if (finishState.equals(UnityAds.FinishState.COMPLETED)) {
                // Reward the user for watching the ad to completion.
            } else if (finishState.equals(UnityAds.FinishState.SKIPPED)) {
                // Do not reward the user for skipping the ad.
            } else if (finishState.equals(UnityAds.FinishState.ERROR)) {
                // Log an error.
            }
        }

        @Override
        public void onUnityAdsError (UnityAds.UnityAdsError error, String message) {
            // Implement functionality for a Unity Ads service error occurring.
        }
    }
}

Quảng cáo banner

Cấu hình vị trí

Quảng cáo banner yêu cầu một kiểu Vị trí banner chuyên dụng cụ thể.

Triển khai tập lệnh

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

Trong tập lệnh trò chơi của bạn, hãy nhập API BannerView, sau đó triển khai giao diện [IListener] (https://unityads.unity3d.com/help/android/api-android#ilistener) để cấp lệnh gọi lại cho SDK. 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 và các nút để kiểm tra chúng. Để biết thêm thông tin về các lớp được tham chiếu, tham khảo mục API [BannerView] (https://unityads.unity3d.com/help/android/api-android#bannerview).

package com.example.test_app;
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import com.unity3d.ads.UnityAds;
import com.unity3d.services.banners.BannerView;
import com.unity3d.services.banners.UnityBannerSize;
import android.util.Log;
import android.view.View;
import android.view.ViewGroup;
import android.widget.Button;
import android.widget.RelativeLayout;
public class MainActivity extends AppCompatActivity {

    String unityGameID = "3054608";
    Boolean testMode = true;
    Boolean enableLoad = true;
    String bannerPlacement = "banner";
    // Listener for banner events:
    UnityBannerListener bannerListener = new UnityBannerListener();
    // This banner view object will be placed at the top of the screen:
    BannerView topBanner;
    // This banner view object will be placed at the bottom of the screen:
    BannerView bottomBanner;
    // View objects to display banners:
    RelativeLayout topBannerView;
    RelativeLayout bottomBannerView;
    // Buttons to show the banners:
    Button showTopBannerButton;
    Button showBottomBannerButton;
    // Buttons to destroy the banners:
    Button hideTopBannerButton;
    Button hideBottomBannerButton;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        // Initialize Unity Ads:
        UnityAds.initialize (this, unityGameID, null, testMode, enableLoad);
        
        // Set up a button to load the top banner when clicked:
        showTopBannerButton = findViewById(R.id.loadTopBanner);
        showTopBannerButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                showTopBannerButton.setEnabled(false);
                // Create the top banner view object:
                topBanner = new BannerView(view.getContext(), bannerPlacement, new UnityBannerSize(320, 50));
                // Set the listener for banner lifcycle events:
                topBanner.setListener(bannerListener);
                // Request a banner ad:
                topBanner.load();
                // Get the banner view:
                topBannerView = findViewById(R.id.topBanner);
                // Associate the banner view object with the banner view:
                topBannerView.addView(topBanner);
            }
        });

        // Set up a button to load the bottom banner when clicked:
        showBottomBannerButton = findViewById(R.id.loadBottomBanner);
        showBottomBannerButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                showBottomBannerButton.setEnabled(false);
                bottomBanner = new BannerView(view.getContext(), bannerPlacement, new UnityBannerSize(320, 50));
                bottomBanner.setListener(bannerListener);
                bottomBannerView = findViewById(R.id.bottomBanner);
                bottomBannerView.addView(bottomBanner);
                bottomBanner.load();
            }
        });

        // Set up a button to destroy the top banner when clicked:
        hideTopBannerButton = findViewById(R.id.hideTopBanner);
        hideTopBannerButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                // Remove content from the banner view:
                topBannerView.removeAllViews();
                // Remove the banner variables:
                topBannerView = null;
                topBanner = null;
                showTopBannerButton.setEnabled(true);
            }
        });

        // Set up a button to destroy the bottom banner when clicked:
        hideBottomBannerButton = findViewById(R.id.hideBottomBanner);
        hideBottomBannerButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                bottomBannerView.removeAllViews();
                bottomBannerView = null;
                bottomBanner = null;
                showBottomBannerButton.setEnabled(true);
            }
        });
    }

    BannerView SetUpBanner(){
        return new BannerView(this, bannerPlacement, new UnityBannerSize(320, 50));
    }

    // Implement listener methods:
    private class UnityBannerListener implements BannerView.IListener {
		@Override
		public void onBannerLoaded(BannerView bannerAdView) {
		    // Called when the banner is loaded.
        }

		@Override
		public void onBannerFailedToLoad(BannerView bannerAdView, BannerErrorInfo errorInfo) {
		    Log.d("SupportTest", "Banner Error" + s);
            // Note that the BannerErrorInfo object can indicate a no fill (see API documentation).
        }

		@Override
		public void onBannerClick(BannerView bannerAdView) {
            // Called when a banner is clicked.
		}

		@Override
		public void onBannerLeftApplication(BannerView bannerAdView) {
		    // Called when the banner links out of the application.
        }
    }
}

Lưu ý: Ví dụ này sử dụng một trình nghe đơn cho nhiều đối tượng khung nhìn banner. Bạn cũng có thể tạo các trình nghe khác nhau cho từng đối tượng khung nhìn banner.

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 thực thể banner hoặc hiển thị nhiều banner.

Thử nghiệm

Trước khi phát hành trò chơi, hãy bật chế độ thử nghiệm bằng cách thực hiện các bước sau:

  1. Chọn Dự án của bạn từ thẻ** Hoạt động**nằm trongBảng điều khiển Nhà phát triển.
  2. Chọn Kiếm tiền > Nền tảng từ thanh điều hướng bên trái.
  3. Chọn nền tảng mong muốn, sau đó chọn thẻ CÀI ĐẶT.
  4. Kéo xuống mục CHẾ ĐỘ THỬ NGHIỆM và đổi sang ghi đè chế độ kiểm tra máy khách, sau đó bấm vào nút chọn 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