Skip to content

Conventions

Describes the page structure of the Hive Axyl SDK reference, the notation rules, and the calling conventions that apply to all modules in common.

Page structure

The reference consists of the following three types of pages.

  • Runtime reference: Initialization, configuration, session, call context, and the result and error models of the Core module, which apply to all modules in common
  • Module overview: Package, supported platforms, registration method, list of interfaces that the module provides, and entry classes that app code uses directly
  • Interface reference: Methods that the interface provides, the parameters and result cases of each method, request and response data types, and enums

Interface reference pages are organized in the following order.

  1. Registration and retrieval: Code that registers the module and retrieves the interface
  2. Method summary: Full list of methods and the purpose of each method
  3. Methods: Signature, parameters, and result cases of each method
  4. Data types: Types used in request and response bodies
  5. Enums: Enum values used in fields

Notation rules

Type notation

Types are written as the C# types that app code actually uses. Fields are also written with their C# property names.

If you need the JSON field names exchanged with the server, derive them by changing the first letter of the C# property name to lowercase. For example, PlayerId becomes playerId, and CodeChallengeMethod becomes codeChallengeMethod. Because app code does not handle JSON directly, you need this conversion only when you check server logs or align conventions with the app server.

For enums, the C# member name and the wire value differ. Enter the C# member name in app code. Each enum table lists both values.

// The C# member name is Guest; the value serialized and sent to the server is GUEST.
ProviderId = Provider.Guest

Required or optional

The 'Required' column in field tables uses the following two values.

  • Required: For a request field, you must specify a value. For a response field, a value is always present.
  • Optional: For a request field, you can omit it. For a response field, a value may be absent, so check whether it is null.

Authentication requirement

The 'Authentication' column in the method summary table indicates whether a login session is needed at the time of the call.

  • Not required: A method that you can call without a session, so you can use it even before login
  • Session required: A method that you can call only after you log in and register a session
  • Access token required: A method that authenticates with the access token sent through ApiCallContext.WithAccessToken() instead of the current session

Result model

Hive Axyl SDK methods return call failures as result objects, not as exceptions. Result branches and how to branch on them are described in Core result model, and the exceptions thrown for problems that require fixing app code are described in Exceptions.

Common Failure codes

The following three are the common Failure codes that IAuthService and ITokenService return. The server responds with a code, but because it is not a feature-level result, it branches to Failure, not Outcome, and the cause code is contained in Failure.Problem.ExternalCode. The list of common Failure codes differs by module, so for the lists of other modules, see Common Failure codes by module.

  • invalid_parameter: When a request parameter does not match the format
  • missing_field: When a required field or required header itself is missing, such as when the X-App-Id header is not sent
  • missing_app_id: When the X-App-Id header is sent but its value is empty

All three codes are resolved only by fixing how the app code makes the call. They are not cases in which you should prompt the user to retry.

Call context

Methods that call the Hive Axyl server take ApiCallContext? as the last parameter. Add-on methods that wrap native features take CancellationToken instead. You can omit both, and if you omit them, the default values apply.

The values you can specify and usage examples are described in Core call context.

Notes on using Add-ons

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

If you request an unregistered type with Resolve<T>(), RegistrationNotFoundException is thrown.