🎁Promo Items

Rewarding players with rewarding items

Like what you're seeing?

Support us as a GitHub Sponsor and get instant access to all our assets, exclusive tools and assets, escalated support and issue tracking and our gratitude. These articles are made possible by our GitHub Sponsors ... become a sponsor today!

Introduction

Steam Inventory has a concept of "Promo Items" These are items that can be given to players either on demand or when pre-defined conditions are met. Promo items are the only way to give users items in the game without the use of a trusted backend server.

Steam Inventory is about security first

You CANNOT give just any user, just any item, just anytime you want. Unless you use a Trusted Web Server with a publisher token to use the Steam Web API which is beyond the scope of Heathen's Steamworks asset which is a Unity asset, not a Web API integration.

The closest you can get to giving users rewards on demand such as for completing a quest or game session. This is to define Promo Items with suitable rules for your use case.

Why?

Because Steam needs to ensure that users cannot simply hack your game or manipulate the Steam API to generate items at will. The promo system lets you identify what items can be granted and what restrictions are applied to mitigate exploiters and cheaters.

All other items can only be generated by Steam through the Steam store or by your trusted web server through the Steam Web API with a publisher token.

The Exception to the rule is game developer grants Game Developers who are listed as developers on the app can use a special feature of Steam API to grant themselves any item at any time. This is for testing and cannot be used by any other user at any other time. Grant can be used on any item type and does not require the item to be a promo item.

What

What makes a Steam Inventory Item a Promo Time?

Steam Inventory Schema (Steamworks Documentation)

You really should read this closely

Any item with a "promo" rule defined is a promo item. for example

{
    "itemdefid" : 101,
    "type" : "item",
    "name" : "Example Promo Item",
    "promo" : "manual"
}

The JSON item definition listed above describes an item which is a promo item, that can be granted via a manual Add Promo Item call as a 1-time item drop.

How

How do you give the player the promo items?

With an item defined, you can simply call Add Promo Item, This can either be done from the Inventory API or from the Item Definition object itself.

Configuration

As with everything Steam Inventory this can get complex or be very simple depending on your requirements.

Note that items or bundles can be promo items, also note that bundles can contain generators and bundles themselves. So with a bit of nesting, you can create very complex probability-based loot pools that you can grant multiple times on complex rules as promo items.

Much more commonly though we define promo items as single item or bundle rewards for owning DLC, for having played some amount of time, for having earned some achievement or we provide them iterative such as once a week or similar.

Promo Rules

There are 4 types of rules and you can mix and match, except manual. Only manual rules can be repeated all other rules are one-time drops only. The manual rule is demonstrated in the example JSON above, in the What section.

App Rule

This is a rule that checks if a user owns a specific app it looks something like this

{
    "itemdefid" : 101,
    "type" : "item",
    "name" : "Example Promo Item",
    "promo" : "owns:480"
}

This indicates that the user must own app 480 ... which is a horrible rule because everyone owns app 480.

Achievement Rule

This is a rule that checks if a user has unlocked a given achievement based on achievement ID and looks like this

{
    "itemdefid" : 101,
    "type" : "item",
    "name" : "Example Promo Item",
    "promo" : "ach:myAchievementId"
}

This indicates that the user must have unlocked the achievement named myAchievementId in order for this rule to drop.

Play Time Rule

This is a rule that checks if a user has played a given amount of a given game. Note that a rule will never equate to true for apps the user has temporarily such as free weekends, borrowed, etc.

{
    "itemdefid" : 101,
    "type" : "item",
    "name" : "Example Promo Item",
    "promo" : "played:480/15"
}

This indicates that the user must have played app 480 for 15min or longer

Multiple Rules

You can and often would use multiple rules at once.

{
    "itemdefid" : 101,
    "type" : "item",
    "name" : "Example Promo Item",
    "promo" : "owns:480;played:510/30;ach:myAchievementId"
}

This indicates that the local user must

• Own App 480

• Have played 30 min or more of App 510

• Have unlocked the achievement myAchievementId for this game

Manual Promos

Manual ruled promo items are a lot more flexible and can be dropped for the player multiple times. These make manual promo rules the way to go for weekly rewards, game session rewards and so on.

{
    "itemdefid" : 101,
    "type" : "item",
    "name" : "Example Promo Item",
    "promo" : "manual",
    "drop_interval": 10080
}

This would indicate that the item can be dropped for the player once every 7 days e.g. a weekly reward.

You can use additional nodes such as drop window and drop max per window to fine tune how your drops work. You can find several examples from Valve at the link below

Steam Inventory Schema (Steamworks Documentation)