IAnalyticsService

A service that turns events that occur in the app client into logs and sends them to the Hive Axyl analytics log server. It creates a log event by adding attributes defined by the app to the event name and event time, and sends multiple events in a single request. The server collects log events without interpreting their contents.

Interface: IAnalyticsService
Namespace: Hive.Axyl.Analytics
Package: com.com2usplatform.hiveaxyl.analytics

Registration and retrieval

Unity

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

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

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAnalytics();
});

IAnalyticsService analytics = HiveCore.Resolve<IAnalyticsService>();

Method summary

For the meaning of the 'Authentication' column, see Authentication requirement notation.

Method	Authentication	Description
CollectClientLogAsync	Not required	Sends a list of log events to the Hive Axyl analytics log server.

Common parameters

The last parameter of every method is ApiCallContext? context = null. If you omit it, the default values apply. For details, see Call context.

Every method takes the request body as the request parameter, and request is Required. The method descriptions below show only the request type and omit the parameter table. Check the fields of each request type in Data types.

Exceptions

ArgumentNullException: When request is null

Common Failure codes

The server responds with the following codes, but they are not feature-level results, so they branch to Failure, not Outcome. The cause code is contained in Failure.Problem.ExternalCode. For result branches and how to branch, see Core result model.

bad_request: Bad request
invalid_parameter: Request parameter format error
missing_field: A required field or a required header such as X-App-Id is missing entirely
missing_app_id: The X-App-Id header was sent, but its value is empty
unauthorized: The authentication token is missing or invalid
token_expired: The authentication token has expired
forbidden: No permission for the request
resource_not_found: The requested resource does not exist
method_not_allowed: Request method not allowed
resource_conflict: Conflict between the request and the resource state
unprocessable_content: Request content that cannot be processed
rate_limit_exceeded: Request rate over the allowed limit
internal_error: Internal server error
service_unavailable: Service temporarily unavailable

Methods

CollectClientLogAsync

Sends a list of log events to the Hive Axyl analytics log server. When the server collects the logs, it returns Success, and there is no response data. The SDK automatically passes the App ID with every request, so do not put it in the request.

You can call this method both before and after login. Before login, the SDK sends the request without an authentication token. After a login session is activated, the SDK automatically includes the session's authentication token in the request, and the server identifies the user with this token.

Unity

Task<AnalyticsCollectClientLogResult> CollectClientLogAsync(ClientLogCollectRequest request, ApiCallContext? context = null);

Request: ClientLogCollectRequest
Response: None
Authentication: Not required

Result cases — AnalyticsCollectClientLogResult

Result case	Wire code	Description
`Success`	—	The server collected the logs.
`UnknownOutcome`	`UNKNOWN`	A new result that this SDK version does not recognize.
`Failure`	`FAILURE`	The call could not be completed. Common Failure codes also branch to this case.

Call example

Unity

using System;
using System.Collections.Generic;
using Hive.Axyl.Analytics;
using Hive.Axyl.Core;

var result = await analytics.CollectClientLogAsync(new ClientLogCollectRequest
{
    LogBody = new[]
    {
        new ClientLogEvent
        {
            EventTime = DateTimeOffset.Now,
            EventName = "levelup_log",
            DeviceId  = deviceKey,   // Same value as the DeviceKey used for login
            AdditionalProperties = new Dictionary<string, string>
            {
                ["level"]        = "12",              // Number
                ["stage"]        = "\"boss_room\"",   // For strings, include the double quotes.
                ["isFirstClear"] = "true",            // Boolean
            },
        },
    },
});

if (result is AnalyticsCollectClientLogResult.Failure failure)
{
    HiveError error = failure.Problem;
}

For the implementation procedure, see Send event logs.

Data types

ClientLogCollectRequest

Log event sending request.

Field	Type	Required	Description
`LogBody`	IReadOnlyList<ClientLogEvent>	Required	List of log events to send. The default value is an empty list, and the request is sent as is even if it is empty.

ClientLogEvent

A single log event. For attributes that are not in the table below, the app decides their names and adds as many as it needs to AdditionalProperties.

Field	Type	Required	Description
`EventTime`	`DateTimeOffset`	Required	Time when the event occurred. It is sent in RFC 3339 format, including the time offset. If not specified, the default value of `DateTimeOffset` is sent, so always specify it.
`EventName`	`string`	Required	Event name. Example: `levelup_log`
`DeviceId`	`string?`	Optional	Device identifier. Specify exactly the same value as the `DeviceKey` that the app puts in login requests. The SDK does not fill in this value automatically. For how to prepare the value, see DeviceId.
`UserId`	`string?`	Optional	User identifier.
`IdentifierProvider`	ClientLogEventIdentifierProvider?	Optional	Identifier provider. The server always overwrites it with `hive`, so do not specify it.
`AdditionalProperties`	`IDictionary<string, string>`	Optional	Event attributes whose names the app defines. Keys are attribute names, and values are strings that represent JSON values. Each attribute is sent as a field at the same level as `eventName`. The default value is an empty dictionary, and if it is empty, no attributes are sent. For the rules, see Rules for writing AdditionalProperties.

Rules for writing AdditionalProperties

In the values of AdditionalProperties, put the JSON value itself as a string, not text to display on screen. The SDK writes the values to the request body as is without validating them, so if a value is not a valid JSON value, the entire request body becomes invalid JSON. If a value is null, it is sent as JSON null.

Value type	Value in C# code	JSON sent
Number	`"42"`	`42`
String	`"\"gold\""`	`"gold"`
Boolean	`"true"`	`true`
Array	`"[1,2]"`	`[1,2]`
Object	`"{\"a\":1}"`	`{"a":1}`
JSON null	`"null"`	`null`

eventTime, eventName, deviceId, userId, and identifierProvider are the names used when the declared fields are sent, so do not use them as attribute names. If you use the same name, a field with the same name can be sent twice in one log event.

Enums

Enter the C# member name in app code. The wire value is the string exchanged with the server.

ClientLogEventIdentifierProvider

Identifier provider of a log event. You specify it in ClientLogEvent.IdentifierProvider, but the server always overwrites it with hive.

C# member	Wire value	Description
`Unspecified`	`CLIENT_LOG_EVENT_IDENTIFIER_PROVIDER_UNSPECIFIED`	Default value when no value is specified.
`Hive`	`hive`	Hive identifier provider.