API Reference of GS2-Exchange SDK for Game Engine

Model

EzRateModel

Exchange Rate Model

The exchange rate is an entity that defines the rate used to exchange resources for resources.

In addition to the rate at which a resource can be exchanged immediately, a rate can also be set at which a resource can be exchanged after a certain amount of time in real time has elapsed. Exchange rates that require an elapse of time in real time can further define the resources required to perform an immediate exchange.

	Type	Require	Default	Limitation	Description
name	string	✓		~ 128 chars	Exchange Rate Name
metadata	string			~ 2048 chars	metadata
timingType	enum [‘immediate’, ‘await’]	✓	“immediate”	~ 128 chars	Type of exchange
lockTime	int	{timingType} == “await”		~ 525600	Waiting time (minutes) from the execution of the exchange until the reward is actually received
consumeActions	List<EzConsumeAction>		[]		List of Consumption Action
acquireActions	List<EzAcquireAction>		[]		List of Acquire Action

EzIncrementalRateModel

Cost increase type exchange rate model

Normal exchange rates always provide exchanges at a constant rate. With incremental exchange rates, you can define a rate that increases in cost as the number of exchanges increases. For example, the first exchange can be exchanged at a rate of 1:1, but the second exchange can be exchanged at a rate of 2:1. By defining such a rate, you can increase the value of the resources obtained by the player as the game progresses.

The number of exchanges can be reset by the passage of real time. This is useful for resetting the number of exchanges on a daily or weekly basis.

	Type	Require	Default	Limitation	Description
name	string	✓		~ 128 chars	Cost Increase Type Exchange Rate Name
metadata	string			~ 2048 chars	metadata
calculateType	enum [’linear’, ‘power’, ‘gs2_script’]	✓		~ 128 chars	Calculation method for cost increase amount
consumeAction	EzConsumeAction	✓			Consumption Action (Quantity/Value is overwritten so no setting is required)
baseValue	long	{calculateType} == “linear”		~ 9223372036854775805	Base Value
coefficientValue	long	{calculateType} in [“linear”, “power”]		~ 9223372036854775805	Coefficient Value”
exchangeCountId	string	✓		~ 1024 chars	GRN of GS2-Limit model that manages the number of exchanges
acquireActions	List<EzAcquireAction>		[]		List of Acquire Action

EzAwait

Standby for exchange

An entity for which the time lapse of real time represents the execution state of the exchange process for exchange conditions.

	Type	Require	Default	Limitation	Description
userId	string	✓		~ 128 chars	User Id
rateName	string	✓		~ 128 chars	Exchange rate name
name	string	✓	UUID	~ 36 chars	Exchange standby name
exchangedAt	long	✓			Datetime of creation

EzConfig

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

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

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

Methods

acquire

Get rewarded for waiting for exchange

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
awaitName	string	✓	UUID	~ 36 chars	Exchange standby name

Result

	Type	Description
