IPushService

This service manages, on the Hive Axyl server, the device tokens used to receive remote push notifications. It provides device token registration, changes to the token language and push notification consent, and detaching the token from the user. Push notification Add-ons handle tasks that call Firebase Cloud Messaging or Apple's notification framework directly on the device, such as device token issuance. For the division of roles, see Relationship with push notification Add-ons.

Item	Value
Interface	`IPushService`
Namespace	`Hive.Axyl.Push`
Package	`com.com2usplatform.hiveaxyl.push`

Registration and retrieval

Unity

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

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

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

IPushService push = HiveCore.Resolve<IPushService>();

Method summary

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

Method	Authentication	Description
UpsertTokenAsync	Session required	Registers the device token by linking it to the logged-in user. If the token is already registered, updates all of the token information.
PatchTokenLanguageAsync	Session required	Changes the language of a registered device token.
PatchTokenAgreementAsync	Session required	Changes the push notification consent settings of a registered device token.
DetachTokenIdentifierAsync	Session required	Detaches the device token from the user.

The server accepts the requests of all methods and then processes them asynchronously. Therefore, Success means that the server has accepted the request, and no data is returned in the response.

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

Exception	When thrown
`ArgumentNullException`	When `request` is `null`

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.

Wire code	Meaning
`bad_request`	The request is invalid.
`invalid_parameter`	A request parameter is not in the correct format.
`missing_field`	A required field or required header itself is missing. This includes the case where the `X-App-Id` header is not sent.
`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`	You do not have permission for the request.
`resource_not_found`	The requested resource does not exist.
`method_not_allowed`	The request method is not allowed.
`resource_conflict`	The resource state conflicts with the request.
`unprocessable_content`	The request content cannot be processed.
`rate_limit_exceeded`	The request rate exceeds the allowed limit.
`internal_error`	An internal server error occurred.
`service_unavailable`	The service is temporarily unavailable.

Methods

UpsertTokenAsync

Registers the device token with the Hive Axyl server by linking it to the logged-in user. If the requested Token already exists on the server, the token information is updated with all of the request values; otherwise, the token is newly registered. You do not include a user identifier in the request. The server gets the Player ID from the authentication token of the login session and links it to the token.

Because the token information is updated with all of the request values, specify the app user's current consent settings and language even when you register an already registered token again. Consent items that you do not specify in Agreement change to false.

Each time the token is registered or updated, the validity period of the token stored on the server is renewed to one year. Sending the same request multiple times produces the same result, so if you do not receive a response, you can send the same request again.

Get the device token with GetTokenAsync() of the Firebase Cloud Messaging push notification Add-on on Android, and with GetTokenAsync() of the Apple Push Notification service push notification Add-on on iOS and macOS. When a new token is issued, both Add-ons raise the TokenRefreshed event, but they do not register the token with the Hive Axyl server automatically. Register the new token you receive through the event with this method as well.

Unity

Task<PushUpsertTokenResult> UpsertTokenAsync(UpsertTokenRequest request, ApiCallContext? context = null);

Item	Value
Request	UpsertTokenRequest
Response	None
Authentication	Session required

Result cases — PushUpsertTokenResult

Result case	Wire code	Description
`Success`	—	The server accepted the registration request.
`ResourceNotInScope`	`resource_not_in_scope`	The requested resource does not belong to the scope of the authenticated project.
`InvalidSubject`	`invalid_subject`	The method was called with a type of authentication token that this method does not allow.
`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 Hive.Axyl.Core;
using Hive.Axyl.Push;

var result = await push.UpsertTokenAsync(new UpsertTokenRequest
{
    Token        = deviceToken,                          // Token received from GetTokenAsync() of the push notification Add-on
    ProviderType = UpsertTokenRequestProviderType.Fcm,   // For Android. On iOS and macOS, use Apns or ApnsSandbox
    TimezoneId   = "Asia/Seoul",
    Country      = "KR",
    Language     = LanguageCode.Ko,
    Agreement    = new Agreement
    {
        Info      = true,
        Advertise = true,
        Night     = false,
    },
});

switch (result)
{
    case PushUpsertTokenResult.Success:
        // The server accepted the registration request.
        break;

    case PushUpsertTokenResult.Failure failure:
        HiveError error = failure.Problem;
        break;

    default:
        // Unhandled results and UnknownOutcome
        break;
}

PatchTokenLanguageAsync

Changes only the language of a registered device token. The server finds the token that matches Token and is linked to the logged-in user, and changes its language. The token language is referenced when the language of push notification messages is determined.

Unity

Task<PushPatchTokenLanguageResult> PatchTokenLanguageAsync(PatchTokenLanguageRequest request, ApiCallContext? context = null);

Item	Value
Request	PatchTokenLanguageRequest
Response	None
Authentication	Session required

Result cases — PushPatchTokenLanguageResult

Result case	Wire code	Description
`Success`	—	The server accepted the language change request.
`ResourceNotInScope`	`resource_not_in_scope`	The requested resource does not belong to the scope of the authenticated project.
`InvalidSubject`	`invalid_subject`	The method was called with a type of authentication token that this method does not allow.
`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.

