Service country restriction

Use the service country restriction check method to check whether the user country code that the app passes matches a blocked country registered in the console.

1. Configure service country restriction in the Hive Console

To use service country restriction, first register a blocking 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 Service Country Restriction. 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 CountryCode, which determines whether access is blocked, and PlayerId, which is used to check whether the allowlist applies.

CountryCode

CountryCode is the ISO 3166-1 alpha-2 country code that represents the user's country. For example, the Republic of Korea is KR. The server compares this value, case-insensitively, with the blocked countries registered in the console to determine whether access is blocked.

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.Blocked is false even if a blocking item is in effect. For service country restriction, even if an allowlist item specifies an app version, the item applies regardless of the 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 service country restriction check method

CheckCountryBlockAsync

Call CheckCountryBlockAsync() to check whether the CountryCode in the request matches a blocked country of a service country restriction item in effect. If the user is blocked, the method also returns the notice title, body, and redirect URL. According to this result, the app decides whether to block entry or show a 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	CheckCountryBlockRequest	Required	Country block 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.

CheckCountryBlockRequest

Field name	Type	Required	Description
`CountryCode`	string	Required	Country code (ISO 3166-1 alpha-2). The server compares this value, case-insensitively, with the blocked countries registered in the console.
`PlayerId`	long?	Optional	Player ID used to check whether the allowlist applies. Omit it before login.

Call example

The CheckCountryBlockAsync() 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 CheckCountryBlockRequest {
    CountryCode = "CN",   // User country code (ISO 3166-1 alpha-2)
    // PlayerId = HiveCore.Resolve<ISessionManager>().PlayerId,  // Specify when checking again after login
};

ServiceAccessCheckCountryBlockResult result = await service.CheckCountryBlockAsync(request);

switch (result)
{
    case ServiceAccessCheckCountryBlockResult.Success success:
        if (success.Data.Blocked)
        {
            // Blocked -> show a notice screen or redirect (the app implements the actual blocking)
            Debug.Log($"Access blocked: {success.Data.Title} ({success.Data.RedirectUrl})");
        }
        else
        {
            // Access allowed
        }
        break;

    // Handle common failures (network and server errors, request value errors)
    case ServiceAccessCheckCountryBlockResult.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 (CheckCountryBlockResponseData) of ServiceAccessCheckCountryBlockResult.Success. If Data.Blocked is true, the app must implement the notice UI and the redirect itself. If multiple blocking items apply to the requested country, the notice message and the list of blocked countries of the most recently registered item are returned.

Field name	Type	Required	Description
`Data.Blocked`	bool	Required	Whether the passed country code is blocked
`Data.Id`	long?	Optional	ID of the applied service country restriction item. `null` if not blocked
`Data.Title`	string	Required	Notice title to display when blocked. Empty string if not blocked
`Data.Content`	string	Required	Notice body to display when blocked. Empty string if not blocked
`Data.RedirectUrl`	string	Required	Notice URL to send the user to when blocked. Empty string if not set in the console or if not blocked
`Data.Countries`	`IReadOnlyList<CountryBlockCountry>`	Required	List of blocked countries specified for the requested App ID in the applied item. Empty list if not blocked. For the item structure, see `CountryBlockCountry` below
`Data.AlwaysOn`	bool	Required	Whether this is an always-on block
`Data.StartAt`·`Data.EndAt`	DateTimeOffset?	Optional	Block effective period. Both are `null` if not blocked; `StartAt` is `null` for an item with no start time specified, and `EndAt` is `null` for an always-on block with no end time
`Data.Timezone`	`TimeZoneInfoNullable`	Optional	Reference time zone for interpreting `StartAt` and `EndAt`. `null` if not blocked. For the item structure, see `TimeZoneInfoNullable` below

CountryBlockCountry

Field name	Type	Required	Description
`AppId`	string	Required	App ID subject to the block
`CountryCode`	string	Required	Blocked country code (ISO 3166-1 alpha-2)

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, regardless of the CountryCode in the request, 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 the user is not blocked, 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.Blocked is false, the notice title, body, and redirect URL are all empty strings. Check Data.Blocked first before you show a notice screen. The app client must implement the actual access blocking and notice screen display itself.

Response headers

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