How To Authenticate Players

Holger Weissböck on July 15, 2013

Hello Floxxers! Today I’ll shine a light on Flox player authentication and the login process. Player authentication is one of the most basic parts of the Flox SDK and almost all of you will encounter it in your game development endeavors. As with all things Flox the player login process is designed to be as lean as possible.

There Shall Be A Player

The most important fact you need to keep in mind is that there is always a player logged in when you use the Flox SDK. Yes, even if you start your game for the first time. You can access the currently logged-in player using the example code below:

//Retrieve the currently logged-in player.
var currentPlayer:Player = Player.current;

In the example above Player.current will never be null, but will always point to the last logged-in player. This means that if you’ve logged in a player during the last game session and restart your game, Player.current will return that last logged-in player. On the other hand, if you start your game for the first time Player.current will return a new player of type “Guest”. That way, you will never need to worry about null-checking the current player, and you will never have to wonder if it’s necessary to call one of the login methods.

Different Authentication Types

As you may already know, Flox sports three different types of player authentication: Guest, Key and Email. You can read up on the details of those types in the Flox documentation. For those of you, who are lazy readers, here is a short summary:

  • Guest Authentication: Guests are players that are bound to a single installation of your game. They get a random ID and can be used like other players. However, they can not be transferred to other game installations.
  • Key Authentication: Players are identified by a single foreign “key” string, that you are able to submit. Use this to integrate your Flox players with a foreign authentication system, such as facebook or the iOS GameCenter. These players are recoverable (they will be able to access their game data from different devices as long as the “key” string is the same.)
  • Email Authentication: Players that authenticated themselves using their email address. Player need to authenticate every device/browser they are playing on by clicking a link within an email they receive. These players are recoverable as well.

That said, most of the games on Flox use one of the following two approaches: They either allow their players to start out as guests and convert them to key/email players at a later point. That way players may start playing immediately and will be confronted with some authentication at a later point in the game, hopefully when they’re already hooked to the gameplay. Other games force a single authentication type on their players. For example, if your game runs on facebook you may want to enforce key authentication at all times.

In the following two sections, I’ll give you an overview over how I’d implement these two scenarios.

Example 1: Lenient Guest/Email Authentication

My game lets players start out as guests, play a little, and tries to convert them to email players after the first level. To do that the score screen at the end of the level shows my players something like this hint: “To be able to access your game from any device, please enter your email address.”. If the player decides to enter his email address, my game converts the current guest account to a full-blown email player account.

To achieve this functionality, all I need do is the following. Firstly, at the start of my game, I use whatever player Player.current points at and refresh its state. That way I ensure that the player I work with is at the latest server state:

//Refresh the currently logged-in player.
Player.current.refresh(
    function onComplete(player:Player) {
        //The player has now been refreshed and represents the server state.
        //We can continue with the game logic.
    },
    function onError(message:String) {
        //An error occurred: Handle it.
    }
);

Secondly, if a player hits the “Login With Email” button at any point in the game, I do the email login and convert the current guest player to an email player:

var email:String = "yu@no.com";

Player.loginWithEmail(email,
    function onLoginComplete(player:Player) {
        //The player is now logged in.
    },
    function onLoginFailed(error:String, confirmationEmailSent:Boolean) {
        //An error occurred: Handle it.
    }
);

From now on this player will be able to access his account by logging in via his email address.

The cool thing about email and key login is this: If the current player is a Guest and has been playing for a while, then it’s entirely possible that he has already progressed within the game. I would not want him to lose his progress by logging in via email authentication. That’s why the Flox server converts the current guest player and all its data to an email player, if such an email player does not yet exist. Read more about email authentication over here.

Example 2: Strict Key Authentication

My second game is a facebook game and I want it to integrate with the facebook user system. Therefore I am going to force key authentication onto all my players. I do not want any guest players: I’d rather like them to use their facebook IDs to access their data. I know that Player.current gives me a guest on my first game start. Using that knowledge, I can do the following:

//Check if the current player is a guest. If so, this is the first start
//of the game and the player has not yet been authenticated.
if(Player.current.authType == AuthenticationType.GUEST) {
    //Player.current points to a guest player. We need to find/create
    //this player's foreign key and log the player in.
    var key:String = "facebook-1238589021";

    //Now since we have the key, let's login the player.
    Player.loginWithKey(key,
        function onComplete(player:Player) {
            //The player is now logged in.
            //We can continue with the game logic.
        },
        function onError(message:String) {
            //An error occurred: Handle it.
        }
    );
} else {
    //Player is already logged in. This is not the first game start.
    //We can continue to use Player.current in our game.
    //In order to get the current players server state we need to call
    //refresh on the player.
    Player.current.refresh(
        function onComplete(player:Player) {
            //The player has now been refreshed.
            //We can continue with the game logic.
        },
        function onError(message:String) {
            //An error occurred: Handle it.
        }
    );
}

That’s it! Now the correct player will be logged in on every game start!

Refreshing Players And Entities

As you’ve seen in the examples, I use the refresh method to get the current server state for my players. One thing to keep in mind is that calling refresh will eventually overwrite the players or entities current state with the state from the server. In other words: local or unsaved changes will be lost and overwritten by the server-side state. That’s why you should make sure that you always save your players and entities after you’ve changed crucial properties.

And Finally…

If you’d like to get more information on all of this I am not getting tired of recommending this article. However, what you just read should give you a good starting point for your own game code. Do any of you use Flox authentication differently?