Skip to content

Install the module, initialize, and log in

This document explains how to install and initialize the payment module in the Hive Axyl SDK, and then prepare a login session so that you can use the payment features. If you have not installed the Hive Axyl SDK yet, first install the Hive Axyl SDK.

1. Install the payment module

Install the payment module in the Hive Axyl SDK in the following order.

1.1. Select common modules

Select the common module, which is the minimum feature set needed to use Hive Axyl.

  • com.com2usplatform.hiveaxyl.core: Initialization that you call when starting the SDK, and basic features that other modules use in common

1.2. Select modules for the payment feature

To use the payment feature, also select the following modules.

  • com.com2usplatform.hiveaxyl.auth: Features needed to prepare a login session, such as account creation, login, and token issuance
  • com.com2usplatform.hiveaxyl.payments: Features needed for the payment flow, such as getting the product list, recording purchases, confirming payments, recording delivery results, and restoring purchases

The app user is the one who pays for in-app products. Therefore, payment works only when there is a user login session, and for this you need both the payment module and the authentication module.

Note

To integrate the payment window of stores such as Google and Steam, also install the dedicated plugin for each provider. For details, see the integration setup for each payment provider below.

1.3. Install modules

The module installation procedure is the same as SDK installation. Because the Hive Axyl SDK is installed only through a scoped registry, additionally declare the modules needed for payment in the Hive Axyl Scoped Registry that you registered when you installed the SDK.

In dependencies of Packages/manifest.json, add com.com2usplatform.hiveaxyl.auth for preparing the login session and com.com2usplatform.hiveaxyl.payments, the payment feature module, together with com.com2usplatform.hiveaxyl.core.

{
  "scopedRegistries": [
    {
      "name": "Hive Axyl",
      "url": "https://package.openupm.com",
      "scopes": [
        "com.com2usplatform.hiveaxyl"
      ]
    }
  ],
  "dependencies": {
    "com.com2usplatform.hiveaxyl.core": "1.0.0",
    "com.com2usplatform.hiveaxyl.auth": "1.0.0",
    "com.com2usplatform.hiveaxyl.payments": "1.0.0"
  }
}

1.4. Verify the installation

The following code is an example that quickly checks whether the namespaces of the installed SDK and the authentication and payment modules are recognized correctly.

using Hive.Axyl.Core;
using Hive.Axyl.Auth;
using Hive.Axyl.Payments;

The installation step is complete when all of the following items are met.

  • The installed modules are shown as Installed in Unity Package Manager

2. Initialize the SDK

Method

Initialize

Hive Axyl SDK initialization is a preparation step that the app performs once before it uses Hive Axyl SDK features. Call initialization when the app starts to prepare to use the features that Hive Axyl provides, such as authentication, payment, and push.

Register the payment module together in the builder of the app-wide initialization. Call it only once when the app starts, in the following order.

  1. Check the App ID you created in Create app information.
  2. Run CoreConfig.CreateBuilder with the App ID to create a CoreConfig object.
  3. Run initialization with HiveBootstrap.Initialize. Register AddAuth(), AddToken(), and AddPayments() in builder.
    • During development, connect the payment module to the sandbox server with AddPayments(sandbox: true); in production, connect it to the production server with AddPayments()

The payment feature works based on the logged-in user's session. Therefore, when you register AddPayments(), also register the authentication module AddAuth() and the token module AddToken() in the same Initialize call.

sandbox: true changes only the server that the payment module connects to. The authentication module and token module registered together connect to the production server.

Call parameters

Field name Type Required Description
config CoreConfig Required The CoreConfig object that contains the App ID. Create it with CoreConfig.CreateBuilder.
assemble Builder callback Required The builder callback that registers the feature modules to use. To use the payment feature, include builder.AddAuth(), builder.AddToken(), and builder.AddPayments().

Call example

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Auth;         // AddAuth, AddToken extensions
using Hive.Axyl.Payments;     // AddPayments extension

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth();                   // Account and authentication (IAuthService)
    builder.AddToken();                  // Token issuance (ITokenService)
    builder.AddPayments(sandbox: true);  // Payment (IPaymentsService). Development and test environment. Use AddPayments() for production builds
});

Register the feature modules to use together in the second argument (builder) of Initialize.

AddToken() is needed to issue the actual token using the authorizationCode received as the login result, so always register it together with the authentication module.

Call the registered modules afterward as follows.

  • HiveCore.Resolve<IAuthService>()
  • HiveCore.Resolve<ITokenService>()
  • HiveCore.Resolve<IPaymentsService>()

Response data

No data is returned on success.

Response example

IAuthService auth = HiveCore.Resolve<IAuthService>();
ITokenService token = HiveCore.Resolve<ITokenService>();
IPaymentsService payments = HiveCore.Resolve<IPaymentsService>();

Response status

If calling HiveCore.Resolve<IAuthService>(), HiveCore.Resolve<ITokenService>(), and HiveCore.Resolve<IPaymentsService>() in your code returns instances normally, initialization and module registration are complete.

If initialization fails, exceptions are thrown as follows.

  • Passing null to config throws ArgumentNullException
  • Calling the initialization method again after initialization is already complete throws InvalidOperationException

Unlike a Failure in a method call result, these exceptions make the initial setup fail immediately. For the common principles, including the exception that Resolve<T>() throws when a registration is missing, see Common error handling.

3. Activate the login session

The app user is the one who makes payments. Therefore, the payment feature works only when there is a user login session. Activate the login session first, and then call the payment methods.

4. Generate an AccountUuid

AccountUuid is the reference value used to check whether the user who made the payment and the user who requested receipt verification are the same. Because it must be included in the receipt verification request that the app server sends, decide how to generate it before you implement the payment flow. The server does not generate AccountUuid, so generate a UUIDv5 from the logged-in user's playerId in the app client.

  1. Choose one namespace UUID for the app.
  2. Convert the logged-in user's playerId to a decimal string. For example, if playerId is 1234567890, the name string is "1234567890".
  3. Generate a UUIDv5 from the namespace UUID and the name string.

Within the same app, use the same namespace UUID on all platforms and devices. Always use the same AccountUuid for the same playerId, and do not create a new UUID for each payment. AccountUuid in Hive Axyl SDK payment method requests is optional, but to have the Hive Axyl server match the account of the user who made the payment, pass the value generated with the method above.

Next steps