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

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
missedReceiveReliefConsumeActions	List<EzConsumeAction>	{missedReceiveRelief} == “enabled”		~ 10 items	List of consumption actions for missed receive relief

EzReward

	Type	Require	Default	Limitation	Description
acquireActions	List<EzAcquireAction>	✓		1 ~ 10 items	List of Acquire Action

EzConfig

	Type	Require	Default	Limitation	Description
key	string	✓		~ 64 chars	Name
value	string			~ 51200 chars	Value

EzConsumeAction

	Type	Require	Default	Limitation	Description
action	enum []	✓		~ 128 chars	Types of actions to be performed in the stamp task
request	string	✓		~ 1048576 chars	JSON of the obtain request

EzAcquireAction

	Type	Require	Default	Limitation	Description
action	enum []	✓		~ 128 chars	Types of actions to be performed in the stamp sheet
request	string	✓		~ 1048576 chars	JSON of request

Methods

missedReceive

Receive login bonus

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 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 stamp sheet variables

Result

	Type	Description
item	EzReceiveStatus	Receive status
bonusModel	EzBonusModel	Login Bonus Model
transactionId	string	Transaction ID of the stamp sheet issued
stampSheet	string	Stamp sheets used to execute the purchase process
stampSheetEncryptionKeyId	string	Cryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheet	bool	Is stamp sheet 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(
        AccessToken
    )->Bonus(
    );
    const auto Future = Domain->MissedReceive(
        "bonus-0001",
        1,
        nullptr // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        if (Gs2::LoginReward::Error::FAlreadyReceivedError::TypeString == Task->GetTask().Error()->Type())
        {
            // You have already received today's login bonus.
        }
        return false;
    }

receive

Receive login bonus

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 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 stamp sheet variables

Result

	Type	Description
item	EzReceiveStatus	Receive status
bonusModel	EzBonusModel	Login Bonus Model
transactionId	string	Transaction ID of the stamp sheet issued
stampSheet	string	Stamp sheets used to execute the purchase process
stampSheetEncryptionKeyId	string	Cryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheet	bool	Is stamp sheet auto-execution enabled?

Error

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(
        AccessToken
    )->Bonus(
    );
    const auto Future = Domain->Receive(
        "bonus-0001",
        nullptr // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        if (Gs2::LoginReward::Error::FAlreadyReceivedError::TypeString == Task->GetTask().Error()->Type())
        {
            // You have already received today's login bonus.
        }
        return false;
    }

getBonusModel

Get Login Bonus Model

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 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	✓		~ 32 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(
    );
    for (auto Item : *It)
    {

    }

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.

Therefore, callbacks will not be invoked if the value is changed in any other way.

getReceiveStatus

Get Receive Status

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 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(
        AccessToken
    )->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(
        AccessToken
    )->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.

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	✓		~ 32 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(
        AccessToken
    );
    const auto It = Domain->ReceiveStatuses(
    );
    for (auto Item : *It)
    {

    }

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(
        AccessToken
    );
    
    // 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.

Therefore, callbacks will not be invoked if the value is changed in any other way.