Skip to content

IServiceAccessService

This service retrieves, from the Hive Axyl server, the information needed to restrict access to the app or display notice screens. It provides retrieval of server maintenance in effect, checks of whether a client update is needed, and checks of whether service country restriction applies. The server only returns the items and notice messages registered in the console; it does not block access itself. The app implements access restriction, notice screen display, and going to the store according to the results.

  • Interface: IServiceAccessService
  • Namespace: Hive.Axyl.ServiceAccess
  • Package: com.com2usplatform.hiveaxyl.serviceaccess

Registration and retrieval

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

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

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

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

Method summary

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

Method Authentication Description
GetActiveMaintenancesAsync Not required Gets the list of server maintenance items currently in effect.
CheckClientUpdateAsync Not required Checks whether the app client version needs an update.
CheckCountryBlockAsync Not required Checks whether a country code is subject to service country restriction.

No method sends the authentication token of the login session. Therefore, you can call them even before login, and no authentication error occurs even if the session expires.

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 query conditions 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.

Automatically sent values

With every request, the SDK automatically sends the App ID used for initialization in the X-App-Id header and the request language in the Accept-Language header. Therefore, the request types have no fields for these two values. The request language is the device language at the time of initialization, and you change it with SetLanguage().

The notice messages Title and Content are returned in the request language. If the console has no message in that language, the message registered in the default language is returned; if there is no message in the default language either, an empty string is returned.

Exceptions

Common Failure codes

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

  • invalid_parameter: Invalid request parameter format
  • missing_field: Missing required parameter or required header

An internal error that the server responds to with the internal_error code branches to UnknownOutcome, not Failure, and the code is contained in UnknownOutcome.Code. Handle UnknownOutcome as a failure as well.

Methods

GetActiveMaintenancesAsync

Gets the list of server maintenance items in effect at the current time. Data.Items is sorted starting from the most recently registered item, and it is an empty list if no maintenance is in effect. If the access IP or PlayerId is in the Allowlist, an empty list is returned even if maintenance is in effect.

The maintenance returned depends on ServerCode and ClientVersion in the request. Maintenance that specifies neither target servers nor target versions is returned regardless of the values of these two fields. ClientVersion also determines whether allowlist items that specify an app version apply.

Request field When specified When not specified
ServerCode Returns maintenance that targets this server and maintenance that does not specify target servers. Returns maintenance regardless of target servers.
ClientVersion Returns maintenance that does not specify target versions, and maintenance that targets the requested App ID and this version. Versions are compared only for an exact string match, without interpreting ranges or notation differences. Allowlist items that specify an app version apply only when that version is the same as this version. Maintenance that specifies target versions is not returned. Only allowlist items that do not specify an app version apply. 
Task<ServiceAccessGetActiveMaintenancesResult> GetActiveMaintenancesAsync(GetActiveMaintenancesRequest request, ApiCallContext? context = null);

Result cases — ServiceAccessGetActiveMaintenancesResult

Result case Wire code Description
Success — The retrieval succeeded. The maintenance list is contained in Data.Items, and the response header values are contained in Headers.
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.

For the implementation procedure, see Server maintenance.

CheckClientUpdateAsync

Checks whether the ClientVersion in the request needs an update. Versions are compared only for an exact string match, without interpreting ranges or notation differences. If a client update item in effect targets the requested App ID and this version, Data.UpdateRequired is true, and whether the update is forced and the notice messages are returned with it. If multiple items match, the most recently registered item is returned. If no item applies, Data.UpdateRequired is false.

If the access IP or PlayerId is in the Allowlist, a result indicating that no update is needed is returned regardless of the items in effect. Allowlist items that specify an app version apply only when that version is the same as the ClientVersion in the request.

Task<ServiceAccessCheckClientUpdateResult> CheckClientUpdateAsync(CheckClientUpdateRequest request, ApiCallContext? context = null);

Result cases — ServiceAccessCheckClientUpdateResult

Result case Wire code Description
Success — The check succeeded. Whether an update is needed is contained in Data.UpdateRequired, and the response header values are contained in Headers.
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.

For the implementation procedure, see Client update.

CheckCountryBlockAsync

Checks whether the CountryCode in the request is subject to service country restriction. Country codes are compared case-insensitively. If a service country restriction item that blocks this country for the requested App ID is in effect, Data.Blocked is true, and the notice messages and the list of blocked countries for this App ID are returned with it. If multiple items match, the most recently registered item is returned. If no item applies, Data.Blocked is false.

If the access IP or PlayerId is in the Allowlist, a not-blocked result is returned regardless of the items in effect. Even if an allowlist item specifies an app version, the item applies regardless of the version.

