Blog

Latest news and updates from the PlayFab developers

by JamesGwertzman 2015-07-02

How to Use PlayFab's Content Management API

One of the biggest benefits to having a backend for your game is the ability to make content updates to the game without having to force your players to update the game itself. There are several backend services needed to make this happen, but the most basic is a mechanism for uploading files to the backend, then efficiently downloading those files to your players, typically through a content distribution network (CDN).

PlayFab recently added a set of content management features to our backend services API. This feature is not yet exposed in our Game Manager, but you don't need to wait for that to begin using these features today. This blog post will walk you through the steps of uploading a file to PlayFab, telling your game about the file, then downloading the file in your game.

Step 1: Uploading a File to PlayFab

There are two steps to uploading a file to PlayFab. First, you call the GetContentUploadUrl function, which lives in our Admin API. You pass in whatever identifier (the "key") you want to use to later retrieve the file, and you will get back an upload URL. Second, you use that upload URL to upload the file itself to PlayFab.

Simple, right? It is, but the actual details can be tricky. Here's a step-by-step guide.

Well image by Pepper Racoon/opengameart.org

1. Determine what file you are going to upload, and what key you will later use to retrieve it. For example, let's say you are adding a new virtual item to your game's catalog, like a well for your city building game, and you want to upload a graphical icon to visually represent the item in your game's item store. The retrieval key could be anything unique -- it could be "a38434" or "well.png" but for the sake of organization let's use "images/well.png" so that it's clearly identified and stored in a well-defined sub-folder.

2. Locate your game's secret key in the game manager, as well as the API endpoint. You will need both in order to use the Admin API. In this example, we will use the API endpoint "https://2ABE.playfabapi.com" and the secret key "TY77KDZN5W9TI6JOYUYSD51YTQFXR15DIEB63F9AM597GX7DDA" (not the actual secret key, so don't bother trying it).

Credentials screen in Game Manager

