The most important feature to grasp with the Heroic Labs service is how to create and manage gamer accounts in your games. Almost all of the features in the service revolve around requests you can perform within the context of a gamer playing a game. For example, when a gamer is logged into their account you can save their games, trigger their achievements, submit new scores to the leaderboards, and much more.
The service uses a "gamer token" to identify a specific gamer logged into a game. Gamer Tokens are discussed in more detail in the Authentication section.
Heroic Labs uses a unique approach to create and manage gamer accounts which enables us to support many different login mechanisms. There are three main login mechanisms so far; Anonymous Login, Social Login, and Email Login. Currently supported Social Login providers include Facebook, Google, and Tango. You have the option of providing any combination of login options you want in your games, and all of the features in our service will work.
Accounts and Profiles
An account represents a gamer's core identity in the Heroic Labs service. It ties together the gamer's unique ID assigned by the service, their nickname, optional information such as timezone or locale, and one or more profiles.
Anonymous IDs, Email Logins, and Social Logins are tied to profiles. Profiles are used to connect multiple identities to the same gamer account. An arbitrary number of profiles can point to the same gamer account.
Accounts and profiles have a one-to-many relationship. An account can have more than one profile, and a profile will only ever be linked to one account.
Gamer accounts are created automatically when needed, such as when requesting a fresh login with a Facebook account that doesn't yet exist in the Heroic Labs service. If an existing gamer identity is provided instead, the new profile will be linked to the existing account instead of creating a new one.
Accounts are assigned a unique ID when they are first created by the Heroic Labs service. This ID is a reliable way to identify each account, and will not change for the lifetime of that account.
Nicknames are a property of the account, and are unique per game. All nicknames must be 3 to 32 printable UTF-8 characters, and will be checked for profanity.
With any login option we automatically create nicknames for new gamer accounts so they can appear in the leaderboards, etc. These nicknames are generated using a safe word list; some examples are: "ProudFraction4537", "IntellectualTune5407", and "LeftFront0339". Nicknames can be changed at any point after login.
Retrieving an account will also list the profiles currently attached to it.
For more information have a look at the API Reference.
Profiles provide a wide variety of mechanisms for identifying gamers with the Heroic Labs service. Profile types may have slightly different usage patterns or requirements, but each profile is treated equally within the service.
The most efortless way of identifying a gamer with the Heroic Labs service is to use an Anonymous ID. This can be done entirely without user interaction, so the user experience is completely frictionless.
You can think of 'Anonymous' login as guest profiles. They don't require any information from a gamer to create although you'll want to use an identifier from the gaming device which can be used to recover the account if necessary.
Anonymous logins are performed by sending Heroic Labs a single field representing a unique identifier, usually a UDID or a Device ID. This unique identifier can be used again later to retrieve the same account for example when recovering the account after the game is removed and reinstalled.
If a UDID or similar is not available on your platform, you can generate and cache locally a random string identifying the client environment, such as a browser.
The UDID from mobile devices like Android and iOS are changed often by the operating system vendors. They are not reliable sources for uniquely identifying the device; you should cache the UDID once obtained so the game can use it to recover the account.
For more information have a look at the API Reference.
Facebook, Google, and Tango
Heroic Labs provides a simple mechanism for your game to implement social login, allowing your gamers to sign in using Facebook, Google, or Tango, and start playing right away.
We're always interested in adding support for more social login providers; if you'd like us to support a specific social network please let us know.
To perform a social login, ensure the gamer is first logged into their social account and has authorised your game. This may be done through the native Facebook/Google/Tango application on a mobile platform, or through OAuth for desktop and web games; see each platform provider's documentation for instructions on this step.
Once the social authentication is complete, the last step is to send Heroic Labs the access token available through the SDK or web endpoint of the social provider. This is usually an OAuth 2.0 access token, but varies by social provider.
The Heroic Labs service will use the access token to retrieve the social profile from the remote provider, and map it to a gamer account in the service.
This method allows you to have full control over the login flow and user experience of your game, and is also particularly useful when:
- You are developing for a wearable device or a VR headset where an interactive screen may not be appropriate.
- You are developing a game which requires deeper integration with a social network (such as a Facebook Game).
- Your game requires custom server-based game logic which is executed after a successful login.
Heroic Labs supports authentication using Game Center Player IDs on compatible Apple devices. This is a good frictionless authentication option as it requires no user input much like Anonymous accounts.
Gamers can be authenticated by sending the following Game Center credentials to the server:
Public Key URL.
For gamers that still want to log in, but would prefer not to connect through their social or platform accounts, Heroic Labs provides a custom login option, where accounts are created and managed entirely by the Heroic Labs service.
Email profiles are explicitly created using an email address and password. If the gamer forgets their password, this can be reset through an email requested to the address used to register the profile.
There are a variety of ways to interact with gamer accounts and profiles, allowing game clients the flexibility to handle any authentication or identity scenario.
The Heroic Labs service provides methods to check if a given profile exists:
- For Anonymous profiles, check if the given Anonymous ID is already registered with the service.
- For Social profiles, check if the social account identified by the given access token is already registered with the service.
- For Email profiles, check if the given email address is already registered with the service.
Additionally, an existing session or gamer token can be given to the check functions. In thses cases the service will also return a flag specifying whether the profile is linked to the identified gamer, when the profile existed.
This allows game clients to choose an appropriate action from the account operations listed below: Login, Link, or Unlink.
Logging in is the main way to access a gamer account. Using the appropriate endpoint for the chosen profile type and passing in the required credentials will return an existing gamer account, or automatically create a new one if necessary.
Email profiles are never automatically created. Instead they must be explicitly created before a login is possible.
Linking is a direct way to attach a new profile to an existing gamer account. You can only link profiles that are not otherwise currently linked to a different gamer.
Because email profiles are explicitly created, they cannot be linked at a later point. Make sure you supply a session or gamer token at create time to link the new email profile to.
Unlinking removes a specific profile from the gamer account. Once an unlink has been performed, it will no longer be possible to login to the account using that profile.
Once unlinked, the profile is removed from the system and its ID is made available for new registrations, or for linking to other accounts. An unlink operation cannot be undone; game clients should use the corresponding Link operation to achieve the opposite effect if needed.
Accounts must always have at least one profile linked to make sure they remain accessible. The service will prevent unlinking of the last profile on any given account and return an error.
Whichever login mechanism you use in your games you will receive a session which can be used create, edit, and delete data which belongs to the gamer.
For example, you could fetch information about the gamer, maybe to greet them!
Check out our feature documentation for other cool things you can do.
Session object on the client to make sure it still available if the game is closed and restarted. For example, on Unity check out the