Task<ServiceAccessCheckCountryBlockResult> CheckCountryBlockAsync(CheckCountryBlockRequest request, ApiCallContext? context = null);

Result cases — ServiceAccessCheckCountryBlockResult

Result case Wire code Description
Success — The check succeeded. Whether the country is blocked is contained in Data.Blocked, and the response header values are contained in Headers.
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.

For the implementation procedure, see Service country restriction.

Data types

Fields shared by multiple types have the same meaning.

  • PlayerId: The Player ID used to determine whether the allowlist applies
  • Id: The ID of the service access control item registered in the console
  • StartAt: The effective start time of the item, expressed in the Timezone time zone of the same object. null for an item with no start time
  • EndAt: The effective end time of the item, expressed in the Timezone time zone of the same object. null if there is no end time, as with always-on items
  • AlwaysOn: Whether the item is registered in the console as an always-on item
  • Title: The notice title in the request language to display to the user. For how the language is selected, see Automatically sent values
  • Content: The notice body in the same language as Title
  • RedirectUrl: The URL or deep link that sends the user to a detailed notice page or the store. An empty string if it is not registered in the console
  • Timezone: The time zone information for StartAt and EndAt. For the fields, see TimeZoneInfo
  • Meta: Additional response information. null in service access control responses

Before login, there is no Player ID, so omit PlayerId, and specify it when you check again after login. Check the Player ID of the logged-in user with PlayerId of ISessionManager. If you specify a Player ID that has no matching item in the allowlist, the result does not change.

CheckClientUpdateRequest

A client update check request.

Field Type Required Description
ClientVersion string Required The app client version to check. Specify it in the same format as the version registered in the console. You cannot specify an empty string or a value that contains whitespace characters. Example: 1.2.0
PlayerId long? Optional The Player ID used to determine whether the allowlist applies.

CheckClientUpdateResponseData

The client update check result. If UpdateRequired is false, either no item applies or the allowlist applies, and the other fields contain the following values.

  • ForceUpdate, AlwaysOn: false
  • Title, Content, RedirectUrl: Empty string
  • Versions: Empty list
  • Id, StartAt, EndAt, Timezone: null

Check UpdateRequired first, and then use the other fields.

Field Type Required Description
Id long? Optional The ID of the applied client update item.
UpdateRequired bool Required true if an update is needed.
ForceUpdate bool Required true for a forced update, and false for an optional update. It follows the force update setting in the console.
StartAt DateTimeOffset? Optional The effective start time.
EndAt DateTimeOffset? Optional The effective end time.
AlwaysOn bool Required Whether the item is an always-on item.
Title string Required The update notice title.
Content string Required The update notice body.
RedirectUrl string Required The update notice destination, such as the store.
Timezone TimeZoneInfoNullable? Optional The time zone information for StartAt and EndAt. null if no item applies.
Versions IReadOnlyList<ClientUpdateVersion> Required Of the target versions specified in the applied item, the list of versions for the requested App ID.
Meta ResponseMeta? Optional Additional response information.

CheckCountryBlockRequest

A service country restriction check request.

Field Type Required Description
CountryCode string Required The ISO 3166-1 alpha-2 country code of the country to check. Specify two English letters; the value is not case-sensitive. Example: KR
PlayerId long? Optional The Player ID used to determine whether the allowlist applies.

CheckCountryBlockResponseData

The service country restriction check result. If Blocked is false, either no item applies or the allowlist applies, and the other fields contain the following values.

  • AlwaysOn: false
  • Title, Content, RedirectUrl: Empty string
  • Countries: Empty list
  • Id, StartAt, EndAt, Timezone: null

Check Blocked first, and then use the other fields.

Field Type Required Description
Id long? Optional The ID of the applied service country restriction item. null if the country is not blocked.
Blocked bool Required true if the requested country is blocked.
StartAt DateTimeOffset? Optional The block start time.
EndAt DateTimeOffset? Optional The block end time.
AlwaysOn bool Required Whether the item is an always-on item.
Title string Required The block notice title.
Content string Required The block notice body.
RedirectUrl string Required The block notice destination.
Timezone TimeZoneInfoNullable? Optional The time zone information for StartAt and EndAt. It is determined based on the country identified from the access IP, not the CountryCode in the request. null if the country is not blocked.
Countries IReadOnlyList<CountryBlockCountry> Required Of the blocked countries specified in the applied item, the list of blocked countries for the requested App ID.
Meta ResponseMeta? Optional Additional response information.

ClientUpdateVersion

A target version specified in a client update item. It holds an App ID and a version as a pair.

Field Type Required Description
AppId string Required The target App ID.
ClientVersion string Required The target app client version.

CountryBlockCountry

A blocked country specified in a service country restriction item. It holds an App ID and a country code as a pair.

