Unity IAP Xiaomi integration guide

Overview

Unity IAP provides a streamlined channel for developers outside of China to publish apps in the Chinese market. This guide introduces the Unity Channel SDK, and describes the end-to-end process for a developer publishing IAP content to the Xiaomi Mi Game Center platform.

Publishing a game to the Mi Game Center is a 3-step process:

1. Submit your Xiaomi-configured game package through Unity Cloud Build.
2. In the Xiaomi-Unity developer portal, populate your game’s store metadata.
3. Release your game upon Xiaomi approval.

Xiaomi Mi Game Center

The Mi Game Center is Xiaomi’s official Android store. It allows users to search, browse and purchase products for the Xiaomi platform using a secure payment portal. For more information, visit Unity’s Xiaomi partner site.

Unity Channel

Unity Channel is an internal component of Unity IAP that helps developers outside of China access the Chinese app store market by facilitating user login, payment management, and Chinese Government app distribution regulatory approval.

Because of Unity Channel, Xiaomi Mi Pay integration differs from Google Play and iTunes in the following ways:

• Xiaomi games require a Unity IAP Catalog. Google Play and iTunes support entirely backend-defined Products. However, the Xiaomi client SDK built into Unity IAP depends on the Product IDs and metadata being available on the client.
• Codeless IAP support is planned but not yet available (check forums for updates).
• During Unity IAP initialization, Product ownership information is not returned to the client. Therefore, developers must track user purchases through their servers or locally on the device.

Requirements

• The Unity Channel SDK is designed for use with Unity versions 2017.1+, however it is backwards compatible with versions 5.3+.
• The Unity Channel SDK is included in Unity IAP versions 1.13.0+.
• Xiaomi IAP support is only available for Android builds. The appropriate Android and Java SDKs are required.
• Pushing builds to Xiaomi requires the Unity Cloud Build service.
• Xiaomi does not currently support Codeless IAP implementation.

Building your Project for Xiaomi

This section describes the process of configuring your game through the Unity Editor using the Unity IAP SDK:

• Setting up your Project
• Adding the Xiaomi package to your Project
• Enabling IAP
• Creating an IAP Catalog

Setting up your Project

Configuring for Android

Xiaomi only supports Android builds. Configuring your Project for Android is a 4-step process.

1. Download and install the Android and Java SDKs. For more information, see documentation on Getting started with Android Development.
2. Set the SDK file path targets. In the Unity Editor, go to Edit > Preferences (Windows) or Unity > Preferences (Mac) , then select External Tools from the left navigation bar. Scroll down to the Android section, and set the SDK and JDK fields to reflect the file paths where you installed the Android and Java SDKs respectively (see image 1.1, below; note that you can select the Download buttons next to each field for direct links to each SDK’s download webpage).
3. Set the application’s Package Name. Xiaomi requires the application’s Package Name to follow the “BuildName.mi” convention. Select Edit > Project Settings, then select the Player category to open the Player settings. Then select the Android tab (see image below) and, under the Other Settings panel, navigate to the Identification section, and set the Package Name field (see image 1.2, below).
4. Build the Project for Android. In the Editor, select File > Build Settings, then select Android from the menu. Select Build to test that Unity can locate the SDKs and compile your build.

Adding the Xiaomi Asset package to your Project

In the Editor, enable Unity IAP from the Services window (Window > General > Services; see documentation on Setting up Unity IAP). Be sure to Import the IAP Asset package when prompted (see image below). As of version 1.13.0, the Unity IAP Asset package includes the Unity Channel and Xiaomi SDKs.

[Optional] Standalone SDK

If you wish to publish your app to the Mi Game Center without in-app purchasing, install the Xiaomi Unity Channel standalone SDK from the Build Settings window (File > Build Settings) by selecting Android from the Platform menu and selecting Add from the Xiaomi Game Center menu option that appears.

App store settings