3. Call the GetContentUploadUrl function to retrieve the upload URL (feel free to take a minute and click that link to read the API documentation if you'd like, or just continue with this example). There are several ways to call an API -- in this example we will use the widely used cURL library.

To upload a file it's recommended to specify the MIME type of the file. A full list of MIME types can be found here; this is a PNG file so we will use "image/png".

Here is how you would call this API using curl, using the API endpoint, secret key, file key, and content type listed above.

curl -XPOST https://2ABE.playfabapi.com/admin/GetContentUploadUrl
-H "Content-Type: application/json"
-H "X-SecretKey: TY77KDZN5W9TI6JOYUYSD51YTQFXR15DIEB63F9AM597GX7DDA"
-d "{'Key' : 'images/well.png', 'ContentType' : 'image/png'}"

The response will contain a URL that looks like this. This is the URL you will use to upload the file.

https://pf-content-live.s3-us-west-2.amazonaws.com/2abe/etc/images/well.png?AWSAccessKeyId=ASIAJ3VLMQ246XDW24TA&Expires=1434615778&x-amz-security-token=APoDYYdzED8a4AOswTVNkl23fp7jEcfpiusUaqjpb9IfQYGbx6MJsaUw9vuZAbPGBP%2F1l%2BY65Myb8N8zSe%2FyOWtOSOy2UEx1LFGiO2Tr2CEQpYGFJfZfrcsl%2FVJuvMFy%2B1er7pP6SUs5Wfy8WRWdBnpDvwnyqOEo%2BAeqUYILWfaW0GPS4g62J36oGklg8B4q3X3qRhnPBP5A5fzEWIWl5YTMVw8RdXzpebyAQzcKrFGpNabdKQeUF7xJUQX8RXH8cl6aGcieyv%2F6T8ydgnOYRoWizBPo9ORdpSpRZSx9vN2A8%2BtNVze2dJeF66haulJUnT%2BmbrJfCA8lK4%2FyQGbtIkLwL8Gp1u%2FW4jVsx1%2Bsd6%2BHq3oNqzta0ElNkYWiQJDIMFRpJdDyDc0xTzk3iF%2FdN%2FMCitGNcw0mJ5s%2FHvR7x7gSmDNcIktozo4d8StyOUEqWtqxtsE2w%2BNmvP%2BYJaJ7KkYMXVd84Bte%2Bg35TztO6v%2FdISVBP7cozZVmtUb0RbKjwigXvX6vz74q2wx2ZVXy0QkuisSUKjO9wtznsgnJH49mTuau1uD%2FQcrgO9%2FF3EMEESQ9onhERv2kDuJbMzfnHF9XOlabnqv8kd%2Be6QlOy2pbWPiDTV0GfsgELC52%2BIW9tFyKQtr%2FpaxZS5Ig5byJrAU%3D&Signature=GvT7ZGDHBFSTm6BXljQCJD48XJ4%3D

4. Now you can upload the file itself. Once again, we will use the cURL library. The syntax to upload the local file "well.png" to the URL listed above looks like this:

curl -v --insecure -H "Content-Type:image/png" --upload-file "well.png" "https://pf-content-live.s3-us-west-2.amazonaws.com/2abe/etc/images/well.png?AWSAccessKeyId=ASIAJ3VLMQ246XDW24TA&Expires=1434615778&x-amz-security-token=APoDYYdzED8a4AOswTVNkl23fp7jEcfpiusUaqjpb9IfQYGbx6MJsaUw9vuZAbPGBP%2F1l%2BY65Myb8N8zSe%2FyOWtOSOy2UEx1LFGiO2Tr2CEQpYGFJfZfrcsl%2FVJuvMFy%2B1er7pP6SUs5Wfy8WRWdBnpDvwnyqOEo%2BAeqUYILWfaW0GPS4g62J36oGklg8B4q3X3qRhnPBP5A5fzEWIWl5YTMVw8RdXzpebyAQzcKrFGpNabdKQeUF7xJUQX8RXH8cl6aGcieyv%2F6T8ydgnOYRoWizBPo9ORdpSpRZSx9vN2A8%2BtNVze2dJeF66haulJUnT%2BmbrJfCA8lK4%2FyQGbtIkLwL8Gp1u%2FW4jVsx1%2Bsd6%2BHq3oNqzta0ElNkYWiQJDIMFRpJdDyDc0xTzk3iF%2FdN%2FMCitGNcw0mJ5s%2FHvR7x7gSmDNcIktozo4d8StyOUEqWtqxtsE2w%2BNmvP%2BYJaJ7KkYMXVd84Bte%2Bg35TztO6v%2FdISVBP7cozZVmtUb0RbKjwigXvX6vz74q2wx2ZVXy0QkuisSUKjO9wtznsgnJH49mTuau1uD%2FQcrgO9%2FF3EMEESQ9onhERv2kDuJbMzfnHF9XOlabnqv8kd%2Be6QlOy2pbWPiDTV0GfsgELC52%2BIW9tFyKQtr%2FpaxZS5Ig5byJrAU%3D&Signature=GvT7ZGDHBFSTm6BXljQCJD48XJ4%3D=

If all goes well, you should receive a success message that looks like this:

* We are completely uploaded and fine
< HTTP/1.1 200 OK

5. Just to be sure, you can check that the file is there using the GetContentList API call, like this:

curl -XPOST https://2ABE.playfabapi.com/admin/GetContentList
-H "Content-Type: application/json"
-H "X-SecretKey: TY77KDZN5W9TI6JOYUYSD51YTQFXR15DIEB63F9AM597GX7DDA"

This should return a list of the files that have been uploaded, including the most recent file. It should look something like this:

{
  "code":200,
  "status":"OK",
  "data":{
    "ItemCount":4,
    "TotalSize":1509596,
    "Contents":[
      { "Key":"images/UB_Icon.png",
        "Size":9855,
        "LastModified":"2015-06-19T18:44:23Z"
      },
      {
        "Key":"images/test.png",
        "Size":9855,
        "LastModified":"2015-06-16T19:27:47Z"
      },
      {
        "Key":"images/well.png",
        "Size":81754,
        "LastModified":"2015-06-18T07:47:48Z"
      },
      {
        "Key":"sales/sale0001",
        "Size":1408132,
        "LastModified":"2015-06-26T20:58:07Z"
      }
    ]
  }
}

Step 2: Tell Your Game About the File

In order for your game to download the file, it must somehow know about the file and the key that it is filed under. In this example, the image of the well is being used to describe an item in the game's catalog. The file key can therefore be stored in one of the key/value pairs of the catalog item itself.

Consider the following item in your catalog:

Game Manager screenshot

We can assign this item a key/value attribute called "icon" that contains the path to the image, as follows. In this example, the "file:" prefix tells the game that the following string is to be used to download the file.

Game Manager screenshot

Step 3: Download the File

The final step is to have the game download the file. In this example, we'll use Unity and the PlayFab Unity SDK. (If you haven’t already built a project yet, get started with our Getting Started tutorials.)

There are two steps to downloading a file in Unity -- retrieve the URL, and then download the asset.

1. To retrieve the URL, use the GetContentDownloadUrl API. In Unity, you first set up the call using the GetContentDownloadURLRequest object, then you need to handle the returned result.

For example, this code sets up the request:

GetContentDownloadUrlRequest request = new GetContentDownloadUrlRequest ();
request.Key = "images/well.png";
PlayFabClientAPI.GetContentDownloadUrl ( request, OnGetDownloadUrlSuccess, OnPlayFabCallbackError );

And then this code handles the results:

static void OnGetDownloadUrlSuccess( GetContentDownloadUrlResult result)
{
  string returnUrl; returnUrl = result.URL;
}

2. Once you have the URL for the file, you can then download it in a number of different ways. The easiest is probably to use the WWW object which is built into Unity, and even has support for turning the downloaded asset into a texture. Unity provides a good example on its site.

For example:

var url = [URL you get from PlayFab];
function Start () {
  // Create a texture in DXT1 format
  renderer.material.mainTexture = new Texture2D(4, 4, TextureFormat.DXT1, false);
  // Start a download of the given URL
  var www = new WWW(url);
  // wait until the download is done
  yield www;
  // assign the downloaded image to the main texture of the object
  www.LoadImageIntoTexture(renderer.material.mainTexture);
}

In practice, if you are using this technique for updating your game's content post-launch, you would want to cache any files that you download like this on the client, both for efficiency, and to support offline play. However that's beyond the scope of this simple example.

Updating your game post-launch is an important way to keep up your player engagement and retention.  Better support for managing content will be coming soon in the Game Manager, but until then this short example should hopefully show you how to do it with our existing underlying API.