PatchTokenAgreementAsync

Changes the push notification consent settings of a registered device token to all of the requested values. The server finds the token that matches Token and is linked to the logged-in user, and changes its consent settings.

Even when you change only one consent item, specify all of Info, Advertise, and Night in Agreement. Items that you do not specify are sent as false, so items that the app user consented to are changed to a not-consented state.

Unity

Task<PushPatchTokenAgreementResult> PatchTokenAgreementAsync(PatchTokenAgreementRequest request, ApiCallContext? context = null);

Item	Value
Request	PatchTokenAgreementRequest
Response	None
Authentication	Session required

Result cases — PushPatchTokenAgreementResult

Result case	Wire code	Description
`Success`	—	The server accepted the consent change request.
`ResourceNotInScope`	`resource_not_in_scope`	The requested resource does not belong to the scope of the authenticated project.
`InvalidSubject`	`invalid_subject`	The method was called with a type of authentication token that this method does not allow.
`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.

DetachTokenIdentifierAsync

Detaches the device token from the user. The token data stored on the server is not deleted; only the Player ID linked to the token is detached. Call this method when the user logs out.

This method also identifies the user by the login session, so you must call it before you discard the session with LogoutPlayerAsync.

Unity

Task<PushDetachTokenIdentifierResult> DetachTokenIdentifierAsync(DetachTokenIdentifierRequest request, ApiCallContext? context = null);

Item	Value
Request	DetachTokenIdentifierRequest
Response	None
Authentication	Session required

Result cases — PushDetachTokenIdentifierResult

Result case	Wire code	Description
`Success`	—	The server accepted the detach request.
`ResourceNotInScope`	`resource_not_in_scope`	The requested resource does not belong to the scope of the authenticated project.
`InvalidSubject`	`invalid_subject`	The method was called with a type of authentication token that this method does not allow.
`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.

Data types

Fields shared by multiple request types have the same meaning.

Shared field	Meaning
`Token`	The device token issued by the push service. Get it with `GetTokenAsync()` of the Firebase Cloud Messaging push notification Add-on on Android, and of the Apple Push Notification service push notification Add-on on iOS and macOS. In language change, consent change, and detach requests, use the same value that you registered with UpsertTokenAsync.
`Language`	The language code of the token. It is referenced when the language of push notification messages is determined. For the values you can specify, see LanguageCode.

Agreement

Push notification consent settings. The default value of all three fields is false, and the three values are always sent together in a request.

When the app server sends a notification with Send remote push notifications, the devices that receive the notification are determined by the notification type and these settings. Informational notifications whose category is INFO are delivered to devices where Info is true, and advertising notifications whose category is ADVERTISE are delivered to devices where both Advertise and Night are true.

Field	Type	Required	Description
`Advertise`	`bool`	Required	Whether the user consents to receive advertising push notifications.
`Info`	`bool`	Required	Whether the user consents to receive informational push notifications.
`Night`	`bool`	Required	Whether the user consents to receive nighttime advertising push notifications. It cannot be set to `true` if `Advertise` is `false`.

DetachTokenIdentifierRequest

A request to detach the device token from the user.

Field	Type	Required	Description
`Token`	`string`	Required	The device token to detach from the user.

PatchTokenAgreementRequest

A request to change the push notification consent of a device token.

Field	Type	Required	Description
`Agreement`	Agreement	Required	The complete set of consent settings to apply.
`Token`	`string`	Required	The device token whose consent settings you change.

PatchTokenLanguageRequest

A request to change the language of a device token.

Field	Type	Required	Description
`Language`	LanguageCode	Required	The language code to apply.
`Token`	`string`	Required	The device token whose language you change.

UpsertTokenRequest

A device token registration request. If the token is already registered, the token information is updated with all of the values in this request.