Unity Channel includes an Asset that provides an Editor interface for managing app store credentials and test mode functionality. This AppStoreSettings Asset installs to Assets/Plugins/UnityChannel/XiaomiSupport/Resources when you import the Unity IAP Asset package. You can also create it manually in the Editor by selecting Assets > Create > App Store Settings. Access the interface by selecting the Asset and viewing the Inspector.

Note: The AppStoreSettings Asset is only available in Unity 5.6+.

In order to communicate, the Unity and Xiaomi servers both require unique identifiers for your game. Note that you can retrieve your Unity Client credentials here by pasting your Project ID into the search field. Unity 5.3 or 5.4 users must retrieve and set credentials this way, as they cannot access the AppStoreSettings Asset. The settings depicted in the image above are described below:

1. The Generate Unity Client button populates Unity credentials that bind to your Project.
   
   Note: Generating, loading, or updating Unity client credentials sends networked requests to Unity’s backend server. Progress for this operation appears in the Console log.
   
   
2. Client ID and Client Key are required to communicate through Unity IAP to the Unity Channel and Xiaomi backends. The Unity Channel backend proxies receipt validation requests (for more information, see documentation on Unity IAP receipt validation, and the Receipt validation and extensions section of the Unity Channel SDK documentation).
3. Client RSA Public Key is an optional security layer. Use it to receive server callbacks for client-side receipt validation, or to integrate with Unity server APIs.
   
   Note: Client Secret is another optional security layer should you wish to implement server-side validation. Client Secret is auto-generated with the other credentials. Refresh it any time by selecting Update Client Secret from the AssetStoreSettings Asset.
   
   
4. Provide an optional Callback URL for your game server to receive purchase transaction data.
5. Xiaomi distributes App ID, App Key, and App Secret credentials during the submission process. You must save them to your App Store Settings before submitting your final build for publication.
6. Test Mode is required for testing your application’s purchase flows and submitting to Xiaomi.

You need these credentials and the test mode toggle at various points of the integration process. Note that App Store Settings data updates server-side, as opposed to saving to your client.

Implementing IAP

Enabling the Unity IAP service

If you enabled Unity IAP to import the Xiaomi Asset package, no action is required. Otherwise, see documentation on Setting up Unity IAP to enable the service.

You can also install the latest Unity IAP plugin through the Unity Asset Store.

Creating a Product Catalog

The Xiaomi client SDK built into Unity IAP depends on Product metadata being available in the client. As such, you must define your Products through the Editor’s IAP Catalog GUI (Window > Unity IAP > IAP Catalog).

Populating the Catalog The IAP Catalog GUI defines Products along with their metadata for the game client’s runtime. Documentation on Codeless IAP contains information on configuring Products through the IAP Catalog. The following Product attributes warrant attention for Xiaomi specifically:

1. ID is a unique identifier (string data type) required by the Mi Game Center.
2. Type indicates the durability of the Product. Xiaomi supports consumable and non-consumable Product Types. It does not support subscription Product Types.
3. The Descriptions section controls Title and Description text for use on the Mi Store. You must specify Simplified Chinese from the Locale drop-down menu (this is currently the only supported language).
4. Pay Configuration controls the Product’s price point. The Unity Channel SDK supports predefined Chinese yuan pricing tiers for Xiaomi, but not arbitrary values.

For more information about Product attributes and their parameters, see documentation on Defining Products.

Exporting the Catalog for Xiaomi’s developer portal

In the Editor, in the IAP Catalog window, export the Catalog by selecting App Store Export > Xiaomi Mi Pay Catalog.

Export the MiGameProductCatalog.prop file to your location of choice. Import your Product catalog on the Xiaomi developer portal by navigating to your Project’s IAP Configuration tab and selecting Import (see section on Importing your IAP Product catalog, below).

Exporting the IAP Catalog also writes a copy of the MiGameProductCatalog.prop file to your Project’s Assets/Plugins/Android/assets/ directory (see image below). Unity IAP uses this file in the IAP Catalog editor and at runtime. It also serves as a default Product catalog for your app if no catalog file is explicitly imported through the Xiaomi developer portal.

Client-side initialization

