Install the module, initialize, and log in

To use the mailbox, you must install the mailbox module in the Hive Axyl SDK and initialize it. If you have not installed the Hive Axyl SDK yet, first install the Hive Axyl SDK.

1. Install the mailbox module

Install the mailbox module together with the common module and the authentication module. To keep the login state even after the app restarts, also install the storage module.

1.1. Select common modules

The common module provides the minimum features for using Hive Axyl, so you must select it.

• com.com2usplatform.hiveaxyl.core: SDK initialization and the basic features that other modules share

1.2. Select modules for mailbox features

Mailbox features additionally require the authentication module and the mailbox module. Select the storage module when you implement keeping the login state yourself.

Module	Needed	Description
com.com2usplatform.hiveaxyl.auth	Required	Needed to prepare the login session, such as account creation, login, and token issuance.
com.com2usplatform.hiveaxyl.mailbox	Required	Provides mailbox features based on the logged-in user's session, such as sending mail, getting sent mail, getting received mail, and recalling and deleting mail.
com.com2usplatform.hiveaxyl.storage	Optional	Provides secure storage that encrypts values that must not be exposed, such as login tokens, saves them on the user's device, and loads them again.

The actor that sends, receives, recalls, and deletes mail is the app user. Therefore, the mailbox works only when there is a user login session, and for this, the mailbox and authentication modules are both needed.

The Hive Axyl SDK keeps the login session only in memory while the app is running. So when the app restarts, the user must log in again. To avoid this, the app must save the login token on the device and load it on the next launch, and the storage module provides a safe storage space to use for this. The app writes the code that saves and loads the token itself.

1.3. Install modules

Install the modules the same way as in SDK installation. Because the Hive Axyl SDK is installed only through a Scoped Registry, additionally declare the modules the mailbox needs in the Hive Axyl Scoped Registry you registered when you installed the SDK.

Add com.com2usplatform.hiveaxyl.core together with com.com2usplatform.hiveaxyl.auth for preparing the login session and the mailbox feature module com.com2usplatform.hiveaxyl.mailbox to dependencies in Packages/manifest.json. If you implement keeping the login state, also add com.com2usplatform.hiveaxyl.storage.

manifest.json

{
  "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.storage": "1.0.0",
    "com.com2usplatform.hiveaxyl.mailbox": "1.0.0"
  }
}

1.4. Verify the installation

Use the following code to check that the namespaces of the installed SDK and the authentication and mailbox modules are recognized correctly.

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Auth;
using Hive.Axyl.Mailbox;
using Hive.Axyl.Storage;   // Required only if you installed the storage module

The installation step is complete when the installed modules appear in the Installed state in Unity Package Manager.

2. Initialize the SDK

Initialize

Hive Axyl SDK initialization is a preparation step that the app goes through once before it uses mailbox features. When the app starts, call initialization to load the project identification information and runtime configuration into memory and get ready to use the authentication and mailbox features.

Register the mailbox module together in the builder of the app-wide initialization. Call it only once when the app starts.

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. Initialize with HiveBootstrap.Initialize, and register AddAuth(), AddToken(), and AddMailbox() on builder. If you installed the storage module, also register AddSecureStorage().

Mailbox features work based on the logged-in user's session. Therefore, when you register AddMailbox(), also register AddAuth() and AddToken() of the authentication module in the same Initialize call. Both AddAuth() and AddToken() are provided by the com.com2usplatform.hiveaxyl.auth module, so you do not need to install a separate module. If you installed the storage module, also register AddSecureStorage() in the same call.

Environments where secure storage is available

AddSecureStorage() registers secure storage only in Android, iOS, macOS, and Windows builds. It does not register it when you run in the Unity Editor or in other builds. This is because the secure storage method differs by device, and the Hive Axyl SDK supports only the storage methods of the four operating systems above.

If you call HiveCore.Resolve<ISecureStorage>() in an environment where it is not registered, a RegistrationNotFoundException is thrown, which means the requested feature is not registered. For details, see Common error handling. If you also run the app in the Editor, first check with HiveCore.TryResolve<ISecureStorage>(out var storage), which returns true or false to indicate whether it is registered instead of throwing an exception.

Even if secure storage cannot be used, mailbox methods work as usual. This is because the login session is kept in memory while the app is running. However, because the login state cannot be saved on the device, in that environment the user must log in again every time the app restarts.

Call parameters

Field name	Type	Required	Description
config	CoreConfig	Required	The object that holds the App ID. Create it with CoreConfig.CreateBuilder.
assemble	Builder callback	Required	The builder callback that registers the feature modules to use. To use mailbox features, include builder.AddAuth(), builder.AddToken(), and builder.AddMailbox(). If you installed the storage module, also include builder.AddSecureStorage().

Call example

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Auth;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Storage;      // AddSecureStorage extension
using Hive.Axyl.Mailbox;      // AddMailbox extension

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

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth();            // Account and authentication (IAuthService)
    builder.AddToken();           // Token issuance (ITokenService)
    builder.AddMailbox();         // Mailbox (IMailboxService)
    builder.AddSecureStorage();   // Secure storage (ISecureStorage). Register only when you implement keeping the login state
});

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

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

After that, call and use the registered modules as follows.

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

Because there are environments where secure storage is not registered, get it with HiveCore.TryResolve<ISecureStorage>(out var storage) instead of HiveCore.Resolve<ISecureStorage>(). If it returns true, storage holds the secure storage.

Response data

No data is returned on success.

Response example

Unity

IAuthService auth = HiveCore.Resolve<IAuthService>();
ITokenService token = HiveCore.Resolve<ITokenService>();
IMailboxService mailbox = HiveCore.Resolve<IMailboxService>();

Response status

Check whether initialization and module registration are complete with the result of the HiveCore.Resolve<T>() calls. If HiveCore.Resolve<IAuthService>(), HiveCore.Resolve<ITokenService>(), and HiveCore.Resolve<IMailboxService>() all return an instance, they are complete. If you registered secure storage, check whether HiveCore.TryResolve<ISecureStorage>(out var storage) returns true. If the app is not running in one of the environments where secure storage is available, it returns false.

If initialization fails, the following exceptions are thrown.

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

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

Windows build prerequisites

In Windows builds, the SDK also loads the OS-specific binaries (native plugins) that it calls from C# code. If these files cannot be loaded, a DllNotFoundException is thrown during initialization. There are two causes.

• When the native plugin files are not included in the build output
• When Microsoft Visual C++ 2015-2022 Redistributable (x64) is not installed on the PC that runs the app. This package is a set of Microsoft runtime libraries that the native plugins need to run. Windows does not include it by default, and Unity does not add it to the build output.

Therefore, when you release on Windows, include this redistributable package in your app installer, or guide users to install it on first launch. The download link is also included in the exception message.

3. Activate the login session

The mailbox works only when there is a user login session. This is because the actor that sends, receives, recalls, and deletes mail is the app user. Activate the login session first, and then call the mailbox methods.

Next steps

• Send mail

Learn more

• Mailbox usage examples