Manage inventory integration with AGS Commerce

Last updated on July 18, 2024

注記

The Inventory service is available upon request. To integrate this service into your environment, please open a request through the AccelByte Customer Support Portal.

Overview

The AccelByte Gaming Service (AGS) Inventory service allows you to use data from the Store and Entitlements service as the authoritative source for player-owned items. With this integration, Entitlements will be the primary data source for player-owned items, helping the Inventory service to avoid problems such as duplicate or conflicting actions on items, such as buying, consuming, discarding, trading, or gifting them.

Prerequisites

You must have access to the following:

• AGS Admin Portal
• AGS Inventory API documentation
• AGS Unreal or Unity SDK, including the permissions:
  • Client ID
  • Client Secret

Inventory and Commerce sync behavior

Supported item types

To ensure seamless integration between the Inventory and Commerce services, AGS supports synchronizing specific item types from Entitlements into Inventory. The supported item types are:

• In-game items
• Loot box
• Option box
• Bundle

注記

For bundle items, only in-game items, loot boxes, and option boxes can be synced from the bundle into player inventories; other item types from the bundle cannot be synced.

Supported items attributes

The Inventory service works as a decorator and relies on the AGS Store service to use defined item attributes. The supported attributes that can synced from Store to Inventory initially carry basic default value. Some of the attributes can later be modified from within Inventory. This approach ensures a smooth initial setup while allowing tailored item attributes customization in Inventory, enhancing flexibility and item-specific customization.

• For example, Item Name, Description, Image represent basic item information and cannot be changed specifically within Inventory. They will always follow the values set in the Store.
• On the other hand, other attributes such as Custom Attributes, Server Custom Attributes and Slot Used will serve as default values in Inventory but can be later updated or modified, specifically for individual items without impacting the default values set in the Store. For more information about this attribute, see Item custom attributes.

This approach ensures both consistency with default attributes configured in the AGS Store and flexibility customization within the Inventory service.

Platform-specific items

The Inventory service differentiates items originating from different platforms such as Xbox, PSN, Epic, Steam, etc. This impacts the service's behavior in the following ways:

• Inventory only allows the retrieval of items from their respective platforms (e.g., items that come from Steam can only be retrieved from Steam).
• Inventory supports storing items from either a single platform or multiple platforms within the same user inventory and calculates the capacity collectively across all platforms.
  • If you prefer to store items from a specific platform separately, you can create a dedicated inventory configuration for that respective platform (e.g., Steam Backpack).
  • Alternatively, if you prefer to store items from multiple platforms together, you can create a single inventory configuration for all items originating from different platforms (e.g., Backpack).

注記

Using a single inventory to store items from multiple platforms may fill up the Inventory due to the items primarily coming from one platform (e.g., Steam), potentially limiting the storage available for items from other platforms (e.g., Epic).

Supported actions

Action supported by both Inventory and Commerce hold significant effect over their interconnected operations. This means that action originating from either system can impact others. Let's explore the supported actions from both Inventory and Commerce, and how each system functionality and interaction.

Adding items

1. Purchasing items from Commerce. Items that players buy from Commerce will be synced to the player's inventory. If the player's inventory is full, the player can't purchase more items from Commerce.
2. Granting entitlements from other entitlement sources, such as items that are rewards from challenges, season passes, and other sources will be also synced to player's inventory.
3. Saving Commerce items directly from the Inventory service. The items will be reflected in the player's entitlements.

Consuming items

1. Consuming items from the player's inventory reduces the item useCount value for consumable items in player's entitlement.
2. Consuming items directly from the player's entitlements reduces the item's quantity in their inventory.
3. If the player's entitlement useCount reaches 0, the entitlement status is changed to "Consumed." Adding another similar item will create another new entitlement entry.
4. If the quantity of an item from a player's inventory reaches 0, the item is removed from the player's inventory and frees up inventory space.
5. Only items with their entitlement property set to Consumable can be consumed.
6. Durable items cannot be consumed; attempts will result in failure.

Deleting items and revoking entitlements

1. Deleting items from player's inventory revoke the related items from the player's entitlements.
2. Revoking a player's entitlement from a supported platform also removes the related items from the player's inventory.
3. Durable and consumable items can deleted or revoked.

Moving or transferring items

An item from a player's inventory can be split or partially transferred to a different inventory. This action

Splitting or partially transferring items from a player's inventory to a different inventory reduces the player's related entitlements and creates new entitlements.

備考

The current version of the Inventory service can only handle items from the OTHER source. It does not yet support processing items from Commerce, but enhancements are in progress to enable this functionality

Integrate Inventory with Entitlements

Integrating the Inventory service with Entitlements enables the auto-syncing of items from your published store into your preferred inventory configuration.

To integrate the Inventory service with Entitlements, follow these steps:

1. One the AGS Admin Portal sidebar, go to Progression & Inventory > Inventory > Integrations.
2. In the Ecommerce Integration Configuration section, click on the + Add Configuration button.
3. On the Ecommerce Integration Configuration window, do the following:
4. In Item Types, select the item types from your published store that you want to synchronize with your selected inventory.
5. In Target Inventory, select the inventory configuration you want to synchronize items from your published store into. For information about setting up inventory configurations, see Setting up inventory configurations.
6. Click Add to complete. The integration appears on the Ecommerce Integration Configuration page.
7. Activate the integration by switching on its ACTIVE toggle.

Manually sync item ownership from entitlement to players' inventory

AGS also supports manually syncing player inventories with entitlements to ensure data consistency This process allows you to initiate the sync operation as needed, guaranteeing that data remains up-to-date and identical across both systems.

Manual sync is best executed in the following scenarios:

• When you have been using Entitlements and plan to start syncing it with Inventory.
• When you have been using Inventory, disabled the integration with Commerce midway, and then re-enabled it. In this case, manually syncing ensures both sides are updated and synchronized.