Unity IAP typically requires a configuration builder that consumes IAP Catalog data to be parsed for the destination store, followed by the Unity IAP Initialize() API (see documentation on Initializing IAP).

Xiaomi games require an extra step prior to initializing IAP, because the Mi Game Center requires apps to share their credentials through the login API at launch.

The modified initialization process becomes:

1. Initialize the Unity Channel Xiaomi API.
2. Log in to the Unity Channel Xiaomi API.
3. Initialize Unity IAP as normal by running a configuration builder instance, then call the Unity IAP initialize() API.

Execute these steps early in the game’s runtime lifecycle, preferably at launch. You can implement them in the same script.

1. Xiaomi Login

The following example illustrates how to modify initialization using the Unity Channel SDK to call the login API:

using AppStoreSupport;
using System;
using System.Collections;
using UnityEngine;
using UnityEngine.Purchasing;
using UnityEngine.Store;

// Run the script once, at game launch.
public class UnityChannelSample : MonoBehaviour
{
    // Xiaomi login requires a login listener.
    // Create one by implementing the ILoginListener abstract class included in the Unity Channel SDK.
    class SampleLoginListener : ILoginListener
    {
        public Action initializeIAP;

        // Step 1 succeeded; call step 2
        public void OnInitialized()
        {
            Debug.Log("Initialization succeeded.");
            UnityEngine.Store.StoreService.Login(this); // If initialization succeeds, initiate Xiaomi login
        }

        // Step 1 failed; display error message and recourses
        public void OnInitializeFailed(string message)
        {
            Debug.Log("Initialization failed.");
        }

        // Step 2 completed; call step 3
        public void OnLogin(UserInfo userInfo)
        {
            Debug.Log(string.Format("Login successful: userId {0}, userLoginToken {1}, channel {2}", userInfo.userId, userInfo.userLoginToken, userInfo.channel));
            // When login succeeds, proceed to initializing IAP
initializeIAP(); 
        }

        // Step 2 failed; display error message and recourses
        public void OnLoginFailed(string message)
        {
            Debug.Log("Login failed.");
        }
    }
}

Note: You must use all of the functions in the above sample code, which account for all possible steps of the login process. However, you can choose the actions called within each function. In this example, debug text appears in place of action calls. In this example, the OnLogin() method initiates a Unity IAP initialization function.

2. Xiaomi initialization

Next, initialize the Xiaomi API using a login listener and the app credentials stored in your AppStoreSettings Asset:

    void Awake()
    {
        // Create a login listener based on the SamleLoginListener class
        SampleLoginListener loginListener = new SampleLoginListener();

        // Tie the initializeIAP Action (from the SampleLoginListener class) to a function (defined in the next step)
        loginListener.initializeIAP = ConfigureIAP;

        // Access the AppStoreSettings Asset to generate AppInfo with your stored credentials. The AppStoreSettings class is part of the AppStoreSupport library. 
        AppStoreSettings appStoreSettings = Resources.Load<AppStoreSettings>("AppStoreSettings");

        // Initialize Xiaomi using the credentials and login listener
        UnityEngine.Store.StoreService.Initialize(appStoreSettings.getAppInfo(), loginListener);
    }

Upon loading your Project’s AppStoreSettings Asset, the getAppInfo() function returns credential data for the Mi Game Center store initialization process.

3. Unity IAP configuration builder and initialization

