Unity Integration Guide

Environment Requirements

• Supports Unity version 2019.4 and above

Preparation

• Create an app as described in Getting Ready, configure app parameters, and bind the API domain name
• Configure the package name and signature as described in TapSDK Quick Start

Obtaining the SDK

tip

For versions before Unity 2020.3.15, it is recommended to upgrade the Gradle version to avoid build errors later. Refer to the Gradle Upgrade Steps Document.

The following introduces two methods to import the SDK: via Unity Package Manager or by modifying the Packages/manifest.json configuration file. Choose either one based on your project needs:

1. Import via Package Manager Visual Interface

Since the TapTap IAP relies on EDM4U (External Dependency Manager for Unity) to handle Android-related dependencies, the steps to import dependencies are install the EDM4U library first, then install the TapTap IAP.

Installing EDM4U

Below are two methods to install EDM4U, either through OpenUPM installation or manual download and installation:

• Method 1: Install EDM4U via OpenUPM

EDM4U can be downloaded via OpenUPM. Developers can register to use OpenUPM through Edit > Project Settings > Package Manager.

• Method 2: Manual Download and Installation

Developers can download the UPM package from Google APIs for Unity and install it by installing from a local disk.

Installing TapTap IAP

The TapTap IAP can be installed via NPMJS. Developers can register to use NPMJS through Edit > Project Settings > Package Manager.

After configuration, you can install TapTapSDK IAP 4.5.1 in Window > Package Manager > My Registries. If TapTap Payments Global V2 is not in the installation directory, try re-registering NPMJS in Edit > Project Settings > Package Manager.

2. Modify the Packages/manifest.json File

 "dependencies": {
    "com.taptap.sdk.iap": "4.5.1", // Add TapTap IAP
    "com.unity.purchasing": "3.1.0", // Required dependency for TapTap IAP
    "com.google.external-dependency-manager": "1.2.179", // Required dependency for TapTap IAP
    "com.taptap.sdk.core": "4.5.1",
    ...
    ...
  },
  // Add Registries
  "scopedRegistries": [
    {
      "name": "taptap",
      "url": "https://registry.npmjs.org",
      "scopes": ["com.tapsdk"]
    },
    {
      "name": "openupm",
      "url": "https://package.openupm.com",
      "scopes": ["com.google"]
    }
  ]

tip

Handling Android Dependency Failures

EDM4U automatically monitors Android dependencies introduced by the TapTap IAP. However, in certain cases, automatic dependency resolution may fail. Developers can force dependency resolution by using Assets > External Dependency Manager > Android Resolver > Force Resolve. Before testing, ensure that the dependency for com.taptap.android.payment:unity is added to the mainTemplate.gradle file. If EDM4U does not automatically add this dependency, developers can handle it manually.

SDK Guide

We have implemented a new store within the Unity IAP framework to reduce integration costs for apps that already have in-app purchases on Google Play or the App Store. If this is your first time dealing with in-app purchases, we will briefly explain Unity's in-app purchase process. Developers can also refer to Unity's official documentation for detailed information about in-app purchases.

Initialize Unity Gaming Services

Call UnityServices.InitializeAsync() to initialize Unity Gaming Services at once. This method returns a Task object, through which developers can obtain initialization status information.

using System;
using Unity.Services.Core;
using Unity.Services.Core.Environments;
using UnityEngine;

public class InitializeUnityServices : MonoBehaviour
{
    public string environment = "production";

    async void Start()
    {
        try
        {
            var options = new InitializationOptions()
                .SetEnvironmentName(environment);

            await UnityServices.InitializeAsync(options);
        }
        catch (Exception exception)
        {
            // An error occurred during services initialization.
        }
    }
}

Initialize IAP

Ensure that you add TapPurchasingModule during IAP initialization and set the correct clientId and clientToken.

using UnityEngine;
using UnityEngine.Purchasing;
using UnityEngine.Purchasing.Extension;
using TapSDK.IAP;

