Unaffiliated

Home Documentation & Help
Steamworks Documentation
Steam Inventory Item Dynamic Properties
New to the Steam Inventory Service is the ability to store arbitrary string, integer, boolean, or float properties on any item instance.

These properties are similar to per item tags. However, unlike per item tags which are considered immutable, these properties are dynamic because they can be modified either through a secure Web API call or through the Steamworks API.

Also unlike item tags, dynamic item properties are cleared when an item is traded. Dynamic item properties are not currently visible when inspecting an item in a user's Steam Inventory or on the Steam Community Market.

Retrieving Item Properties


Dynamic item properties are automatically sent along with other item attributes to the Steam Client and can be retrieved by calling ISteamInventory::GetResultItemProperty with the property name dynamic_props. The provided buffer will be filled with the string representation of the JSON for all the dynamic properties for the item. It is up to your application to parse this string appropriately.

For any Web API calls that return items as JSON, the dynamic_props key will point to the full JSON object containing the dynamic item properties.

Modifying Item Properties


From one of your secure servers, you can modify items using the IInventoryService/ModifyItems Web API and your secure publisher key.

You can also modify item properties from the Steam Client via the Steamworks API and calls to ISteamInventory::StartUpdateProperties, ISteamInventory::RemoveProperty, ISteamInventory::SetProperty, and ISteamInventory::SubmitUpdateProperties. However, you will first need to white-list what properties can be set from the client on the Steam Inventory Service configuration page on the partner site. We recommend that you only white-list properties that you are fine with an untrusted client setting (i.e. the user can spoof messages to set the value to whatever they want).

Currently you can modify up to 100 items for a user in each call. This call is rate-limited on a per user basis, so you will want to batch up your modifications and send them at an appropriate time for your game. There is also a maximum of 1024 bytes of JSON per item at this time.

Applying Restrictions

As mentioned previously, you can white-list certain properties so they can be set from the client. But you can also further restrict what properties can be set by requiring the target item to have a specific tag_category:tag_value pair or for any tag_category value. Using these tag restrictions in combination with the client API, you can allow clients to set properties only on items where it makes sense (i.e. a hat would not keep track of the number of kills, but a rocket launcher can). These required tags can exist either on the item or its associated item definition.

Examples


Say you want to keep track of how many times a user has fired their rocket launcher. There are a couple of ways to do this, but regardless of which method you choose, you will want to batch up property modifications, as the calls to modify item properties are rate limited as mentioned above.

WebAPI

On your secure game server, you can accumulate that statistic and at the end of the game round or other appropriate time, you can POST the results to the IInventoryService/ModifyItems Web API using your secure publisher key.

Example form-data for the POST call:
appid: 480 key: "0123456789abcdeffedcba9876543210" input_json:{ "steamid" : "1234", "timestamp" : 1513274037, "updates" : [ { "itemid" : "1", "property_name" : "num_times_fired", "property_value_int" : 100 } ] }

Steamworks API

If you want to use the Steamworks API to modify item properties (again, inherently insecure), you will first need to add them to a white-list for your app.

Then, as with the above example, once the game round has ended or other appropriate time, you can start an update, set properties, and then submit the update to Steam.

SteamInventoryUpdateHandle_t updateHandle = SteamInventory()->StartUpdateProperties(); SteamInventory()->SetProperty( updateHandle, nItemID, "num_times_fired", nNumTimesFired ); SteamInventoryResult_t resultUpdate; SteamInventory()->SubmitUpdateProperties( updateHandle, &resultUpdate );

Then in your callback handler for SteamInventoryResultReady_t, you will get the results of the call to update those item properties.