Finally, use a configuration builder to translate Product data from your IAP Catalog for Xiaomi, then initialize Unity IAP:

    // The configuration builder requires a store listener. 
    // Create one by implementing the IStoreListener abstract class.
    class StoreListener : IStoreListener
    {
        private IStoreController controller;
        private IExtensionProvider extensions;

        // Called when Unity IAP is ready to make purchases.
        public void OnInitialized(IStoreController controller, IExtensionProvider extensions)
        {
            this.controller = controller;
            this.extensions = extensions;
        }

        // Note that this will not be called if Internet is unavailable;
        // Unity IAP will attempt initialization until it becomes available.
        public void OnInitializeFailed(InitializationFailureReason error)
        {
        }

        // Called when a purchase completes, or Unity IAP encounters an unrecoverable initialization error;
        // may be called at any time after OnInitialized().
        public PurchaseProcessingResult ProcessPurchase(PurchaseEventArgs e)
        {
            return PurchaseProcessingResult.Complete;
        }

        // Called when a purchase fails.
        public void OnPurchaseFailed(Product i, PurchaseFailureReason p)
        {
        }
    }

    // Run a configuration builder to define your Products
    public void ConfigureIAP()
    {
        // Load Products from the IAP Catalog
        var module = StandardPurchasingModule.Instance();
        var builder = ConfigurationBuilder.Instance(module);
        var catalog = ProductCatalog.LoadDefaultCatalog();

        // Loop through Products in Catalog, extracting metadata to the builder
        foreach (var product in catalog.allProducts)
        {
            if (product.allStoreIDs.Count > 0)
            {
                var ids = new IDs();
                foreach (var storeID in product.allStoreIDs)
                {
                    ids.Add(storeID.id, storeID.store);
                }
                builder.AddProduct(product.id, product.type, ids);
            }
            else
            {
                builder.AddProduct(product.id, product.type);
            }
        }

        // Create a store listener based on the StoreListener class
        StoreListener storeListener = new StoreListener();

        // Initialize Unity IAP
        UnityPurchasing.Initialize(storeListener, builder);
    }

The configuration builder references Product IDs and Product Types to automate population of Price, Type, Title, and Description metadata. It uses your IAP Catalog’s IAPProductCatalog.json file and the builder object instantiated during Unity IAP initialization.

Implementing IAP purchasing

For information on methods for in-game purchase implementation, see documentation on the following:

• Codeless IAP
• Unity IAP Initialization
• Unity Channel SDK

Testing integration

Test your game’s purchase flows on a non-Xiaomi Android device by toggling test mode in the AppStoreSettings Asset interface. Unity Channel also provides an API for toggling test mode:

AppInfo.debug = true;

The Unity Channel wrapper includes the AppInfo class, and passes data to the Xiaomi SDK. To submit your app to Xiaomi, you must enable test mode. Test mode also bypasses the credit card requirement for testing purposes. After enabling test mode, build your Project and launch the resulting APK file from an Android device.

To test real purchasing, set test mode to false and test on a Xiaomi device. Please note that real purchasing requires a Xiaomi Mi Pay Account and appropriate currency such as Chinese Yuan.

Submitting to Xiaomi

This section describes the process of submitting your game through the Unity Editor using the Unity IAP SDK:

1. Set the IAP target
2. Test IAP integration
3. Register the application
4. Push your game to the Xiaomi portal

Setting the IAP target

In the Unity Editor, set Unity IAP to target Mi Game Pay by selecting Window > Unity IAP > Android > Target Xiaomi Mi Game Pay. This enables Xiaomi for the next build of the game’s APK. It also creates the configuration file that informs Unity IAP at runtime to use the Xiaomi Mi Pay native billing API.

Pushing the Project to the Xiaomi developer portal

Before pushing to Xiaomi, test building your game, either locally or by configuring the Project with an Android build target in Unity Cloud Build (see documentation on Cloud Build).

In the Editor, enable Cloud Build through the Unity Services window (see documentation on Cloud Build implementation).

Upload the build

Upload your build to the build history for your project, using one of two methods:

From the Editor:

1. In the Cloud Build Services window, select Manage Target Builds > Add New Target.
2. In the TARGET SETUP menu, set the PLATFORM field to Android and enter a useful TARGET LABEL. Then select Next: Save.
3. Select Start Cloud Build, then select the target build you just created.

From the Unity Cloud Build Developer Dashboard:

1. Navigate to your Project’s Cloud Build History.
2. Select Upload, then select the APK file you built from the Editor.

Push the build to Xiaomi

Push the the hosted build to Xiaomi’s developer portal, using one of two methods:

From the Editor:

