Client update

Use the client update check method to check whether the current app version needs an update.

1. Configure client update in the Hive Console

To use client update, first register an update item in the console. In Hive Console > Service Access Control > Service Access Control, select a project, click Search, and then in New access control item, set the type to Client Update. For the input fields on the registration screen, see Service access control items. Before you register, prepare the App ID and the app's supported languages. For how to prepare them, see App ID and App meta info.

2. Prepare the call parameter values

Before the call, prepare ClientVersion, which determines whether an update is needed, and PlayerId, which is used to check whether the allowlist applies.

ClientVersion

ClientVersion is the version of the currently running app client. The server compares this value with the target versions registered in the console to determine whether an update is needed.

The server does not interpret version ranges or notation differences; it only compares whether the strings are exactly the same. For example, 1.2 and 1.2.0 are treated as different versions. Pass the version exactly as it is written in the console. You cannot pass an empty string or a value that contains whitespace characters.

PlayerId

PlayerId is the Player ID used to check whether the user is registered in the Allowlist. The server applies the allowlist automatically when it processes the request, so the app does not need to retrieve the allowlist separately. If the access IP or PlayerId is on the allowlist, Data.UpdateRequired is false even if an update item is in effect. For client update, if an allowlist item specifies an app version, the item applies only when the request's ClientVersion is the same as that version. If no allowlist item matches, PlayerId does not affect the result.

Because there is no Player ID before login, omit it then, and specify it when you check again after you log in. Check the logged-in user's Player ID with PlayerId of ISessionManager.

3. Call the client update check method

CheckClientUpdateAsync

Call CheckClientUpdateAsync() to check whether the current app version is a target of a client update item in effect. If an update is needed, the method also returns whether the update is forced and the store notice URL. According to this result, the app handles a forced or optional update and, if needed, implements going to the store.

You can call it even before login. However, considering the possibility of fraudulent use, we recommend calling it with PlayerId after login.

Call parameters

Field name	Type	Required	Description
request	CheckClientUpdateRequest	Required	Client update retrieval request
context	ApiCallContext	Optional	Per-call settings object. If omitted, the default values are used.

The SDK automatically sends the App ID and the notice message language that you set in Install and initialize the module, so you do not include them in the request.

CheckClientUpdateRequest

Field name	Type	Required	Description
`ClientVersion`	string	Required	Current app client version. You cannot specify an empty string or a value that contains whitespace characters.
`PlayerId`	long?	Optional	Player ID used to check whether the allowlist applies. Omit it before login.

Call example

The CheckClientUpdateAsync() call example handles Success, Failure, and UnknownOutcome separately. For the result model and handling principles of common failures (Failure), see Common error handling.

Unity

using Hive.Axyl.ServiceAccess;
using Hive.Axyl.Core;

IServiceAccessService service = HiveCore.Resolve<IServiceAccessService>();

var request = new CheckClientUpdateRequest {
    ClientVersion = Application.version,  // Current app version
    // PlayerId   = HiveCore.Resolve<ISessionManager>().PlayerId,  // Specify when calling after login
};

ServiceAccessCheckClientUpdateResult result = await service.CheckClientUpdateAsync(request);

switch (result)
{
    case ServiceAccessCheckClientUpdateResult.Success success:
        if (success.Data.UpdateRequired)
        {
            // Update needed. Forced if ForceUpdate; otherwise, encourage an optional update. Go to the store with RedirectUrl
            Debug.Log($"Update required (force={success.Data.ForceUpdate}): {success.Data.RedirectUrl}");
        }
        else
        {
            // No update needed -> proceed normally
        }
        break;

    // Handle common failures (network and server errors, request value errors)
    case ServiceAccessCheckClientUpdateResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}/{err.ExternalCode}] {err.Message} (trace: {err.TraceId})");
        break;

    // Treat results not defined in this SDK version and internal server errors (UnknownOutcome) as failures.
    default:
        Debug.LogWarning($"Unhandled result: {result.GetType().Name}");
        break;
}

