Server maintenance

Use the server maintenance retrieval method to check the maintenance items that are active at the current time.

1. Configure server maintenance in the Hive Console

To use server maintenance, first register a maintenance 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 Server Maintenance. For the input fields on the registration screen, see Service access control items. You must register the servers to select as maintenance targets in the console in advance. For how to register them, see App server.

2. Prepare the call parameter values

Before the call, prepare ServerCode and ClientVersion, which determine the retrieval scope, and PlayerId, which is used to check whether the allowlist applies.

ServerCode

ServerCode is the server ID registered in Hive Console > App Info > App Server. For how to register an app server, see App server. Specify it to retrieve only the maintenance that applies to a specific server. If you pass this value, the method retrieves the maintenance items registered for that server together with the maintenance items that have no target server specified. If you omit it or specify an empty string, the method retrieves all active maintenance items regardless of the target server.

ClientVersion

ClientVersion is the version of the currently running app client. If you pass this value, the method retrieves the maintenance items that have no target version specified together with the maintenance items registered for the app's App ID and this version. If you omit it or specify an empty string, maintenance items with a target version specified are excluded from the results, and only maintenance items with no version specified are retrieved.

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.

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.Items is an empty list even during maintenance. For server maintenance, if an allowlist item specifies an app version, the item applies only when the request's ClientVersion is the same as that version. If you omit ClientVersion, only the allowlist items with no app version specified apply. 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 server maintenance retrieval method

GetActiveMaintenancesAsync

Call GetActiveMaintenancesAsync() to retrieve the server maintenance items that are in effect at the current time. Based on the returned maintenance list, the app itself decides whether to restrict access or show a maintenance notice screen. You can call it even before login, and you usually run it when the app starts.

Call parameters

Field name	Type	Required	Description
request	GetActiveMaintenancesRequest	Required	Server maintenance 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.

GetActiveMaintenancesRequest

Field name	Type	Required	Description
`ServerCode`	string	Optional	The server ID registered in Hive Console > App Info > App Server. If specified, the method retrieves the maintenance registered for this server and the maintenance with no target server specified; if omitted or an empty string, it retrieves maintenance for all servers.
`ClientVersion`	string	Optional	Current app client version. Only a target version whose string is exactly the same matches; if omitted or an empty string, maintenance items with a target version specified are not retrieved.
`PlayerId`	long?	Optional	Player ID used to check whether the allowlist applies. Omit it before login.

Call example

The GetActiveMaintenancesAsync() 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 GetActiveMaintenancesRequest {
    // ServerCode    = "{serverCode}",       // Specify to retrieve only a specific app server
    // ClientVersion = Application.version,  // Specify to also retrieve maintenance targeting the current version and to apply allowlist items with a specified version
    // PlayerId      = HiveCore.Resolve<ISessionManager>().PlayerId,  // Specify when checking again after login
};

ServiceAccessGetActiveMaintenancesResult result = await service.GetActiveMaintenancesAsync(request);

switch (result)
{
    case ServiceAccessGetActiveMaintenancesResult.Success success:
        if (success.Data.Items.Count > 0)
        {
            // Active maintenance exists -> show the maintenance notice screen (the app implements the actual access restriction)
            foreach (Maintenance m in success.Data.Items)
                Debug.Log($"Under maintenance: {m.Title} ({m.Content})");
        }
        else
        {
            // No active maintenance -> proceed normally
        }
        break;

    // Handle common failures (network and server errors, request value errors)
    case ServiceAccessGetActiveMaintenancesResult.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 (GetActiveMaintenancesResponseData) of ServiceAccessGetActiveMaintenancesResult.Success. Data.Items is sorted starting from the most recently registered maintenance item, and it is an empty list if there is no active maintenance.

Field name	Type	Required	Description
`Data.Items`	`IReadOnlyList<Maintenance>`	Required	List of active server maintenance items. It is an empty list if there is no active maintenance.

Maintenance

Field name	Type	Required	Description
`Id`	long	Required	Maintenance identifier
`Title`	string	Required	Maintenance notice title
`Content`	string	Required	Maintenance notice body
`RedirectUrl`	string	Required	Maintenance notice URL. Empty string if not set in the console
`Servers`	`IReadOnlyList<string>`	Required	List of server IDs under maintenance. Empty list for maintenance that applies regardless of the server because no target server is specified
`Versions`	`IReadOnlyList<MaintenanceVersion>`	Required	List of maintenance target versions specified for the requested App ID. Empty list for maintenance with no target version specified. For the item structure, see `MaintenanceVersion` below
`AlwaysOn`	bool	Required	Whether this is always-on maintenance
`StartAt`·`EndAt`	DateTimeOffset?	Optional	Maintenance start and end times. `StartAt` is `null` only for always-on maintenance registered without a start time, and `EndAt` is `null` for always-on maintenance with no end time
`Timezone`	`TimeZoneInfo`	Required	Reference time zone for interpreting `StartAt` and `EndAt`. For the item structure, see `TimeZoneInfo` below

MaintenanceVersion

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

TimeZoneInfo

Timezone is the time zone information for interpreting StartAt and EndAt, and it is always included in every maintenance item. 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.

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.

Note

The fully qualified name of this type is Hive.Axyl.ServiceAccess.TimeZoneInfo. If you also use using System; in the same file, the name conflicts with System.TimeZoneInfo and causes a compile error. In that case, write the fully qualified name or specify a using alias.

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

The returned maintenance list provides notice information only. The app client must implement the actual access blocking, maintenance screen display, and redirect handling itself.

Response headers

On success, the response header values are contained in Headers (GetActiveMaintenancesResponseHeaders) of ServiceAccessGetActiveMaintenancesResult.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