Blog

Latest news and updates from the PlayFab developers

by BrendanVanous 2014-09-26

Gift-Giving, PlayFab Style

The holidays are still a ways out, but it's always a good time to give a gift to your players. With that in mind, here's a quick how-to on gifting a player within the PlayFab service; whether it's a reward for an in-game activity, tied to a holiday, a player-to-player gift, a celebration of the anniversary of your game's launch, or just because you feel like it. In general, gifts are implemented using "containers" (See the API documentation for Containers). A container is just like a bundle, except a container can live in the player's inventory unopened, whereas a bundle adds its contents to the inventory as soon as it is purchased.

Let's use the PlayFab AngryBots sample as the starting place. We already have defined a few things in the catalog for that title, including health and ammo. For this gift, we'll create a container with both of the catalog's health packs and an ammo pack. And since we're feeling especially generous, we'll include 1,000 units of our game's virtual currency. Using the UpdateCatalogItems API call, the call would look like this (note that for your own title, you need to make sure to use your Title ID for the endpoint, and add your Secret Key, since this is an Admin call):

POST /admin/UpdateCatalogItems HTTP/1.1
Host: [TitleID].playfabapi.com
Content-Type: application/json
X-SecretKey: [Your title's Secret Key]
{
  "CatalogVersion": "1",
  "Catalog": [
    {
      "ItemId": "Awesome_Gift",
      "CatalogVersion": "1",
      "Container": {
        "ItemContents": [
          "ammo_pack_1",
          "health_pack_1",
          "health_pack_2"
        ],
        "VirtualCurrencyContents": {
          "GC": 1000
        }
      },
      "Consumable": {
        "UsageCount": 1
      }
    }
  ]
}

 

Now, some things worth noting here are:

  • No cost has been defined. That's because we want this to be a gift, not something a player can purchase via real or virtual currency. With no cost defined any call to purchase the item, regardless of how that call is made, will fail.
  • There's also no key defined. This is also by design, in this case. Normally, a container would be defined with a key (KeyItemId, in the definition), which would be required to open it. Defining it without one means that no key item is needed. The container will open, and its contents be delivered to the player inventory, when the UnlockContainerItem call is made on it.
  • We've defined this container item as a consumable, having a single use. Whenever a container is opened, the container item and the key item used to open it will each be decremented by one, if they are consumables. As with other consumables, they will then be removed from the player's inventory when they hit zero uses. If either container or key is defined as non-consumable, they will remain in the player's inventory, so that they can be re-used whenever the player has both the container and the key. In this case, we wouldn't want the player to be able to re-use the container, as this is meant to be a one-time gift.

And with that, your gift is ready to be distributed far and wide, using the GrantItemsToUsers API call*. And since management of the inventory is taken care of on the backend, you know that users who receive the container won't be able to use any disconnect attacks or hacked clients to get more than you intended to give them. Of course, once you've sent out your gifts, it's important to make sure your players are aware of them. One approach to this would be to have a specific string that you always include as part of the name for your gifts (the ItemId), such as "Gift" in the example above. Then, when your players jump into your game, you can do a quick check for any goodies awaiting them, using the GetUserInventory API call. That way, if you find your key term, you'll know you have a nice surprise for them. Again, Containers without keys won't automatically open and deliver their contents to the user's inventory. So when you detect your gift, you'll want to present it to the user in some manner, so that he can open it (or save it for later). When he chooses to do so, you'll make a call to UnlockContainerItem, as mentioned above. This will open the container, decrement its counter (and remove it from inventory if that means it has zero uses left), and add the contents to the user's inventory. The data returned by UnlockContainerItem will have the complete list of items granted as a result, which you can then use to show the user what he received. Spread the joy with confidence, PlayFab style! 

*And remember - you can quickly and easily test out any of the Web APIs with your title, using a tool like Postman - have a look at our previous post for more info on this.