API Reference of GS2-LoginReward SDK for Game Engine
Model
EzReceiveStatus
Receive status
This model holds the receive status of login bonuses.
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name | |
receivedSteps | List<bool> | ~ 100 items | List of received flags | ||
lastReceivedAt | long | ✓ | 0 | Last received time (Unix time unit:milliseconds) |
EzBonusModel
Bonus Model Set the distribution schedule of login bonuses. There are two types of distribution schedules: “Schedule Mode” and “Streaming Mode”.
In Schedule Mode, the GS2-Schedule event is required, and the bonus is distributed based on the number of days elapsed since the start of the event. If you miss a shot in the middle, you will not receive the bonus for that shot.
In Streaming Mode, the rewards set for the bonus are distributed one by one from the beginning every day. In Streaming Mode, you can set it to repeat. In that case, if you reach the end of the stream, you will start distributing from the beginning again.
Both Schedule Mode and Streaming Mode have a rescue function for missed shots. By paying a certain cost, you can receive the bonus you missed. However, if the GS2-Schedule event is associated, you can only receive the bonus after the number of days elapsed since the start of the event. The missed capture function is not available in streaming mode and when repetition is enabled.
The maximum number of days of bonuses that can be set in both Scheduled and Streaming modes is 100 days.
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
name | string | ✓ | ~ 128 chars | Bonus Model Name | |
metadata | string | ~ 2048 chars | metadata | ||
mode | 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} == "" | ~ 23 | Reset time of the receive flag (UTC) | |
repeat | enum { “enabled”, “disabled” } | {mode} == “streaming” | ~ 128 chars | Reset time of the receive flag (UTC) | |
rewards | List<EzReward> | ~ 100 items | List of rewards | ||
missedReceiveRelief | enum { “enabled”, “disabled” } | ✓ | “disabled” | ~ 128 chars | Missed Rescue Function |
missedReceiveReliefVerifyActions | List<EzVerifyAction> | {missedReceiveRelief} == “enabled” | ~ 10 items | List of verify actions for missed receive relief | |
missedReceiveReliefConsumeActions | List<EzConsumeAction> | {missedReceiveRelief} == “enabled” | ~ 10 items | List of consume actions for missed receive relief |
Enumeration type definition to specify as mode
Enumerator String Definition | Description |
---|---|
schedule | Schedule Mode |
streaming | Streaming Mode |
Enumeration type definition to specify as repeat
Enumerator String Definition | Description |
---|---|
enabled | Enabled |
disabled | Disabled |
Enumeration type definition to specify as missedReceiveRelief
Enumerator String Definition | Description |
---|---|
enabled | Enabled |
disabled | Disabled |
EzReward
Reward
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
acquireActions | List<EzAcquireAction> | ✓ | 1 ~ 10 items | List of Acquire Action |
EzConfig
Configration
Set values to be applied to transaction variables
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
key | string | ✓ | ~ 64 chars | Name | |
value | string | ~ 51200 chars | Value |
EzConsumeAction
Consume Action
EzVerifyAction
Verify Action
EzAcquireAction
Acquire Action
Methods
missedReceive
Receive login bonus
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
stepNumber | int | ✓ | ~ 100 | Step number to receive | |
config | List<EzConfig> | [] | ~ 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 | Is transaction auto-execution enabled? |
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.
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// 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;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// 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 | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
config | List<EzConfig> | [] | ~ 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 | Is transaction auto-execution enabled? |
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.
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// 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;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// 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 | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name |
Result
Type | Description | |
---|---|---|
item | EzBonusModel | Bonus |
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.Model();
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.Model();
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 | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name |
Result
Type | Description | |
---|---|---|
items | List<EzBonusModel> | List of Bonuss |
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 | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
bonusModelName | string | ✓ | ~ 128 chars | Bonus Model Name | |
accessToken | string | ✓ | ~ 128 chars | User Id |
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.Model();
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.Model();
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 | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
accessToken | string | ✓ | ~ 128 chars | User Id |
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.