Field Type Required Description
AppId string Required The App ID to which the block applies.
CountryCode string Required The ISO 3166-1 alpha-2 country code of the blocked country.

GetActiveMaintenancesRequest

A server maintenance retrieval request. You can omit all fields, and specifying an empty string for ServerCode or ClientVersion is the same as omitting it.

Field Type Required Description
ServerCode string? Optional The server ID of the app server to query. Specify the value registered in App Server in the console.
ClientVersion string? Optional The app client version. Specify it in the same format as the version registered in the console.
PlayerId long? Optional The Player ID used to determine whether the allowlist applies.

GetActiveMaintenancesResponseData

The server maintenance retrieval result.

Field Type Required Description
Items IReadOnlyList<Maintenance> Required The list of server maintenance in effect. An empty list if no maintenance is in effect.
Meta ResponseMeta? Optional Additional response information.

Maintenance

A server maintenance item in effect.

Field Type Required Description
Id long Required The ID of the server maintenance item.
StartAt DateTimeOffset? Optional The maintenance start time. null only for always-on items registered without a start time.
EndAt DateTimeOffset? Optional The maintenance end time. null if there is no end time, as with always-on items.
AlwaysOn bool Required Whether the item is an always-on item.
Title string Required The maintenance notice title.
Content string Required The maintenance notice body.
RedirectUrl string Required The maintenance notice destination.
Timezone TimeZoneInfo Required The time zone information for StartAt and EndAt.
Servers IReadOnlyList<string> Required The list of server IDs under maintenance. An empty list if the maintenance does not specify target servers.
Versions IReadOnlyList<MaintenanceVersion> Required Of the versions under maintenance, the list of versions for the requested App ID. An empty list if the maintenance does not specify target versions.

MaintenanceVersion

A target version specified in a server maintenance item. It holds an App ID and a version as a pair.

Field Type Required Description
AppId string Required The target App ID.
ClientVersion string Required The target app client version.

ResponseMeta

Additional response information. The service access control server sends Meta in the response as null, so use XTraceId in the response headers for inquiries or log lookups.

Field Type Required Description
RequestId string? Optional The request ID used for inquiries or log lookups.
Timestamp DateTimeOffset? Optional The time when the server created the response.

TimeZoneInfo, TimeZoneInfoNullable

TimeZoneInfo and TimeZoneInfoNullable are time zone information for interpreting StartAt and EndAt in the response, and they have the same fields. Maintenance.Timezone is a TimeZoneInfo that always contains a value, and Timezone in the client update and service country restriction check results is a TimeZoneInfoNullable that becomes null if no item applies.

Regardless of the request values, the server determines the time zone based on the country identified from the access IP, and uses UTC if the country cannot be identified. Therefore, the app does not need to send time zone information separately. The UTC offsets of StartAt and EndAt are the values that apply in this time zone at each time, so if a daylight saving time transition occurs between the two times, their offsets differ.

Same name as System.TimeZoneInfo

The System namespace also has a TimeZoneInfo with the same name. If you declare both using System; and using Hive.Axyl.ServiceAccess; in one file and then use TimeZoneInfo as is, it is ambiguous which type you mean, and a compile error occurs. In such files, assign an alias such as using AccessTimeZoneInfo = Hive.Axyl.ServiceAccess.TimeZoneInfo; or use the fully qualified name.

Field Type Required Description
Id string Required The IANA time zone identifier. Example: Asia/Seoul
UtcOffset string Required The UTC offset in ±HH:MM format, reflecting daylight saving time. The reference time is StartAt; if StartAt is null, it is EndAt, and if both are null, it is the current time. If the offset is 0, the value is +00:00. Example: +09:00
OffsetSeconds int Required The UTC offset in seconds. It is calculated with the same reference time as UtcOffset. Example: 32400
Dst bool Required true if daylight saving time applies at the reference time of UtcOffset.
IsInEuropeanUnion bool Required true if the country used to determine the time zone is a member state of the European Union. false if UTC is used.
Name string? Optional The country name in the request language. If there is no name for the request language tag, the name is looked up in this order: the tag with only the language part, English, and then 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. The language tags provided by default are de, en, es, fr, ja, pt-BR, ru, zh-CN, ko, vi, and fil, and only the languages that have a name are included. Empty if UTC is used.

Response header types

CheckClientUpdateResponseHeaders, CheckCountryBlockResponseHeaders, and GetActiveMaintenancesResponseHeaders are the response header values passed in Success.Headers of each method, and they have the same fields.

Field Type Required Description
XTraceId string? Optional A 32-digit hexadecimal trace ID that the server includes in every response. It is the same value as the trace ID that the SDK creates for each request. Use it when you inquire about a problem or look up logs.