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
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.Model();
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.Model();
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.
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.
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? |
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
}
// 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.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;
}
// 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->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.Model();
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;
});