The Google Play plugin allows you to integrate your game with Google Play Game Services. Users can log in, submit and view scores, and unlock achievements.
Setting up Google Play Game Services
Using Google Play Game Services requires that you have an account registered with the Google Play Developer service. There may be a small one-time registration fee if you need to sign up.
For each game that you wish to use Google Play Game Services for, click the Game Services icon in the developer console and then click Add a new game. Enter the name of your game, choose its category, and click Continue.
Once added you can edit the game details such as its description and any associated images. You can also add achievements and leaderboards - which must be added before you can use them in the Google Play plugin - as well as configure testing and publishing.
To ensure your finished game has permission to access the Google Play Game Services, click the Linked apps section while editing the game in the developer console. Click the button to link a Web app. You will need to fill out details such as the URL it is played from and some authorisation details. Once completed, you should be given a client ID. This should be in a format similar to:
Copy and paste this client ID in to the Google Play plugin's Client ID property. It is not actually necessary to fill in the Application ID property, but you can add it anyway: the application ID is the number that appears beside the game name in the header of the Developer Console, e.g. "My Super Game - 12345678". The application ID in this case is 12345678.
Extra steps for Cordova
Google Play Game Services are designed to work in a web browser, but it's possible to also configure it to work in Cordova (e.g. when exporting to mobile via PhoneGap Build or the Intel XDK). To set it up for Cordova you'll also need to:
- Fill in the Client secret property with the value from the Google Play Developer Console.
- Add http://localhost as one of the redirect URIs in the API console.
- Remove any uses of On auto-sign in failed. It never triggers in this mode, so you will need to rely on having manual sign-in instead.
Enabling access in preview mode
When testing your project, your game will typically run from localhost or a local IP address for preview-over-wifi. Since this is is different to the published URL of your game, Google Play Game Services will block access unless you add the preview URLs as permitted locations.
Click Update. Now your game should be authorised to be accessed from preview mode as well as when you publish it.
To use the Google Play plugin, you must first wait for it to finish loading. Do not attempt to use any features of the plugin until On loaded triggers, or Is loaded is true.
Next the Google Play plugin will automatically try to sign the user in. If they have successfully signed in before, On signed in will trigger soon after loading. If they have never signed in before, On auto-sign in failed will trigger; in this event you should show a button that allows the user to sign in. When they click this button, use the Sign in action; if it succeeds, On signed in will be triggered.
Once the user is signed in, you can make use of the other plugin features such as requesting leaderboards, submitting high-scores, and unlocking achievements.
Most actions in the Google Play plugin are asynchronous. This means they are not completed immediately. Instead, the action starts a request which is sent off to the Google Play servers. A few moments later the server will respond, and a corresponding trigger will run in the Google Play plugin.
For example, the Request play details action does not complete immediately. The player details are not available until On player details received triggers, which should happen shortly after running the action. Only after the trigger runs can the player details be accessed.
Google Play properties
This is not currently necessary, but can be filled out with the application ID from the Google Play Developer Console.
The client ID for the game from the Google Play Developer Console. For more information see the section Setting up Google Play Game Services above.
The client secret for the game from the Google Play Developer Console. This is only necessary when publishing via Cordova (e.g. PhoneGap Build). For more information see the section Setting up Google Play Game Services above.
Google Play conditions
Compare achievement state
Compare whether an achievement at an index is revealed, hidden or unlocked. The achievement list must have already been successfully received.
On achievement list success
On achievement list fail
Triggered after the List achievements action, depending on whether the request succeeded or failed. If successful, achievement information for the current player is then available.
On achievement metadata success
On achievement metadata fail
Triggered after the Get metadata achievements action, depending on whether the request succeeded or failed. If successful, achievement metadata (such as the achievement names and icons) is then available.
On achievement revealed
On achievement unlocked
Triggered after the Reveal, Unlock or Increment actions when an achievement has successfully been revealed or unlocked. When incrementing achievements, the achievement is unlocked when it has incremented through every step.
True if the Google Play plugin has loaded and is ready to use. Before this is true, no features of the plugin will work.
Is signed in
True if the user has been successfully signed in (possibly automatically).
On auto-sign in failed
Triggered upon the first visit, when the user cannot be automatically logged in. It is necessary to display a 'Sign in' button and use the Sign in action to get the user to sign in.
Triggered if an error occurs. The ErrorMessage expression will contain information about the error.
Triggered when the plugin finishes loading and is ready to use. Before this triggers, no features of the plugin will work.
On player details received
Triggered after the Request player details action, when the player details have been successfully received. The Player details category of expressions now are set to their correct values for the currently signed in user.
On signed in
On signed out
Triggers when the user is signed in or signed out from Google Play Game Services.
On hi-score request success
On hi-score request fail
Triggered after the Request hi-scores action depending on whether the request succeeded or failed. If successful, the hi-scores list is then available.
On score submit success
On score submit fail
Triggered after the Submit score action, depending on whether the submission succeeded or failed. If successful the score should then appear in hi-score lists.
Google Play actions
Request metadata for the achievements list, such as the achievement names, descriptions and icons. If successful, On achievement metadata success is triggered.
Add to, or set, the number of steps in an incremental achievement. Once the full number of steps has been reached, the achievement is automatically unlocked.
List the achievements for the currently signed in player. Optionally the list of achievements can be filtered to only those in a given state (e.g. revealed). If successful, On achievement list success triggers.
If an achievement is hidden, set its state to 'revealed' for the currently signed in player. If revealing for the first time, On achievement revealed will be triggered.
If an achievement is not already unlocked, set its state to unlocked for the currently signed in player. If unlocking for the first time, On achievement unlocked will be triggered.
Request player details
Request the details of the current player, such as their name and avatar image. If successful On player details received triggers and the Player details category of expressions can be used.
If the player is not already signed in, pop up a window that allows them to sign in. Due to popup blockers, this may only work in a user input event, such as On button clicked or On touch start.
If the player is already signed in, sign them out. This also allows for a different user to then sign in.
Request a hi-score list for a given leaderboard. Scores can be returned for public results, or "social" (from users connected to the currently signed in player), and a time limit can be applied such as to return only the day's best scores so far. The top type returns the very highest scores, and the window type returns the scores around the current player's own best score, allowing them to see where they appear in the rankings.
Submit a new hi-score to a leaderboard. A tag can be provided, which is just a short string (up to 64 characters) associated with this score board entry, e.g. a short comment or an alternative alias for the player. If successfully submitted, On score submit success triggers.
Google Play expressions
The total number of achievements available. The achievements list must already have been successfully requested.
Retrieve information about a given achievement in the achievements list. The achievements list must already have been successfully requested.
Retrieve the icon image URL for a given icon in either its unlocked or revealed state. This can be displayed using the Sprite object's Load image from URL action.
In On error, the relevant error message if available.
The number of hi-scores in the current returned list of results.
The total number of scores in the leaderboard, which may be greater than the number of returned results (HiScoreCount).
Return a numerical value, or formatted string, for a score at a given index.
Return the numerical rank, or formatted string of the rank (e.g. "1st"), at a given index.
Return the name of the player associated with the score at an index.
Return the tag (a short string) that was submitted along with the score at an index.
Return the details for the current player's own best score, including the numerical and formatted versions of the score and rank.