API Reference of GS2-Showcase SDK for Game Engine
Model
EzShowcase
Showcase
Showcase can be used to define products for display.
Additionally, the sales period for products on Showcase can be set.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Showcase Name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| displayItems | List<EzDisplayItem> | ✓ | [] | 1 ~ 1000 items | List of Display Items | |
| salesPeriodEventId | string | ~ 1024 chars | GS2-Schedule event GRN with sales periods for Showcase |
EzDisplayItem
Displayed Item
| Type | Condition | Required | Default | Value Limits | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| displayItemId | string | ✓ | UUID | ~ 128 chars | Displayed Item ID Maintains a unique name for displayed products. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. | |||||||
| type | String Enum enum { “salesItem”, “salesItemGroup” } | ✓ | Type
| |||||||||
| salesItem | EzSalesItem | {type} == “salesItem” | ✓* | Sales Item * Required if type is “salesItem” | ||||||||
| salesItemGroup | EzSalesItemGroup | {type} == “salesItemGroup” | ✓* | Sales Item Group * Required if type is “salesItemGroup” |
EzRandomDisplayItem
Random Displayed Item on the Random Showcase
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | UUID | ~ 128 chars | Random Displayed Item Name Maintains a unique name for randomly displayed products. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. | |
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| verifyActions | List<EzVerifyAction> | [] | 0 ~ 10 items | List of Verify Action | ||
| consumeActions | List<EzConsumeAction> | [] | 0 ~ 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 |
EzSalesItem
Product
Set the price required to purchase the product and the reward earned for the purchase of the product.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Sales Item name Sales Item-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| verifyActions | List<EzVerifyAction> | [] | 0 ~ 10 items | List of Verify Action | ||
| consumeActions | List<EzConsumeAction> | [] | 0 ~ 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 | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Sales Item Group name Sales Item Group-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| salesItems | List<EzSalesItem> | ✓ | [] | 2 ~ 10 items | Products to be included in the product group |
EzConfig
Configuration
Set values to be applied to transaction variables
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| key | string | ✓ | ~ 64 chars | Name | ||
| value | string | ~ 51200 chars | Value |
EzConsumeAction
Consume Action
EzVerifyAction
Verify Action
EzAcquireAction
Acquire Action
EzVerifyActionResult
Verify action execution result
EzConsumeActionResult
Consume action execution result
EzAcquireActionResult
Acquire action execution result
EzTransactionResult
Transaction execution results
Transaction execution results executed using server-side transaction auto-execution functionality
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ | 36 ~ 36 chars | Transaction ID | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 10 items | List of verify action execution results | |||
| consumeResults | List<EzConsumeActionResult> | [] | 0 ~ 10 items | List of consume action execution results | ||
| acquireResults | List<EzAcquireActionResult> | [] | 0 ~ 100 items | List of acquire action execution results |
Methods
buy
Buy Product
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| showcaseName | string | ✓ | ~ 128 chars | Showcase Name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| displayItemId | string | ✓ | UUID | ~ 128 chars | Displayed Item ID Maintains a unique name for displayed products. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. | |
| quantity | int | ✓ | 1 | 1 ~ 1000 | Purchase Quantity | |
| config | List<EzConfig> | [] | 0 ~ 32 items | Set values to be applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzSalesItem | Product |
| transactionId | string | Issued 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 | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction execution result |
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
);
// 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;
}
// 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 | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| showcaseName | string | ✓ | ~ 128 chars | Showcase Name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
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.ModelFuture();
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"
);
// 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); 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.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getRandomShowcaseDisplayItem
Get random showcase display item
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| showcaseName | string | ✓ | ~ 128 chars | Random Showcase Name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| displayItemName | string | ✓ | UUID | ~ 128 chars | Random Displayed Item Name Maintains a unique name for randomly displayed products. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. |
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.ModelFuture();
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"
);
// 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); 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.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listRandomShowcaseDisplayItems
Get list of random showcase display items
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| showcaseName | string | ✓ | ~ 128 chars | Random Showcase Name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
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"
);
// Start event handling
var callbackId = domain.SubscribeRandomDisplayItems(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeRandomDisplayItems(callbackId); 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.
Therefore, callbacks will not be invoked if the value is changed in any other way.
randomShowcaseBuy
Buy Product from random showcase
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| showcaseName | string | ✓ | ~ 128 chars | Random Showcase Name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| displayItemName | string | ✓ | UUID | ~ 128 chars | Random Displayed Item Name Maintains a unique name for randomly displayed products. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. | |
| quantity | int | ✓ | 1 | 1 ~ 1000 | Purchase Quantity | |
| config | List<EzConfig> | [] | 0 ~ 32 items | Set values to be applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzRandomDisplayItem | Displayed item |
| transactionId | string | Issued 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 | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction execution result |
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
);
// 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;
}
// 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;
}