Python quickstart

This quickstart is designed to help you make your first API call in Python 3.

Before continuing, make sure you have completed Getting started for developers which ensures you have a PlayFab account and are familiar with the PlayFab Game Manager.

A native Python project can be used a few ways:

  • As a stand-alone console Admin tool for maintaining your game.

    • The Python SDK works great as a stand-alone Python program.
  • Integration into an existing Python-based game engine.

If you have any issues, let us know on the Forums.

Note

This beta release of the Python SDK only supports synchronous API calls, and your game loop may become blocked performing PlayFab API calls. You may need to create your own async/threading model to avoid this problem.

Before continuing, make sure you have completed Getting started for developers which ensures you have a PlayFab account and are familiar with the PlayFab Game Manager.

Python project setup

  1. Make sure Python 3 is installed on your system.

  2. Install the PlayFab Package using the command shown below.

pip install playfab

If pip is not in your path, use the command shown below instead.

python -m pip install playfab
  1. Create a new python script in your desired directory called playfab_test.py.

Set up your first API call

This quickstart provides the minimum steps to make your first PlayFab API call without any GUI or on-screen feedback. Confirmation is accomplished with a console print statement.

To start, replace the contents of playfab_test.py with the contents shown below.

from playfab import PlayFabClientAPI, PlayFabSettings

PlayFabSettings.TitleId = "144"

request = {
    "CustomId": "GettingStartedGuide",
    "CreateAccount": True,
    "LoginTitlePlayerAccountEntity": True
}

def callback(success, failure):
    if success:
        print("Congratulations, you made your first successful API call!")
    else:
        print("Something went wrong with your first API call.  :(")
        if failure:
            print("Here's some debug information:")
            print(failure.GenerateErrorReport())
PlayFabClientAPI.LoginWithCustomID(request, callback)

Finish and execute

Run the Python script using the following command:

       python playfab_test.py

When it finishes, you should see the following text: "Congratulations, you made your first successful API call!"

At this point, you can start making other API calls, and building your game. For a list of all available client API calls, see our PlayFab API References documentation.

Happy coding!

Deconstruct the code

This optional last section describes each part of playfab_test.py in detail.

  • Imports

    • The PlayFab imports get you access to the APIs.
  • PlayFabSettings.TitleId = "144"

    • Every PlayFab developer creates a title in Game Manager. When you publish your game, you must code that titleId into your game. This lets the client know how to access the correct data within PlayFab. For most users, just consider it a mandatory step that makes PlayFab work.
  • request

    • Most PlayFab API methods require input parameters, and those input parameters are packed into a dictionary object.
      • For LoginWithCustomIDRequest, there is a mandatory parameter of CustomId, which uniquely identifies a player, LoginTitlePlayerAccountEntity, which automatically logs the player's title_player_account in and returns the associated entity token, and CreateAccount, which allows the creation of a new account with this call.
      • For login, most developers will want to use a more appropriate login method.
  • Callback

    • Success

      • If the API call was successful, success will contain the requested information and failure will be None.
      • For login requests, success will contain basic information about the player, but for most users, login is simply a mandatory step before calling other APIs.
    • Failure

      • If the API call wasn't successful, failure will contain some error information and success will be None.

      • API calls can fail for many reasons, and you should always attempt to handle failure.

      • Why API calls fail (In order of likelihood)

        • PlayFabSettings.TitleId is not set. If you forget to set titleId to your title, then nothing will work.
        • Request parameters. If you have not provided the correct or required information for a particular API call, then it will fail.
        • Device connectivity issue. Cell-phones lose/regain connectivity constantly, and so any API call at any time can fail randomly, and then work immediately after. Going into a tunnel can disconnect you completely.
        • PlayFab server issue. As with all software, there can be issues. See our release notes for updates.
        • The internet is not 100% reliable. Sometimes the message is corrupted or fails to reach the PlayFab server.
      • If you are having difficulty debugging an issue, and the information within the error information is not sufficient, please visit us on our forums

  • PlayFabClientAPI.LoginWithCustomID

    • Triggers the API call synchronously. When complete, the callback will be invoked.