Core module

The runtime that every Hive Axyl SDK module depends on. It provides SDK initialization, registration and retrieval of the modules you use, session storage, call policies, and the result and error models. When you install any other module, Core is installed with it, so you do not need to add it separately.

Module information

Package: com.com2usplatform.hiveaxyl.core
Namespaces: Hive.Axyl.Core, Hive.Axyl.Core.Unity
Supported platforms: All
Minimum requirements: Unity 6000.0+

Windows build requirements

com.com2usplatform.hiveaxyl.core includes a native plugin. On Windows, the Microsoft Visual C++ 2015-2022 Redistributable (x64) must be installed; otherwise, DllNotFoundException is thrown during initialization. This applies to the Windows Editor as well as to built players.

Reference structure

The Core module reference is divided into the following pages.

This page: HiveBootstrap, HiveCore, IHiveBuilder
Configuration: CoreConfig, CoreConfigBuilder, configuration options and default values, and log-related types
Session: ISessionManager, SessionSnapshot
Call context: ApiCallContext, RequestOptions, CallCredential
Result model: IAxylResult and the marker interfaces used for result branching
Errors: HiveError, HiveErrorCode, RegistrationNotFoundException

Initialization flow

Initialization has three steps: create the configuration, register the modules to use, and retrieve the interfaces.

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap

void Start()
{
    // 1. Create the configuration.
    var config = CoreConfig.CreateBuilder("{appId}").Build();

    // 2. Initialize while registering the modules to use.
    HiveBootstrap.Initialize(config, builder =>
    {
        builder.AddAuth()
               .AddToken();
    });

    // 3. Retrieve the registered interface.
    IAuthService auth = HiveCore.Resolve<IAuthService>();
}

Threading model

All events the SDK raises are invoked on the engine main thread, so you can use engine APIs inside event handlers. Asynchronous methods, however, are not. The returned task can complete on any thread, so if you use engine APIs after await, the app code must switch to the main thread itself.

HiveBootstrap

class — namespace Hive.Axyl.Core.Unity

The entry class that connects the Unity application lifecycle to HiveCore. It creates a hidden GameObject that persists across scene changes and forwards pause, resume, and quit events to HiveCore.

App code only needs to call Initialize once on the main thread. This class handles the adapter configuration for Unity on the app's behalf.

Initialize

Initializes the SDK. Call it exactly once before you use any other SDK API.

Unity

static void Initialize(CoreConfig config)
static void Initialize(CoreConfig config, Action<IHiveBuilder> assemble)

Parameter	Type	Required	Description
`config`	`CoreConfig`	Required	The configuration created with CoreConfig.CreateBuilder().
`assemble`	`Action<IHiveBuilder>`	Required	The closure that registers the modules to use. Used only in the second overload.

The first overload initializes only the runtime without registering any modules. If you use even one module, use the second overload.

Exceptions

ArgumentNullException: When config is null
InvalidOperationException: When the SDK is already initialized. Call HiveCore.Shutdown() first.
DllNotFoundException: When the native plugin cannot be loaded on Windows. This occurs when the plugin is not included in the build or the Microsoft Visual C++ 2015-2022 Redistributable (x64) is not on the device, and the exception message contains an installation link.

For the installation procedure and initialization options, see Initialize the SDK.

HiveCore

static class — namespace Hive.Axyl.Core

The static entry point of the SDK runtime. It handles retrieving registered services, setting the language, shutdown, and lifecycle transitions.

In Unity, HiveBootstrap.Initialize performs initialization for you, so what app code mainly uses directly from HiveCore is Resolve<T>().

Method summary

Resolve<T>(): Gets a registered service; throws an exception if it is not registered
TryResolve<T>(): Gets a registered service; returns false if it is not registered
SetLanguage(): Sets the language to send with subsequent requests
AddLogSink(): Adds a log sink at runtime
Suspend(): Notifies the SDK that the app moved to the background
Resume(): Notifies the SDK that the app returned to the foreground
Shutdown(): Shuts down the SDK and releases resources

In Unity, HiveBootstrap calls Suspend, Resume, and Shutdown automatically according to lifecycle events.

Methods

Resolve

Gets a registered service. Use it when the module must be registered.

Unity

static T Resolve<T>() where T : class

Returns: T, the registered service instance

Exceptions

InvalidOperationException: When the SDK is not initialized
RegistrationNotFoundException: When no service is registered with type T

TryResolve

Gets a registered service without throwing an exception. Returns false if the SDK is not initialized or the service is not registered.

Add-ons are registered only on supported platforms. They are not registered in the Unity Editor or on unsupported platforms, so for Add-ons, check with this method instead of Resolve<T>() before you use them.

Unity

static bool TryResolve<T>(out T? service) where T : class

Parameter	Type	Required	Description
`service`	`out T?`	Required	Holds the registered service when the method returns `true`. Otherwise, it is `null`.

Returns: bool, true if the service was retrieved

Call example

Unity

if (HiveCore.TryResolve<IAppleSignInPlugin>(out var apple))
{
    // Code that runs only on supported platforms
}

SetLanguage

Sets the language to send in the Accept-Language header of subsequent requests. It applies from the next request without reinitialization and does not affect requests that are already being sent.

Use it when the app has its own language setting separate from the OS language. If you do not call it, the OS language read at initialization is used.

