Thanks for choosing the PlayFab API Addon by Zalance. Yes, it is a free addon! This is an introduction to working with the PlayFab API as well as integrating it into your game. This first part will focus on authentication and getting your users logged into your game. It assumes you already have a PlayFab account created with a game project.
SEE A WORKING EXAMPLE
It's helpful to know what we're heading towards, so click here to open the working example. Once it loads, click the Preview button (shown, circled in red, below) to run it and try it out.
The first screen shows the authentication example. This screen has player support for two actions - log in and sign up.
When you're done, close the preview and press reload in your browser so Construct 3 restarts. This is so we can start the rest of the tutorial from a clean slate.
ASKING FOR HELP
If you get stuck or have a question, please email us. Comments are enabled for this tutorial, but they're easily missed. You're more likely to get a response from an email.
GETTING STARTED
INSTALL THE ADDON
Either open your existing project or click the New Project button. Next, you will need the PlayFab API Addon either available from the Construct Addons page or the Zalance website. Click the download button and save the file to your computer. Install the addon through the Addon manager. The Addon manager can be accessed from the Construct editor from Menu►View►Addon manager.
Click the Install new addon button at the next screen's bottom.
Install the addon by selecting the PlayFab API .c3addon file you downloaded to your computer.
SETUP THE PLUGIN
We need to add the PlayFab API plugin object type to your object’s list. Right-click the Object types in the Project view and choose Add new object type.
Then choose the PlayFab API plugin.
Select the PlayFabAPI object that was created in the Object types menu.
In the Properties panel, enter your PlayFab Project ID.
If you don’t know your project ID, you can find it by visiting your PlayFab games list. The ID will be displayed on your game’s info card.
CREATE THE LOGIN SCREEN
Let's create the login screen your players will need to log into your game. Start by creating a new Layout and name it Login.
ADD THE UI
We need form fields for the user to either authenticate or navigate to the signup screen. First, add two Text object types, one for email and one for password. Name them as Email and Password respectively. Add a button to your layout and call it LogInButton. Now add a second button and call it CreateAccountButton. This will be for redirecting players to a separate SignUp layer. Also, we need to add labels to all of the form elements so players know what they are for. Your layout should look something like this:
LOGIN EVENTS
For our elements to interact with the Zalance API, we need to add the auth functionality. Create a new event sheet and call it LoginCode. Add your first event to this by clicking the Add event to LoginCode. Then, select the LogInButton you created in the previous step.
Then in the next conditions screen, choose On clicked for the condition.
For the action, click the Add action link.
Then find and select the PlayFab API under the Add action dialog.
Choose the Log in with email action under the Authentication section.
On the next screen, we need to add our email and password fields to the input parameters. For Email, choose Email.Text. And for Password, choose Password.Text.
Select OK and you should see your new event on the event sheet.
Now, we need to interact with a successful login action. Let’s click Add event again on our event sheet. And this time, we’ll select the PlayFabAPI condition followed by clicking Next.
On the next screen, choose the On Authenticated condition which will add the new event.
For the action, let’s progress the player to a new screen once they are logged in. This is a great place to take them to the main menu or introduction content that is only available to authenticated users. We’ll select Add action►System►Layout►Go to layout (by name) and choose the name of the layout you want to direct your player to. For this tutorial, we have a layout named “MainMenu”.
Once finished, you should see your new event.
At this point, you have everything you need to handle a successful login. You can preview these changes and test out your authentication with an existing player. Enter the player’s email address and password and click Log In. If all is successful, you should be directed to your next layout.
HANDLING ERRORS
Of course, not all login attempts will be successful. When a login fails, we need to show the user a message so they understand what is happening and provide a good user experience. Add a new Text object, name it LoginMessage, and place it below the login button. Remember to make your text color different from the background so it shows up. We’ve made ours red in the example.
Finally, we need to add an event to capture messages from PlayFab and send them to our new LoginMessage text box. Go back to the LoginCode events sheet and click on Add event. Create a new PlayFabAPI condition that responds to the Authentication On Message. Then, add an action to this event for LoginMessage that will Set text to PlayFabAPI.Get Message. When finished, it will look like this.
To try this out, go ahead and press the preview. Then for the email and password, put in some values you know will fail. For example, Email: nobody@fail.com, Password: 1234. After clicking LOG IN, you should see an error message stating that the user wasn’t found.
If you remove either the email or password fields, you will see an error message stating that they are required.
CONCLUSION
With this tutorial, you have now integrated an email login with PlayFab into your game. Remember that you can download a working example of this tutorial on the Zalance download page or see it in action in the Construct Arcade PlayFab API demo.
In the next part, we’ll be looking to build on this where we’ll create a signup screen to register new players.