API Reference of GS2-LoginReward SDK for Game Engine
Model
EzReceiveStatus
Receive status
This model holds the receive status of login bonuses.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name | ||
| receivedSteps | List<bool> | [] | 0 ~ 100 items | List of received flags | ||
| lastReceivedAt | long | Last received time |
EzBonusModel
Bonus Model
A 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 | Bonus Model Name | ||||||||
| metadata | string | ~ 2048 chars | Metadata | |||||||||
| mode | String Enum enum { “schedule”, “streaming” } | ✓ | ~ 128 chars | mode
| ||||||||
| periodEventId | string | ~ 1024 chars | GS2-Schedule Event GRN that represents the period during which to enable login bonuses | |||||||||
| resetHour | int | {periodEventId} == "" | ✓* | 0 ~ 23 | Reset time of the receive flag (UTC) * required if periodEventId is “" | |||||||
| repeat | String Enum enum { “enabled”, “disabled” } | {mode} == “streaming” | ✓* | ~ 128 chars | Whether to repeat after reaching the end
* required if mode is “streaming” | |||||||
| rewards | List<EzReward> | 0 ~ 100 items | List of rewards | |||||||||
| missedReceiveRelief | String Enum enum { “enabled”, “disabled” } | ✓ | “disabled” | ~ 128 chars | Missed Rescue Function
| |||||||
| missedReceiveReliefVerifyActions | List<EzVerifyAction> | {missedReceiveRelief} == “enabled” | [] | 0 ~ 10 items | List of verify actions for missed receive relief * enabled if missedReceiveRelief is “enabled” | |||||||
| missedReceiveReliefConsumeActions | List<EzConsumeAction> | {missedReceiveRelief} == “enabled” | [] | 0 ~ 10 items | List of consume actions for missed receive relief * enabled if missedReceiveRelief is “enabled” |
EzReward
Reward
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| acquireActions | List<EzAcquireAction> | ✓ | 1 ~ 10 items | List of Acquire Action |
EzConfig
Configuration
Set values to be applied to transaction variables
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| key | string | ✓ | ~ 64 chars | Name | ||
| value | string | ~ 51200 chars | Value |
EzConsumeAction
Consume Action
EzVerifyAction
Verify Action
EzAcquireAction
Acquire Action
EzVerifyActionResult
Verify action execution result
EzConsumeActionResult
Consume action execution result
EzAcquireActionResult
Acquire action execution result
EzTransactionResult
Transaction execution results
Transaction execution results executed using server-side transaction auto-execution functionality
| 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 login bonus
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name | ||
| bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name | ||
| accessToken | string | ✓ | ~ 128 chars | Access token | ||
| stepNumber | int | 0 ~ 100 | Step number to receive. In streaming mode, this can be omitted | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | Set values to be applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzReceiveStatus | Receive status |
| bonusModel | EzBonusModel | Login Bonus Model |
| transactionId | string | Issed transaction ID |
| stampSheet | string | Stamp sheets used to execute the purchase process |
| 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.AlreadyReceived 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 login bonus
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name | ||
| bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name | ||
| accessToken | string | ✓ | ~ 128 chars | Access token | ||
| config | List<EzConfig> | [] | 0 ~ 32 items | Set values to be applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzReceiveStatus | Receive status |
| bonusModel | EzBonusModel | Login Bonus Model |
| transactionId | string | Issed transaction ID |
| stampSheet | string | Stamp sheets used to execute the purchase process |
| 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.AlreadyReceived 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 Login Bonus Model
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name | ||
| bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name |
Result
| Type | Description | |
|---|---|---|
| item | EzBonusModel | 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"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; 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 called when the value in the local cache that the SDK has is changed.
The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listBonusModels
Get list of login bonus models
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name |
Result
| Type | Description | |
|---|---|---|
| items | List<EzBonusModel> | List of 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"
);
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
);
// 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 called when the value in the local cache that the SDK has is changed.
The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getReceiveStatus
Get Receive Status
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name | ||
| bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name | ||
| accessToken | string | ✓ | ~ 128 chars | Access token |
Result
| Type | Description | |
|---|---|---|
| item | EzReceiveStatus | ReceiveStatus |
| bonusModel | EzBonusModel | 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"
);
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
);
// 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 called when the value in the local cache that the SDK has is changed.
The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listReceiveStatuss
Get list of Receive Statuses
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name | ||
| accessToken | string | ✓ | ~ 128 chars | Access token |
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
);
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
);
// 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 called when the value in the local cache that the SDK has is changed.
The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.