GS2-LoginReward SDK for Game Engine API Reference
Model
EzReceiveStatus
Receive Status
Tracks the login bonus receive status for each user per bonus model. Maintains a boolean array (receivedSteps) where each entry indicates whether the user has received the corresponding day’s reward. Also records the last time a bonus was received (lastReceivedAt) to determine daily eligibility. The receivedSteps can be reset when the bonus cycle restarts (e.g., in Streaming Mode with repeat enabled).
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. | ||
| receivedSteps | List<bool> | [] | 0 ~ 100 items | Received Steps An ordered boolean array where each element corresponds to a day in the reward list. true indicates the user has received that day’s reward; false indicates it was missed or not yet received. The array index aligns with the rewards array in the associated BonusModel. In Streaming Mode with repeat enabled, this array is reset when the cycle restarts. | ||
| lastReceivedAt | long | Last Received At The timestamp of when the user last received a login bonus. Used to determine whether the user has already received today’s bonus based on the reset hour defined in the bonus model. Reset to 0 when the receive status is cleared (e.g., on cycle restart in repeat mode). |
EzBonusModel
Login Bonus Model
Login Bonus Model defines the distribution schedule for login bonuses. There are two schedule types: 《Schedule Mode》 and 《Streaming Mode》.
In Schedule Mode, a GS2-Schedule event must be specified, and bonuses are distributed based on the number of days elapsed since the event’s start date. If the user misses a day partway through, the bonus for that day will not be granted.
In Streaming Mode, the rewards configured for the bonus are distributed sequentially from the beginning each day. Streaming Mode also supports repetition; when enabled, the distribution restarts from the first reward after reaching the end of the stream.
Both Schedule Mode and Streaming Mode provide a missed-bonus recovery feature. By paying a certain cost, users can receive bonuses they previously missed. However, if a GS2-Schedule event is associated, users cannot receive bonuses beyond the number of days elapsed since the event’s start date. Additionally, the recovery feature cannot be used when using Streaming Mode with repetition enabled.
In both Schedule Mode and Streaming Mode, the maximum number of days that can be configured for bonuses is 100 days.
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||||||||
| mode | String Enum enum { “schedule”, “streaming” } | ✓ | Mode Specifies the distribution schedule type for the login bonus. In “schedule” mode, rewards are tied to elapsed days since a GS2-Schedule event start date. In “streaming” mode, rewards are distributed sequentially from the beginning each day regardless of calendar date.
| |||||||||
| periodEventId | string | ~ 1024 chars | Period Event GRN GS2-Schedule Event GRN that represents the period during which to enable login bonuses. In Schedule Mode, this field is required and determines the start date from which elapsed days are counted for reward distribution. In Streaming Mode, this field is optional; when specified, users cannot receive bonuses beyond the elapsed days since the event start. | |||||||||
| resetHour | int | {periodEventId} == "" | ✓* | 0 ~ 23 | Reset Hour (UTC) The hour of day (0-23, UTC) at which the daily receive flag resets. This determines when a new day begins for login bonus purposes. Only required when periodEventId is not specified; when an event is set, the reset timing follows the event’s schedule. * Required if periodEventId is “" | |||||||
| repeat | String Enum enum { “enabled”, “disabled” } | {mode} == “streaming” | ✓* | Repeat Whether to restart distribution from the beginning after all rewards have been distributed. Only applicable in Streaming Mode. When enabled, the reward list loops back to the first entry after the last one is distributed. Note: the missed-bonus recovery feature cannot be used when repeat is enabled.
* Required if mode is “streaming” | ||||||||
| rewards | List<EzReward> | 0 ~ 100 items | Rewards The ordered list of daily rewards. Each entry corresponds to one day’s login bonus, distributed sequentially from index 0. In Schedule Mode, the index maps to the number of elapsed days since the event start date. In Streaming Mode, the index maps to the number of login days. Up to 100 entries can be configured. | |||||||||
| missedReceiveRelief | String Enum enum { “enabled”, “disabled” } | “disabled” | Missed Receive Relief Whether to enable the missed-bonus recovery feature. When enabled, users can retroactively receive bonuses they missed by paying a specified cost (consume actions). Optionally, verify actions can be configured to check conditions before allowing recovery. This feature cannot be used when Streaming Mode with repeat enabled is active. Defaults to “disabled”.
| |||||||||
| missedReceiveReliefVerifyActions | List<EzVerifyAction> | {missedReceiveRelief} == “enabled” | * | [] | 0 ~ 10 items | Missed Receive Relief Verify Actions List of verify actions to execute before allowing missed-bonus recovery. These actions check preconditions (e.g., user eligibility) before the recovery is processed. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Applicable only if missedReceiveRelief is “enabled” | ||||||
| missedReceiveReliefConsumeActions | List<EzConsumeAction> | {missedReceiveRelief} == “enabled” | * | [] | 0 ~ 10 items | Missed Receive Relief Consume Actions List of consume actions that define the cost a user must pay to recover a missed bonus. For example, this can be configured to consume in-game currency or items as the recovery cost. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Applicable only if missedReceiveRelief is “enabled” |
EzReward
Reward
Represents a single day’s reward configuration for a login bonus. Each Reward contains a list of acquire actions that define what the user receives (e.g., items, currency, experience). The rewards array in BonusModel holds one Reward per day, distributed in order. Reward values can be modified at runtime through the buff system (BonusModelBuff) to apply rate multipliers to acquire actions.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| acquireActions | List<EzAcquireAction> | ✓ | 1 ~ 10 items | Acquire Actions List of acquire actions that define the resources granted to the user for this day’s reward. Each action specifies a acquire action (e.g., add items, grant currency) and its request parameters. At least 1 and up to 10 actions can be configured per reward. |
EzConfig
Configuration
A key-value pair used to set values applied to transaction variables. Config entries allow dynamic parameterization of acquire actions at runtime. For example, slot names or other context-dependent values can be injected into transaction requests via Config settings, enabling flexible reward configuration without modifying the master data.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| key | string | ✓ | ~ 64 chars | Key The variable name to be replaced in transaction parameters. Maximum 64 characters. | ||
| value | string | ~ 51200 chars | Value The value to substitute for the corresponding key in transaction parameters. Maximum 51,200 characters. |
EzConsumeAction
Consume Action
Defines an action for consuming resources from a user via the transaction mechanism. Used in missed-bonus recovery to specify the cost users must pay (e.g., deducting currency, consuming items). The action field specifies the type of consume action, and the request field contains the corresponding request parameters.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| action | String Enum enum { } | ✓ | Type of action to be executed in the Consume Action | |||
| request | string | ✓ | ~ 524288 chars | JSON string of the request used when executing the action |
EzVerifyAction
Verify Action
Defines an action for verifying conditions before proceeding with an operation. Used in missed-bonus recovery to check preconditions (e.g., user eligibility, resource availability) before allowing the recovery. The action field specifies the type of verify action, and the request field contains the corresponding request parameters.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| action | String Enum enum { } | ✓ | Type of action to be executed in the Verify Action | |||
| request | string | ✓ | ~ 524288 chars | JSON string of the request used when executing the action |
EzAcquireAction
Acquire Action
Defines an action for granting resources to a user via the transaction mechanism. Used within rewards to specify what the user receives (e.g., adding items to inventory, granting currency, awarding experience points). The action field specifies the type of acquire action, and the request field contains the corresponding request parameters.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| action | String Enum enum { } | ✓ | Type of action to be executed in the Acquire Action | |||
| request | string | ✓ | ~ 524288 chars | JSON string of the request used when executing the action |
EzVerifyActionResult
Verify Action execution result
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| action | String Enum enum { } | ✓ | Type of action to be executed in the Verify Action | |||
| verifyRequest | string | ✓ | ~ 524288 chars | JSON string of the request used when executing the action | ||
| statusCode | int | 0 ~ 999 | Status code | |||
| verifyResult | string | ~ 1048576 chars | Result payload |
EzConsumeActionResult
Consume Action execution result
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| action | String Enum enum { } | ✓ | Type of action to be executed in the Consume Action | |||
| consumeRequest | string | ✓ | ~ 524288 chars | JSON string of the request used when executing the action | ||
| statusCode | int | 0 ~ 999 | Status code | |||
| consumeResult | string | ~ 1048576 chars | Result payload |
EzAcquireActionResult
Acquire Action execution result
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| action | String Enum enum { } | ✓ | Type of action to be executed in the Acquire Action | |||
| acquireRequest | string | ✓ | ~ 524288 chars | JSON string of the request used when executing the action | ||
| statusCode | int | 0 ~ 999 | Status code | |||
| acquireResult | string | ~ 1048576 chars | Result payload |
EzTransactionResult
Transaction execution results
Result of a transaction executed using the server-side automatic transaction execution feature
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ | 36 ~ 36 chars | Transaction ID | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 10 items | List of verify action execution results | |||
| consumeResults | List<EzConsumeActionResult> | [] | 0 ~ 10 items | List of Consume Action execution results | ||
| acquireResults | List<EzAcquireActionResult> | [] | 0 ~ 100 items | List of Acquire Action execution results |
Methods
missedReceive
Receive a missed login bonus
Allows the player to retroactively claim a login bonus they missed on a previous day. This feature must be enabled on the bonus model (the “missed receive relief” setting). When enabled, the player can recover a missed reward by paying a cost — for example, spending 50 Gems to claim the reward they missed on Day 3.
In Schedule Mode, only rewards up to the number of elapsed days since the event start can be recovered. In Streaming Mode, the step number can be automatically determined, so it can be omitted.
This feature is not available when Streaming Mode has “repeat” enabled.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| bonusModelName | string | ✓ | ~ 128 chars | Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| stepNumber | int | 0 ~ 100 | Step number to receive. In streaming mode, this can be omitted | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | Configuration values applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzReceiveStatus | Receive status |
| bonusModel | EzBonusModel | Login Bonus Model |
| transactionId | string | Issued transaction ID |
| stampSheet | string | Stamp sheet used to execute the receipt of login bonuses |
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations |
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction execution result |
Error
Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.
| Type | Base Type | Description |
|---|---|---|
| AlreadyReceivedException | BadRequestException | You have already received today’s login bonus. |
Implementation Example
try {
var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Bonus(
);
var result = await domain.MissedReceiveAsync(
bonusModelName: "bonus-0001",
stepNumber: 1,
config: null
);
} catch(Gs2.Gs2LoginReward.Exception.AlreadyReceivedException e) {
// You have already received today's login bonus.
}
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry(). var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Bonus(
);
var future = domain.MissedReceiveFuture(
bonusModelName: "bonus-0001",
stepNumber: 1,
config: null
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2LoginReward.Exception.AlreadyReceivedException)
{
// You have already received today's login bonus.
}
onError.Invoke(future.Error, null);
yield break;
}
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry(). const auto Domain = Gs2->LoginReward->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Bonus(
);
const auto Future = Domain->MissedReceive(
"bonus-0001", // bonusModelName
1 // stepNumber
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::LoginReward::Error::FAlreadyReceivedError::Class))
{
// You have already received today's login bonus.
}
return false;
}receive
Receive today’s login bonus
Claims the login bonus for the current day based on the specified bonus model. Each bonus model defines a sequence of daily rewards — for example, “Day 1: 100 Gems, Day 2: 5 Stamina Potions, Day 3: Rare Gacha Ticket, …”. The player progresses through the reward steps each day they log in and call this API.
There are two modes:
- Schedule Mode: Rewards are tied to a specific calendar period. If the player misses a day, that day’s reward is skipped.
- Streaming Mode: Rewards are given in order from the beginning each time the player logs in, regardless of the calendar date.
If the player has already received today’s bonus, an error is returned. When all rewards in the sequence have been given and “repeat” is enabled (Streaming Mode only), the cycle starts over from the first reward.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| bonusModelName | string | ✓ | ~ 128 chars | Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | Configuration values applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzReceiveStatus | Receive status |
| bonusModel | EzBonusModel | Login Bonus Model |
| transactionId | string | Issued transaction ID |
| stampSheet | string | Stamp sheet used to execute the receipt of login bonuses |
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations |
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction execution result |
Error
Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.
| Type | Base Type | Description |
|---|---|---|
| AlreadyReceivedException | BadRequestException | You have already received today’s login bonus. |
Implementation Example
try {
var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Bonus(
);
var result = await domain.ReceiveAsync(
bonusModelName: "bonus-0001",
config: null
);
} catch(Gs2.Gs2LoginReward.Exception.AlreadyReceivedException e) {
// You have already received today's login bonus.
}
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry(). var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Bonus(
);
var future = domain.ReceiveFuture(
bonusModelName: "bonus-0001",
config: null
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2LoginReward.Exception.AlreadyReceivedException)
{
// You have already received today's login bonus.
}
onError.Invoke(future.Error, null);
yield break;
}
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry(). const auto Domain = Gs2->LoginReward->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Bonus(
);
const auto Future = Domain->Receive(
"bonus-0001" // bonusModelName
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::LoginReward::Error::FAlreadyReceivedError::Class))
{
// You have already received today's login bonus.
}
return false;
}getBonusModel
Get a specific login bonus schedule
Retrieves the details of a single login bonus model by name. Use this to display the detail screen for a specific bonus schedule — for example, showing all 7 days of rewards with checkmarks on the days the player has already claimed.
The returned model includes the full reward list, bonus mode, repeat settings, and missed-bonus recovery configuration. Combine this with GetReceiveStatus to know which days the player has already received and which are still available.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| bonusModelName | string | ✓ | ~ 128 chars | Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzBonusModel | Login Bonus Model |
Implementation Example
var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).BonusModel(
bonusModelName: "bonus-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).BonusModel(
bonusModelName: "bonus-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->LoginReward->Namespace(
"namespace-0001" // namespaceName
)->BonusModel(
"bonus-0001" // bonusModelName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).BonusModel(
bonusModelName: "bonus-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).BonusModel(
bonusModelName: "bonus-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->LoginReward->Namespace(
"namespace-0001" // namespaceName
)->BonusModel(
"bonus-0001" // bonusModelName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::LoginReward::Model::FBonusModel> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listBonusModels
Get a list of all login bonus schedules
Retrieves all login bonus models configured in the namespace. Each model defines a reward schedule — what the player receives on Day 1, Day 2, Day 3, and so on.
Use this to build a login bonus overview screen that shows all available bonus schedules. For example, your game might have a “7-Day Newcomer Bonus” and a “Monthly Login Bonus” running at the same time — this API returns both.
The returned models include the bonus mode (Schedule or Streaming), the list of daily rewards, whether repeat is enabled, and whether missed-bonus recovery is available.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<EzBonusModel> | List of Login Bonus Models |
Implementation Example
var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.BonusModelsAsync(
).ToListAsync(); var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.BonusModels(
);
List<EzBonusModel> items = new List<EzBonusModel>();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
} const auto Domain = Gs2->LoginReward->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->BonusModels(
);
TArray<Gs2::UE5::LoginReward::Model::FEzBonusModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeBonusModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeBonusModels(callbackId); var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeBonusModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeBonusModels(callbackId); const auto Domain = Gs2->LoginReward->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeBonusModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeBonusModels(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getReceiveStatus
Get the player’s login bonus progress for a specific bonus schedule
Retrieves the receive status for a single login bonus model. The status includes a list of boolean values (receivedSteps) showing which days have been claimed — for example, [true, true, false, true, false, false, false] means “Day 1 and 2 claimed, Day 3 missed, Day 4 claimed, Day 5-7 not yet reached”.
Use this together with GetBonusModel to build a detailed login bonus screen that shows each day’s reward alongside its claimed/unclaimed status.
The response also includes the bonus model details, so you can display the reward information and receive status in a single API call.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzReceiveStatus | ReceiveStatus |
| bonusModel | EzBonusModel | Login Bonus Model |
Implementation Example
var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).ReceiveStatus(
bonusModelName: "bonus-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).ReceiveStatus(
bonusModelName: "bonus-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->LoginReward->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->ReceiveStatus(
"bonus-0001" // bonusModelName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).ReceiveStatus(
bonusModelName: "bonus-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).ReceiveStatus(
bonusModelName: "bonus-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->LoginReward->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->ReceiveStatus(
"bonus-0001" // bonusModelName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::LoginReward::Model::FReceiveStatus> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listReceiveStatuss
Get the player’s login bonus progress for all bonus schedules
Retrieves the receive status for every login bonus model the player has interacted with. Each status tells you which days the player has already claimed and which are still available.
Use this to build a login bonus overview screen — for example, showing “7-Day Newcomer Bonus: 4/7 claimed” and “Monthly Bonus: 12/30 claimed” with progress indicators.
This is especially useful at game startup to check if there are any unclaimed bonuses to prompt the player.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| items | List<EzReceiveStatus> | List of ReceiveStatuses |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.ReceiveStatusesAsync(
).ToListAsync(); var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.ReceiveStatuses(
);
List<EzReceiveStatus> items = new List<EzReceiveStatus>();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
} const auto Domain = Gs2->LoginReward->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->ReceiveStatuses(
);
TArray<Gs2::UE5::LoginReward::Model::FEzReceiveStatusPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeReceiveStatuses(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeReceiveStatuses(callbackId); var domain = gs2.LoginReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeReceiveStatuses(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeReceiveStatuses(callbackId); const auto Domain = Gs2->LoginReward->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// Start event handling
const auto CallbackId = Domain->SubscribeReceiveStatuses(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeReceiveStatuses(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.