item	EzAwait	Standby for exchange
transactionId	string	Transaction ID of the stamp sheet issued
stampSheet	string	Stamp sheet used to execute the reward acquisition process
stampSheetEncryptionKeyId	string	Cryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheet	bool	Is stamp sheet auto-execution enabled?

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var result = await domain.AcquireAsync(
    );
    // 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.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var future = domain.Acquire(
    );
    yield return future;
    if (future.Error != null)
    {
        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->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Await(
        "await-0001" // awaitName
    );
    const auto Future = Domain->Acquire(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

deleteAwait

Get exchange standby information

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
awaitName	string	✓	UUID	~ 36 chars	Exchange standby name

Result

	Type	Description
item	EzAwait	Standby for exchange

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var result = await domain.DeleteAwaitAsync(
    );

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var future = domain.DeleteAwait(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Await(
        "await-0001" // awaitName
    );
    const auto Future = Domain->DeleteAwait(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

getAwait

Get exchange standby information

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
awaitName	string	✓	UUID	~ 36 chars	Exchange standby name

Result

	Type	Description
item	EzAwait	Standby for exchange

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Await(
        "await-0001" // awaitName
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

listAwaits

Get list of exchange standby information

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
rateName	string		~ 128 chars	Exchange rate name
accessToken	string	✓	~ 128 chars	User Id
pageToken	string		~ 1024 chars	Token specifying the position from which to start acquiring data

Result

	Type	Description
items	List<EzAwait>	List of Standby for exchange
nextPageToken	string	Page token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.AwaitsAsync(
    ).ToListAsync();

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Awaits(
    );
    List<EzAwait> items = new List<EzAwait>();
    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->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->Awaits( // rateName
    );
    for (auto Item : *It)
    {

    }

skip

Skip the exchange wait at a price.

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
awaitName	string	✓	UUID	~ 36 chars	Exchange standby name

Result

	Type	Description
item	EzAwait	Standby for exchange
transactionId	string	Transaction ID of the stamp sheet issued
stampSheet	string	Stamp sheet used to execute the reward acquisition process
stampSheetEncryptionKeyId	string	Cryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheet	bool	Is stamp sheet auto-execution enabled?

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var result = await domain.SkipAsync(
    );
    // 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.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Await(
        awaitName: "await-0001"
    );
    var future = domain.Skip(
    );
    yield return future;
    if (future.Error != null)
    {
        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->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Await(
        "await-0001" // awaitName
    );
    const auto Future = Domain->Skip(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

getRateModel

Get exchange rate model information

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
rateName	string	✓		~ 128 chars	Exchange Rate Name

Result

	Type	Description
item	EzRateModel	Exchange rate model

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).RateModel(
        rateName: "character-level"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).RateModel(
        rateName: "character-level"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->RateModel(
        "character-level" // rateName
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

listRateModels

Get list of exchange rate model information

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name

Result

	Type	Description
items	List<EzRateModel>	List of exchange rate models

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.RateModelsAsync(
    ).ToListAsync();

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.RateModels(
    );
    List<EzRateModel> items = new List<EzRateModel>();
    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->Exchange->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->RateModels(
    );
    for (auto Item : *It)
    {

    }

getIncrementalRateModel

Get exchange rate model information

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
rateName	string	✓		~ 128 chars	Cost Increase Type Exchange Rate Name

Result

	Type	Description
item	EzIncrementalRateModel	Cost increase type cost increase type exchange rate model

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).IncrementalRateModel(
        rateName: "character-level"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).IncrementalRateModel(
        rateName: "character-level"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->IncrementalRateModel(
        "character-level" // rateName
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

listIncrementalRateModels

Get list of exchange rate model information

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name

Result

	Type	Description
items	List<EzIncrementalRateModel>	List of cost increase type exchange rate models

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.IncrementalRateModelsAsync(
    ).ToListAsync();

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.IncrementalRateModels(
    );
    List<EzIncrementalRateModel> items = new List<EzIncrementalRateModel>();
    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->Exchange->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->IncrementalRateModels(
    );
    for (auto Item : *It)
    {

    }

exchange

Perform exchange

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
rateName	string	✓		~ 128 chars	Exchange Rate Name
accessToken	string	✓		~ 128 chars	User Id
count	int	✓		1 ~ 1073741821	Number of lots to be exchanged
config	List<EzConfig>		[]		Set values to be applied to stamp sheet variables

Result

	Type	Description
item	EzRateModel	Exchange rate model
transactionId	string	Transaction ID of the stamp sheet issued
stampSheet	string	Stamp sheets used to execute the exchange process
stampSheetEncryptionKeyId	string	Cryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheet	bool	Is stamp sheet auto-execution enabled?

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Exchange(
    );
    var result = await domain.ExchangeAsync(
        rateName: "rate-0001",
        count: 1,
        config: null
    );
    // 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.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Exchange(
    );
    var future = domain.Exchange(
        rateName: "rate-0001",
        count: 1,
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        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->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Exchange(
    );
    const auto Future = Domain->Exchange(
        "rate-0001",
        1,
        nullptr // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

incrementalExchange

Perform cost increase type exchange

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
rateName	string	✓		~ 128 chars	Exchange Rate Name
accessToken	string	✓		~ 128 chars	User Id
count	int	✓		1 ~ 1073741821	Number of lots to be exchanged
config	List<EzConfig>		[]		Set values to be applied to stamp sheet variables

Result

	Type	Description
item	EzIncrementalRateModel	Cost increase type exchange rate model
transactionId	string	Transaction ID of the stamp sheet issued
stampSheet	string	Stamp sheets used to execute the exchange process
stampSheetEncryptionKeyId	string	Cryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheet	bool	Is stamp sheet auto-execution enabled?

Implementation Example

    var domain = gs2.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Exchange(
    );
    var result = await domain.IncrementalExchangeAsync(
        rateName: "rate-0001",
        count: 1,
        config: null
    );
    // 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.Exchange.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Exchange(
    );
    var future = domain.IncrementalExchange(
        rateName: "rate-0001",
        count: 1,
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        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->Exchange->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Exchange(
    );
    const auto Future = Domain->IncrementalExchange(
        "rate-0001",
        1,
        nullptr // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }