API Reference of GS2-Inbox SDK for Game Engine

Model

EzMessage

Message

Message data delivered to a message box prepared for each game player.

Messages have an open state, and you can set an acquisition action to be executed when opened. Messages can be set to expire, and messages that expire are automatically deleted regardless of whether they are unread or read after opening. Messages will be deleted even if you have not received the attached reward.

	Type	Require	Default	Limitation	Description
messageId	string	✓		~ 1024 chars	Message GRN
name	string	✓	UUID	~ 36 chars	Message Name
metadata	string	✓		~ 4096 chars	Metadata corresponding to the content of the message
isRead	bool	✓	false		Read
readAcquireActions	List<EzAcquireAction>		[]	~ 100 items	Obtain actions to be performed upon opening
receivedAt	long	✓	Now		Datetime of creation (Unix time unit:milliseconds)
readAt	long	✓	0		Read date and time (Unix time unit:milliseconds)
expiresAt	long				Datetime of ttl (Unix time unit:milliseconds)

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

EzAcquireAction

Acquire Action

	Type	Require	Default	Limitation	Description
action	enum { "Gs2AdReward:AcquirePointByUserId", "Gs2Dictionary:AddEntriesByUserId", "Gs2Enchant:ReDrawBalanceParameterStatusByUserId", "Gs2Enchant:SetBalanceParameterStatusByUserId", "Gs2Enchant:ReDrawRarityParameterStatusByUserId", "Gs2Enchant:AddRarityParameterStatusByUserId", "Gs2Enchant:SetRarityParameterStatusByUserId", "Gs2Enhance:DirectEnhanceByUserId", "Gs2Enhance:UnleashByUserId", "Gs2Enhance:CreateProgressByUserId", "Gs2Exchange:ExchangeByUserId", "Gs2Exchange:IncrementalExchangeByUserId", "Gs2Exchange:CreateAwaitByUserId", "Gs2Exchange:AcquireForceByUserId", "Gs2Exchange:SkipByUserId", "Gs2Experience:AddExperienceByUserId", "Gs2Experience:SetExperienceByUserId", "Gs2Experience:AddRankCapByUserId", "Gs2Experience:SetRankCapByUserId", "Gs2Experience:MultiplyAcquireActionsByUserId", "Gs2Formation:AddMoldCapacityByUserId", "Gs2Formation:SetMoldCapacityByUserId", "Gs2Formation:AcquireActionsToFormProperties", "Gs2Formation:SetFormByUserId", "Gs2Formation:AcquireActionsToPropertyFormProperties", "Gs2Friend:UpdateProfileByUserId", "Gs2Grade:AddGradeByUserId", "Gs2Grade:ApplyRankCapByUserId", "Gs2Grade:MultiplyAcquireActionsByUserId", "Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName", "Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName", "Gs2Idle:IncreaseMaximumIdleMinutesByUserId", "Gs2Idle:SetMaximumIdleMinutesByUserId", "Gs2Idle:ReceiveByUserId", "Gs2Inbox:SendMessageByUserId", "Gs2Inventory:AddCapacityByUserId", "Gs2Inventory:SetCapacityByUserId", "Gs2Inventory:AcquireItemSetByUserId", "Gs2Inventory:AcquireItemSetWithGradeByUserId", "Gs2Inventory:AddReferenceOfByUserId", "Gs2Inventory:DeleteReferenceOfByUserId", "Gs2Inventory:AcquireSimpleItemsByUserId", "Gs2Inventory:SetSimpleItemsByUserId", "Gs2Inventory:AcquireBigItemByUserId", "Gs2Inventory:SetBigItemByUserId", "Gs2JobQueue:PushByUserId", "Gs2Limit:CountDownByUserId", "Gs2Limit:DeleteCounterByUserId", "Gs2LoginReward:DeleteReceiveStatusByUserId", "Gs2LoginReward:UnmarkReceivedByUserId", "Gs2Lottery:DrawByUserId", "Gs2Lottery:ResetBoxByUserId", "Gs2Mission:RevertReceiveByUserId", "Gs2Mission:IncreaseCounterByUserId", "Gs2Mission:SetCounterByUserId", "Gs2Money:DepositByUserId", "Gs2Money:RevertRecordReceipt", "Gs2Money2:DepositByUserId", "Gs2Quest:CreateProgressByUserId", "Gs2Schedule:TriggerByUserId", "Gs2Script:InvokeScript", "Gs2SerialKey:RevertUseByUserId", "Gs2SerialKey:IssueOnce", "Gs2Showcase:DecrementPurchaseCountByUserId", "Gs2Showcase:ForceReDrawByUserId", "Gs2SkillTree:MarkReleaseByUserId", "Gs2Stamina:RecoverStaminaByUserId", "Gs2Stamina:RaiseMaxValueByUserId", "Gs2Stamina:SetMaxValueByUserId", "Gs2Stamina:SetRecoverIntervalByUserId", "Gs2Stamina:SetRecoverValueByUserId", "Gs2StateMachine:StartStateMachineByUserId", }	✓		~ 128 chars	Types of actions to be performed in the acquire action
request	string	✓		~ 1048576 chars	JSON of request

EzVerifyActionResult

Verify action execution result

	Type	Require	Limitation	Description
action	enum { }	✓	~ 128 chars	Types of actions to be performed in the verify task
verifyRequest	string	✓	~ 1048576 chars	JSON of request
statusCode	int		~ 999	Status code
verifyResult	string		~ 1048576 chars	Result payload

Enumeration type definition to specify as action

Enumerator String Definition	Description

EzConsumeActionResult

Consume action execution result

	Type	Require	Limitation	Description
action	enum { }	✓	~ 128 chars	Types of actions to be performed in the consume action
consumeRequest	string	✓	~ 1048576 chars	JSON of request
statusCode	int		~ 999	Status code
consumeResult	string		~ 1048576 chars	Result payload

Enumeration type definition to specify as action

Enumerator String Definition	Description

EzAcquireActionResult

Acquire action execution result

	Type	Require	Limitation	Description
action	enum { }	✓	~ 128 chars	Types of actions to be performed in the acquire action
acquireRequest	string	✓	~ 1048576 chars	JSON of request
statusCode	int		~ 999	Status code
acquireResult	string		~ 1048576 chars	Result payload

Enumeration type definition to specify as action

Enumerator String Definition	Description

EzTransactionResult

Transaction execution results

Transaction execution results executed using server-side transaction auto-execution functionality

	Type	Require	Limitation	Description
transactionId	string	✓	36 ~ 36 chars	Transaction ID
verifyResults	List<EzVerifyActionResult>		~ 10 items	List of verify action execution results
consumeResults	List<EzConsumeActionResult>		~ 10 items	List of consume action execution results
acquireResults	List<EzAcquireActionResult>		~ 100 items	List of acquire action execution results

Methods

delete

Deleting a message

If you do not have the option in your gift box settings to automatically delete messages when they are opened, you must use this API to explicitly delete messages.

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
messageName	string	✓	UUID	~ 36 chars	Message Name

Result

	Type	Description
item	EzMessage	Deleted Message

Implementation Example

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var result = await domain.DeleteAsync(
    );

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var future = domain.DeleteFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Message(
        "message-0001" // messageName
    );
    const auto Future = Domain->Delete(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

get

Get Message

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
messageName	string	✓	UUID	~ 36 chars	Message Name
accessToken	string	✓		~ 128 chars	User Id

Result

	Type	Description
item	EzMessage	Message

Implementation Example

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Message(
        "message-0001" // messageName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

Value change event handling

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-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.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Message(
        "message-0001" // messageName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Inbox::Model::FMessage> 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.

list

Get list of messages received in the gift box

Messages can be retrieved in order from the most recent message.

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
isRead	bool				Read
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int	✓	30	1 ~ 1000	Number of data acquired

Result

	Type	Description
items	List<EzMessage>	List of Message
nextPageToken	string	Page token to retrieve the rest of the listing

Implementation Example

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

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Messages(
    );
    List<EzMessage> items = new List<EzMessage>();
    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->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Messages(
    );
    TArray<Gs2::UE5::Inbox::Model::FEzMessagePtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

Value change event handling

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeMessages(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeMessages(callbackId);

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Messages(
    );
    List<EzMessage> items = new List<EzMessage>();
    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->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeMessages(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeMessages(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.

read

Read the message

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
messageName	string	✓	UUID	~ 36 chars	Message Name
accessToken	string	✓		~ 128 chars	User Id

Result

	Type	Description
item	EzMessage	Message
transactionId	string	Issed transaction ID
stampSheet	string	Stamp sheet
stampSheetEncryptionKeyId	string	Cryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheet	bool	Is transaction auto-execution enabled?
atomicCommit	bool	Transaction to commit 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
MessageExpiredException	NotFoundException	Message has expired

Implementation Example

try {
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var result = await domain.ReadAsync(
    );
} catch(Gs2.Gs2Inbox.Exception.MessageExpired e) {
    // Message has expired
}
    // 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.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var future = domain.ReadFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Inbox.Exception.MessageExpiredException)
        {
            // Message has expired
        }
        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->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Message(
        "message-0001" // messageName
    );
    const auto Future = Domain->Read(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Inbox::Error::FMessageExpiredError::Class))
        {
            // Message has expired
        }
        return false;
    }

receiveGlobalMessage

Receive global messages

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 128 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id

Result

	Type	Description
item	List<EzMessage>	List of received messages

Implementation Example

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.ReceiveGlobalMessageAsync(
    );
    var item = await result.ModelAsync();

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.ReceiveGlobalMessageFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->ReceiveGlobalMessage(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

Event Handler

OnReceiveNotification

Notification used when a message is received

Name	Type	Description
namespaceName	string	Namespace name
userId	string	User Id
messageName	string	Message Name

Implementation Example

    gs2.Inbox.OnReceiveNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var messageName = notification.MessageName;
    };

    gs2.Inbox.OnReceiveNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var messageName = notification.MessageName;
    };

    Gs2->Inbox->OnReceiveNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto UserId = Notification->UserIdValue;
        const auto MessageName = Notification->MessageNameValue;
    });