public class MyIAPManager : IStoreListener {

    private IStoreController controller;
    private IExtensionProvider extensions;

    public MyIAPManager () {
        var builder = ConfigurationBuilder.Instance(TapPurchasingModule.Instance);
        builder.Configure<ITapTapStoreConfiguration>().SetClientId("Your Client ID Here");
        builder.Configure<ITapTapStoreConfiguration>().SetClientToken("Your Client Token Here");
        builder.Configure<ITapTapStoreConfiguration>().SetRegionCode(1); // 0: CN, 1: GLOBAL
        builder.Configure<ITapTapStoreConfiguration>().SetEnableLog(true); // Enable the log. It's recommended to turn it on for Debug and off for Release, with it being off by default.
        builder.AddProduct("100_gold_coins", ProductType.Consumable);

        UnityPurchasing.Initialize (this, builder);
    }

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

    /// <summary>
    /// Called when Unity IAP encounters an unrecoverable initialization error.
    ///
    /// Note that this will not be called if Internet is unavailable; Unity IAP
    /// will attempt initialization until it becomes available.
    /// </summary>
    public void OnInitializeFailed (InitializationFailureReason error)
    {
    }

    public void OnInitializeFailed(InitializationFailureReason error, string str)
    {
    }


    /// <summary>
    /// Called when a purchase completes.
    ///
    /// May be called at any time after OnInitialized().
    /// </summary>
    public PurchaseProcessingResult ProcessPurchase (PurchaseEventArgs e)
    {
        return PurchaseProcessingResult.Complete;
    }

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

Initiate the Purchase Flow

Once IAP is successfully initialized, you can initiate the purchase flow by calling IStoreController.InitiatePurchase.

// Example method called when the user taps a 'buy' button
// to start the purchase process.
public void OnPurchaseClicked(string productId) {
    controller.InitiatePurchase(productId, "developerPayload, e.g. user_id or order_id");
}

Handling Purchase Results

The store listener's ProcessPurchase function is called when a purchase is completed. Your application should fulfill the order whenever a user purchases any item; for example, unlock local content or send the purchase receipt to a server to update the server-side game model.

This process returns a result to indicate whether the application has completed processing the purchase:

Result	Description
PurchaseProcessingResult.Complete	The application has completed processing the purchase, and it should not be notified again.
PurchaseProcessingResult.Pending	The application is still processing the purchase, and unless the ConfirmPendingPurchase function of IStoreController is called, ProcessPurchase will be called again the next time the application starts.

Note that ProcessPurchase may be called at any time after initialization is successful. If the application crashes during the execution of the ProcessPurchase handler, it will be called again when Unity IAP is next initialized, so you may want to implement your own additional deduplication feature.

Reliability

Unity IAP requires explicit confirmation of purchases to ensure that purchases are reliably completed in the event of network interruptions or application crashes. Any purchases completed while the application is offline will be sent to the application the next time it initializes.

Completing Purchases Immediately

When returning PurchaseProcessingResult.Complete, Unity IAP immediately completes the transaction (as shown in the diagram below).

If you are selling consumable items and fulfilling orders from a server (e.g., providing in-game currency in a networked game), you must not return PurchaseProcessingResult.Complete.

Otherwise, if the application is uninstalled before being saved to the cloud, the purchased consumables are at risk of being lost.

Saving Purchases to the Cloud

If you want to save consumable purchase transactions to the cloud, you must return PurchaseProcessingResult.Pending, and only call ConfirmPendingPurchase when the purchase is successfully saved.

When returning Pending, Unity IAP keeps the transaction open in the underlying store until it is confirmed as processed, ensuring that consumable purchase transactions are not lost even if the user reinstalls your application while the consumables are in this pending state.

Debugging

Currently, we only provide the library implementation for Android. Please perform functional debugging in the Android environment (other platforms will be gradually supplemented).