It is safe to call from any thread.

Unity

static void SetLanguage(string? language)

Parameter	Type	Required	Description
`language`	`string?`	Required	A BCP 47 language tag. Example: `ja-JP`. If you specify `null`, the language reverts to the OS language read at initialization.

Exceptions

ArgumentException: When language is an empty string, whitespace, or not in BCP 47 format
InvalidOperationException: When the SDK is not initialized

AddLogSink

Adds a log sink at runtime. Use it when the app wants to send SDK logs to its own log collection tool.

Logs are delivered after PII masking and the minimum level filter. For details, see Connect log collection.

Unity

static void AddLogSink(ILogSink sink)

Parameter	Type	Required	Description
`sink`	ILogSink	Required	The sink to register. You cannot specify `null`.

Exceptions

ArgumentNullException: When sink is null
InvalidOperationException: When the SDK is not initialized

Suspend

Notifies the SDK that the app moved to the background. If the SDK is not initialized, it does nothing.

In Unity, HiveBootstrap calls it automatically, so app code does not need to call it directly.

Unity

static void Suspend()

Resume

Notifies the SDK that the app returned to the foreground. If the SDK is not initialized, it does nothing.

In Unity, HiveBootstrap calls it automatically, so app code does not need to call it directly.

Unity

static void Resume()

Shutdown

Shuts down the SDK and releases resources in the reverse order of initialization. It is safe to call multiple times; from the second call on, it does nothing.

Shutdown does not raise OnSessionExpired. It makes no judgment about the validity of the saved credentials, so event subscribers must not mistake a normal app shutdown for a logout. Saved credentials can be restored as is on the next launch.

Unity

static void Shutdown()

Properties

IsInitialized

Whether the SDK is initialized. It becomes true after Initialize succeeds and is false after Shutdown or before initialization.

Unity

static bool IsInitialized { get; }

IHiveBuilder

interface — namespace Hive.Axyl.Core

The type that the registration closure of HiveBootstrap.Initialize receives as a parameter. Register the modules to use with the extension methods that each module package provides. Registration methods return the builder itself, so you can chain calls.

Registration is finalized when the closure ends, and you cannot add modules after that. Register all the modules you use in this single initialization call.

Module registration methods

Module	Registration method	Package
`auth`	`AddAuth()`, `AddToken()`	`com.com2usplatform.hiveaxyl.auth`
`auth.addon.apple`	`AddAppleSignIn()`	`com.com2usplatform.hiveaxyl.auth.addon.apple`
`auth.addon.credentialmanager`	`AddCredentialManager()`	`com.com2usplatform.hiveaxyl.auth.addon.credentialmanager`
`auth.addon.gpg`	`AddGooglePlayGames()`	`com.com2usplatform.hiveaxyl.auth.addon.gpg`
`auth.addon.steam`	`AddSteamAuth()`	`com.com2usplatform.hiveaxyl.auth.addon.steam`
`auth.addon.webauth`	`AddWebAuth()`	`com.com2usplatform.hiveaxyl.auth.addon.webauth`
`payments`	`AddPayments()`	`com.com2usplatform.hiveaxyl.payments`
`payments.addon.apple`	`AddStoreKit()`	`com.com2usplatform.hiveaxyl.payments.addon.apple`
`payments.addon.google`	`AddPlayBilling()`	`com.com2usplatform.hiveaxyl.payments.addon.google`
`payments.addon.steam`	`AddSteamMicrotransactions()`	`com.com2usplatform.hiveaxyl.payments.addon.steam`
`push`	`AddPush()`	`com.com2usplatform.hiveaxyl.push`
`push.addon.apns`	`AddAPNS()`	`com.com2usplatform.hiveaxyl.push.addon.apns`
`push.addon.applenotification`	`AddAppleNotification()`	`com.com2usplatform.hiveaxyl.push.addon.applenotification`
`push.addon.fcm`	`AddFCM()`	`com.com2usplatform.hiveaxyl.push.addon.fcm`
`mailbox`	`AddMailbox()`	`com.com2usplatform.hiveaxyl.mailbox`
`serviceaccess`	`AddServiceAccess()`	`com.com2usplatform.hiveaxyl.serviceaccess`
`storage`	`AddSecureStorage()`	`com.com2usplatform.hiveaxyl.storage`
`coupon`	`AddCoupon()`	`com.com2usplatform.hiveaxyl.coupon`
`analytics`	`AddAnalytics()`	`com.com2usplatform.hiveaxyl.analytics`
`tcb`	`AddTcb()`	`com.com2usplatform.hiveaxyl.tcb`

Target server

The server that a server API module connects to is decided when the app registers the module. To specify the server URL yourself, use the AddXxx(string baseUrl) overload. If you call a registration method without arguments, each module connects to the following production server.

https://core-api.hiveaxyl.com: AddAuth(), AddToken(), AddServiceAccess()
https://commerce-api.hiveaxyl.com: AddPayments(), AddCoupon()
https://app-api.hiveaxyl.com: AddMailbox(), AddPush(), AddTcb()
https://data-api.hiveaxyl.com: AddAnalytics()

The only overload that connects to the sandbox server is the payment module's AddPayments(sandbox: true), and this overload changes only the payment module's target server. For how to use it, see Registration and retrieval in the Payments module.