Response data

On success, the result is contained in Data (CheckClientUpdateResponseData) of ServiceAccessCheckClientUpdateResult.Success. If Data.UpdateRequired is true, the method also returns the title, body, redirect URL, and list of target versions needed for the update notice. If multiple update items apply to the current version, the notice message and the list of target versions of the most recently registered item are returned.

Field name	Type	Required	Description
`Data.UpdateRequired`	bool	Required	Whether an update is needed
`Data.Id`	long?	Optional	ID of the applied client update item. `null` if no update is needed
`Data.ForceUpdate`	bool	Required	Whether the update is forced. `false` means an optional update; it is also `false` if no update is needed
`Data.Title`	string	Required	Update notice title. Empty string if no update is needed
`Data.Content`	string	Required	Update notice body. Empty string if no update is needed
`Data.RedirectUrl`	string	Required	Update notice URL, such as a store URL. Empty string if not set in the console or if no update is needed
`Data.Versions`	`IReadOnlyList<ClientUpdateVersion>`	Required	List of target update versions specified for the requested App ID in the applied item. Empty list if no update is needed. For the item structure, see `ClientUpdateVersion` below
`Data.AlwaysOn`	bool	Required	Whether the item always applies
`Data.StartAt`·`Data.EndAt`	DateTimeOffset?	Optional	Effective period of the update notice. Both are `null` if no update is needed; `StartAt` is `null` for an item with no start time specified, and `EndAt` is `null` for an always-on item with no end time
`Data.Timezone`	`TimeZoneInfoNullable`	Optional	Reference time zone for interpreting `StartAt` and `EndAt`. `null` if no update is needed. For the item structure, see `TimeZoneInfoNullable` below

ClientUpdateVersion

Field name	Type	Required	Description
`AppId`	string	Required	Update target App ID
`ClientVersion`	string	Required	Update target client version

TimeZoneInfoNullable

Data.Timezone is the time zone information for interpreting Data.StartAt and Data.EndAt. The server determines the time zone based on the country identified from the access IP, so the app does not need to send time zone information separately. If the country cannot be identified, UTC is used. If there is no item to apply because no update is needed, Data.Timezone is null.

The UTC offsets of StartAt and EndAt are the values that apply in this time zone at each of those times. Therefore, if a daylight saving time transition occurs between the two times, the two offsets differ. UtcOffset, OffsetSeconds, and Dst are calculated based on StartAt; if StartAt is null, they are calculated based on EndAt, and if both are null, based on the current time.

Field name	Type	Required	Description
`Id`	string	Required	IANA time zone identifier. Example: `Asia/Seoul`
`UtcOffset`	string	Required	UTC offset in `±HH:MM` format. Reflects daylight saving time; `+00:00` if the offset is 0
`OffsetSeconds`	int	Required	UTC offset in seconds
`Dst`	bool	Required	Whether daylight saving time applies
`IsInEuropeanUnion`	bool	Required	Whether the country used to determine the time zone belongs to the European Union. `false` if UTC is used
`Name`	string	Optional	Country name in the request language. If there is no name for the request language tag, the name found in this order: the tag with only the language part, English, and the other available languages. For example, if the request language is `pt-BR`, the order is `pt-BR`, `pt`, `en`. `null` if there is no country name or UTC is used
`Names`	`IReadOnlyDictionary<string, string>`	Required	Country names by language tag. Empty if UTC is used

Warning

If Data.UpdateRequired is false, the notice title, body, and redirect URL are all empty strings, and the list of target versions is also empty. Check Data.UpdateRequired first before you show a notice screen. The app client must implement the actual update prompting and entry restriction itself.

Response headers

On success, the response header values are contained in Headers (CheckClientUpdateResponseHeaders) of ServiceAccessCheckClientUpdateResult.Success.

Field name	Type	Required	Description
`Headers.XTraceId`	string	Optional	Request trace identifier that the server issues for each response. Use it when you make an inquiry about a problem or look up logs.

Response example