Field	Type	Required	Description
`Agreement`	Agreement	Required	Push notification consent settings. Specify all three items; items that you do not specify are sent as `false`.
`AppVersion`	`string?`	Optional	The app version. Up to 32 characters.
`Country`	`string`	Required	The ISO 3166-1 two-letter country code of the device. It is referenced when push campaigns, which are scheduled push notifications, filter recipients by country. Example: `KR`
`EventType`	`string?`	Optional	The type of event that triggered the token registration. It is stored for record-keeping and can be up to 32 characters. Example: `LOGIN`
`Language`	LanguageCode	Required	The language code of the token.
`ProviderType`	UpsertTokenRequestProviderType	Required	The push service that delivers push notifications. On Android, specify `Fcm`. On iOS and macOS, specify `Apns` or `ApnsSandbox` according to the environment reported by GetProviderEnvironmentAsync() of the Apple Push Notification service push notification Add-on.
`SdkVersion`	`string?`	Optional	The Hive Axyl SDK version applied to the app. Up to 32 characters.
`ServerId`	`string?`	Optional	The app server ID. Up to 64 characters.
`TimezoneId`	`string`	Required	The time zone name of the device. Enter a name from the Internet Assigned Numbers Authority (IANA) time zone database; if you enter a name that does not exist, the request is rejected. It is referenced when push campaigns are sent based on the device's local time. Up to 64 characters. Example: `Asia/Seoul`, `America/New_York`
`Token`	`string`	Required	The device token to register.

Enums

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

LanguageCode

Language codes that Hive Axyl supports. Specify them in UpsertTokenRequest.Language and PatchTokenLanguageRequest.Language.

The Mailbox module also has LanguageCode

The Hive.Axyl.Mailbox namespace also has a LanguageCode with the same name. If you import both namespaces in one file and then use LanguageCode as is, it is ambiguous which type you mean, and a compile error occurs. To use both types in one file, assign an alias to each type, such as using PushLanguageCode = Hive.Axyl.Push.LanguageCode; and using MailboxLanguageCode = Hive.Axyl.Mailbox.LanguageCode;.

C# member	Wire value	Description
`Unspecified`	`LANGUAGE_CODE_UNSPECIFIED`	The default value when no value is specified. Do not use it in requests.
`Ko`	`ko`	Korean.
`En`	`en`	English.
`Ja`	`ja`	Japanese.
`ZhHans`	`zh-Hans`	Simplified Chinese.
`ZhHant`	`zh-Hant`	Traditional Chinese.
`De`	`de`	German.
`Fr`	`fr`	French.
`Ru`	`ru`	Russian.
`It`	`it`	Italian.
`Es`	`es`	Spanish.
`Pt`	`pt`	Portuguese.
`Pl`	`pl`	Polish.
`Nl`	`nl`	Dutch.
`Tr`	`tr`	Turkish.
`Th`	`th`	Thai.
`Id`	`id`	Indonesian.
`Ar`	`ar`	Arabic.
`Hi`	`hi`	Hindi.
`Vi`	`vi`	Vietnamese.
`Sv`	`sv`	Swedish.
`Cs`	`cs`	Czech.
`Fa`	`fa`	Persian.
`No`	`no`	Norwegian.
`Uk`	`uk`	Ukrainian.
`Ro`	`ro`	Romanian.
`He`	`he`	Hebrew.
`Ms`	`ms`	Malay.
`Da`	`da`	Danish.
`El`	`el`	Greek.
`Hu`	`hu`	Hungarian.
`Tl`	`tl`	Tagalog.

UpsertTokenRequestProviderType

The push service that delivers push notifications. Specify it in UpsertTokenRequest.ProviderType.

C# member	Wire value	Description
`Unspecified`	`UPSERT_TOKEN_REQUEST_PROVIDER_TYPE_UNSPECIFIED`	The default value when no value is specified. Do not use it in requests.
`Fcm`	`FCM`	Firebase Cloud Messaging. Specify it for tokens of Android devices.
`Apns`	`APNS`	The production environment of Apple Push Notification service (APNs). Specify it for tokens of iOS and macOS devices for which `GetProviderEnvironmentAsync()` reported the `Apns` environment.
`ApnsSandbox`	`APNS_SANDBOX`	The APNs sandbox environment. Specify it for tokens of iOS and macOS devices for which `GetProviderEnvironmentAsync()` reported the `ApnsSandbox` environment.