In the Cloud Build Services window, locate the desired build from the build history timeline and select Push to Xiaomi. Verify that you want to push, and that the action completes.

From the Unity Cloud Build Developer Dashboard:

1. Navigate to your Project’s Cloud Build History.
2. Select Download .APK file, then select Push to Xiaomi from the dropdown menu.

Note: Only the owner of the organization that your project is under will be able to deploy to Xiaomi.

Configuring the game in the Xiaomi developer portal

Your UDN credentials grant access to your uploaded Projects in the Xiaomi Unity developer portal. The first time you log in, you must acknowledge Xiaomi’s Terms and Conditions before proceeding to your Projects list. Locate the Project you wish to submit. Its status (highlighted below) will initially read Version1.0: Draft. Select the clipboard icon to view a submission log of your Project’s status changes throughout the process. Select the status link to expand your Project’s metadata details.

The following details are illustrated in the image below:

1. Basic Information

This section contains the text to display on the Mi Game Center.

• Game Name is the English title of your app. Xiaomi will manually translate the English title to Chinese for the customer-facing storefront.
• Name of Developer is your customer-facing publisher name.
• Game Introduction is the English description of your app. Note that Xiaomi will manually translate the English title to Chinese for the customer-facing storefront.
• Email is the developer contact information Xiaomi should use to initiate feedback.

2. Target Device

This section contains marketing assets for Phone and Tablet devices that display on the Mi Game Center. Note the following guidelines:

• You must upload a minimum of 3 images for each device type that you check.
• Image dimensions must either be 1080 x 720 pixels (landscape), or 720 x 1080 pixels (portrait).

Submitting for review

When you are ready, select Submit to submit your game to Xiaomi for review. The status indicator for your Project changes to In review. While your Project is in review, you cannot edit its details. Expand the Project and select Cancel to cancel the review and revise the Project’s details.

Regional compliance with regulations

You need an ISBN publication license to publish your app. Xiaomi provides comprehensive support for the ISBN approval process through the State Administration of Press, Publication, Radio, Film and Television (SAPPRFT).

Xiaomi does not guarantee that the SAPPRFT will approve all games (see SAPPRFT submission guidelines). To meet store and country compliance rules, you may need to make some changes to your game.

Content guidelines for a smooth approval process

Consider the following tips when submitting for Chinese government approval:

• Avoid depicting Chinese national landmarks and symbolism (for example, the Chinese national flag, or the Great Wall) in a manner that could be considered undignified.
• Avoid depicting Chinese national politics, history, conflicts, or religions entirely.
• When creating maps and regions in your game’s world, avoid defining regions that conflict with China’s existing geopolitics and borders.
• Avoid depiction of gambling, and gambling mechanics of any kind.
• China has tight restrictions on mature content. Avoid depictions of nudity, realistic violence, and drug usage.
• Avoid depicting minors participating in any illegal activities, such as underage drinking and smoking.

Importing your IAP Product catalog

Before finalizing your submission, follow these steps to ensure Xiaomi has your most current IAP Product catalog:

1. Select your Project, then select IAP Configuration from the left navigation bar.
2. Select Import.
3. Import the MiGameProductCatalog.prop file you exported from your Project.
4. Verify the contents of the catalog, then select Confirm.
5. A list of your imported Products appears. Select Submit to save the catalog to your submission.

Publishing to the Mi Game Center

Credentials

When Xiaomi indicates approval, your project status changes to Approved and receives the following credentials:

• App ID
• App Key
• App Secret

Enter these credential values in the AppStoreSettings Asset or initialization script, then set test mode to false. Create a new build of your game, and push this build to Xiaomi as before.

Xiaomi provides a developer contract via email. Once you sign the contract, Xiaomi facilitates the government approval process. It will notify you when the game receives an ISBN license and clearance to publish on the Mi Game Center.

Xiaomi’s content review process typically takes 1–2 business days, unless it recommends changes. The government approval process and license distribution, however, can take 4–8 months. For more information on the review process, please see the FAQs section of the Unity-Xiaomi partner page.