API Reference of GS2-Showcase SDK for Game Engine
Model
EzSalesItem
Product
Set the price required to purchase the product and the reward earned for the purchase of the product.
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
name | string | ✓ | ~ 128 chars | Product Name | |
metadata | string | ~ 2048 chars | metadata | ||
verifyActions | List<EzVerifyAction> | ~ 10 items | List of Verify Action | ||
consumeActions | List<EzConsumeAction> | ~ 10 items | List of Consumption Action | ||
acquireActions | List<EzAcquireAction> | ✓ | 1 ~ 100 items | List of Acquire Action |
EzSalesItemGroup
Product Group
A product group is an entity for display on a showcase. The first product that is determined to be available for purchase is actually displayed on the shelves. This can be used for products that are discounted only for the first time, or for a system in which the contents of products change depending on the number of times they are purchased, such as a step-up gacha.
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
name | string | ✓ | ~ 128 chars | Product Group Name | |
metadata | string | ~ 2048 chars | metadata | ||
salesItems | List<EzSalesItem> | ✓ | 2 ~ 10 items | Products to be included in the product group |
EzShowcase
Showcase
The sales period can be set for the display shelf.
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
name | string | ✓ | ~ 128 chars | Showcase Name | |
metadata | string | ~ 2048 chars | metadata | ||
displayItems | List<EzDisplayItem> | ✓ | 1 ~ 1000 items | List of Products on display |
EzDisplayItem
Displayed Item
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
displayItemId | string | ✓ | UUID | ~ 128 chars | Displayed Item ID |
type | enum { “salesItem”, “salesItemGroup” } | ✓ | ~ 128 chars | Type | |
salesItem | EzSalesItem | {type} == “salesItem” | Products to be displayed | ||
salesItemGroup | EzSalesItemGroup | {type} == “salesItemGroup” | Product group to be displayed |
Enumeration type definition to specify as type
Enumerator String Definition | Description |
---|---|
salesItem | Product |
salesItemGroup | Product Group |
EzRandomDisplayItem
Random displayable items on the Random Showcase
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
name | string | ✓ | UUID | ~ 128 chars | Random Displayed Item ID |
metadata | string | ~ 2048 chars | metadata | ||
verifyActions | List<EzVerifyAction> | ~ 10 items | List of Verify Action | ||
consumeActions | List<EzConsumeAction> | ~ 10 items | List of Consume Action | ||
acquireActions | List<EzAcquireAction> | ✓ | 1 ~ 100 items | List of Acquire Action | |
currentPurchaseCount | int | ✓ | 1 ~ 2147483646 | Current purchase count | |
maximumPurchaseCount | int | ✓ | 1 ~ 2147483646 | Maximum purchase count |
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
buy
Buy Product
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
showcaseName | string | ✓ | ~ 128 chars | Showcase Name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
displayItemId | string | ✓ | UUID | ~ 128 chars | Displayed Item ID |
quantity | int | ✓ | 1 | 1 ~ 1000 | Purchase Quantity |
config | List<EzConfig> | [] | ~ 32 items | Set values to be applied to transaction variables |
Result
Type | Description | |
---|---|---|
item | EzSalesItem | Product |
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? |
Implementation Example
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Showcase(
showcaseName: "showcase-0001"
).DisplayItem(
displayItemId: "display-item-0001"
);
var result = await domain.BuyAsync(
quantity: null,
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.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Showcase(
showcaseName: "showcase-0001"
).DisplayItem(
displayItemId: "display-item-0001"
);
var future = domain.BuyFuture(
quantity: null,
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->Showcase->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Showcase(
"showcase-0001" // showcaseName
)->DisplayItem(
"display-item-0001" // displayItemId
);
const auto Future = Domain->Buy(
// quantity
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
getShowcase
Retrieve showcase
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
showcaseName | string | ✓ | ~ 128 chars | Showcase Name |
Result
Type | Description | |
---|---|---|
item | EzShowcase | Showcase |
Implementation Example
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Showcase(
showcaseName: "showcase-0001"
);
var item = await domain.ModelAsync();
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Showcase(
showcaseName: "showcase-0001"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Showcase->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Showcase(
"showcase-0001" // showcaseName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
Value change event handling
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Showcase(
showcaseName: "showcase-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.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Showcase(
showcaseName: "showcase-0001"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Showcase->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Showcase(
"showcase-0001" // showcaseName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Showcase::Model::FShowcase> 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.
getRandomShowcaseDisplayItem
Get random showcase display item
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
showcaseName | string | ✓ | ~ 128 chars | Random Showcase Name | |
displayItemName | string | ✓ | UUID | ~ 128 chars | Random Displayed Item ID |
Result
Type | Description | |
---|---|---|
item | EzRandomDisplayItem | Displayed item |
Implementation Example
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RandomShowcase(
showcaseName: "showcase-0001"
).RandomDisplayItem(
displayItemName: "display-item-0001"
);
var item = await domain.ModelAsync();
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RandomShowcase(
showcaseName: "showcase-0001"
).RandomDisplayItem(
displayItemName: "display-item-0001"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Showcase->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->RandomShowcase(
"showcase-0001" // showcaseName
)->RandomDisplayItem(
"display-item-0001" // displayItemName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
Value change event handling
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RandomShowcase(
showcaseName: "showcase-0001"
).RandomDisplayItem(
displayItemName: "display-item-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.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RandomShowcase(
showcaseName: "showcase-0001"
).RandomDisplayItem(
displayItemName: "display-item-0001"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Showcase->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->RandomShowcase(
"showcase-0001" // showcaseName
)->RandomDisplayItem(
"display-item-0001" // displayItemName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Showcase::Model::FRandomDisplayItem> 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.
listRandomShowcaseDisplayItems
Retrieve random showcase display items
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
showcaseName | string | ✓ | ~ 128 chars | Random Showcase Name |
Result
Type | Description | |
---|---|---|
items | List<EzRandomDisplayItem> | Displayed items |
Implementation Example
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RandomShowcase(
showcaseName: "showcase-0001"
);
var items = await domain.RandomDisplayItemsAsync(
).ToListAsync();
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RandomShowcase(
showcaseName: "showcase-0001"
);
var it = domain.RandomDisplayItems(
);
List<EzRandomDisplayItem> items = new List<EzRandomDisplayItem>();
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->Showcase->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->RandomShowcase(
"showcase-0001" // showcaseName
);
const auto It = Domain->RandomDisplayItems(
);
TArray<Gs2::UE5::Showcase::Model::FEzRandomDisplayItemPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
Value change event handling
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RandomShowcase(
showcaseName: "showcase-0001"
);
// Start event handling
var callbackId = domain.SubscribeRandomDisplayItems(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeRandomDisplayItems(callbackId);
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RandomShowcase(
showcaseName: "showcase-0001"
);
var it = domain.RandomDisplayItems(
);
List<EzRandomDisplayItem> items = new List<EzRandomDisplayItem>();
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->Showcase->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->RandomShowcase(
"showcase-0001" // showcaseName
);
// Start event handling
const auto CallbackId = Domain->SubscribeRandomDisplayItems(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeRandomDisplayItems(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.
randomShowcaseBuy
Buy Product from random showcase
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace name | |
showcaseName | string | ✓ | ~ 128 chars | Random Showcase Name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
displayItemName | string | ✓ | UUID | ~ 128 chars | Random Displayed Item ID |
quantity | int | ✓ | 1 | 1 ~ 1000 | Purchase Quantity |
config | List<EzConfig> | [] | ~ 32 items | Set values to be applied to transaction variables |
Result
Type | Description | |
---|---|---|
item | EzRandomDisplayItem | Displayed item |
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? |
Implementation Example
var domain = gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RandomShowcase(
showcaseName: "showcase-0001"
).RandomDisplayItem(
displayItemName: "display-item-0001"
);
var result = await domain.RandomShowcaseBuyAsync(
quantity: 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.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).RandomShowcase(
showcaseName: "showcase-0001"
).RandomDisplayItem(
displayItemName: "display-item-0001"
);
var future = domain.RandomShowcaseBuyFuture(
quantity: 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->Showcase->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->RandomShowcase(
"showcase-0001" // showcaseName
)->RandomDisplayItem(
"display-item-0001" // displayItemName
);
const auto Future = Domain->RandomShowcaseBuy(
1 // quantity
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}