Game Services

Introduction

---

Game services provide tools that let you easily integrate popular gaming features, such as Player Identity and Saved Games, into your mobile and tablet games.

Leverage Plankton's Game Services functionality to seamlessly handle saving/loading user profiles and signing them in with either Google Play Games Services on Android or Apple's Game Center on iOS.

In the upcoming sections, you'll find in-depth instructions on integrating the Plankton Game Services feature into your Unity project for both platforms.

Before you begin

---

Prerequisites

• Complete the Plankton setup
• For Android
  • Set Target API Level to 28 or higher
  • Set Minimum Api Level to 19 or higher
• For iOS
  • Set Target Minimum iOS Version to 15.0 or higher

note

You can change Minimum and Target versions in Unity from Edit > Project Settings > Player > Other Settings

Set up your accounts

Android

The Google Play Console is where you manage Google Play games services for your game, and configure metadata for authorizing and authenticating your game. For more information, see Setting Up Google Play Games Services.

After adding your game to Google Play Console and generating an OAuth 2.0 client ID, retrieve the application ID which can be found at the top of the Configuration page and is labeled as Project ID below the name of your game.

Application ID

The application ID is a required string consisting only of the digits (typically 12 or more) at the beginning of the client ID provided by the Google Play Console.

iOS

Before submitting your app for review, Game Center must be configured in App Store Connect for any apps offering Game Center features. Once you've uploaded your game with Game Center functionality to TestFlight, follow these steps to enable Game Center:

1. In the App Store Connect dashboard, go to Apps and select your app.
2. In the sidebar, click the app version you want to enable for Game Center.
3. Scroll down to the Game Center section and check the box to enable it.

Entitlements in Xcode

If you've heard about needing to add entitlements or configure something in Xcode, don’t worry! Plankton takes care of all Game Center entitlements automatically, so you won't need to do any extra setup.

Confiure Plankton settings

---

1. Open plankton settings by going to Edit > Project Settings > Plankton.
2. Select the checkbox next to the Google Play Services for Android or the Game Center for iOS
3. For Google Play Services fill the App Id field with your Application ID

Implementation

---

It's time to write a few lines of code. Always import the Plankton package in your scripts.

using Plankton;

Sign In

To access game services functionality, your game must authenticate the player by signing them into their account. Here's how you can start the sign-in process for the player:

GameServices.SignIn(callback: result => {
    // result is of type SignResult with the following fields
    //   success = result.success
    //   userId = result.user_id
    //   displayName = result.displayName
    //   email = result.email (Android only)
    //   idToken = result.token (Android only)
    //   serverAuthCode = result.serverAuthCode (Android only)
    Debug.Log($"Game Services sign-in result: success={result.success}");
});

The result of the sign-in process is returned as a SignResult class, which contains multiple fields. Some of these fields like token and serverAuthCode are only available if a serverClientId is provided to the SignIn method. (See next section)

On Android devices, if the player hasn't signed in before, a Google dialog will be shown which asks the user to select an account. This pop-up won't be displayed if the player has signed in the game before, so the sign-in process will be executed silently.

On iOS devices, the sign-in process is handled silently using the iCloud account that the player is already signed into on their iPhone or iPad. A sign-in dialog will only appear if no active iCloud account is detected on the device

Android Optional Parameters

The SignIn method has two optional parameters in Android platform:

• serverClientId: A string which is the OAuth client ID of your game server. Read about generating an OAuth client ID in Google Play Console. You have to pass this parameter to the SignIn method in order to get token and serverAuthCode in the SignResult.
• forceInteractive: A boolean parameter. When true, the Google sign-in dialog will be displayed every time you call SignIn method. Due to other settings that the user sets in their Play Games app, this parameter might not behave as expected!

Check if the user is signed in

You can ensure that the user is signed in or not using the IsSignedIn property:

bool isSignedIn = GameServices.IsSignedIn;

Saved Games

The Saved Games feature provides a convenient way to store and retrieve your players' game progress across devices. On Android, it utilizes Google Play Games Services, while on iOS, it leverages iCloud through Game Center.

This allows players to seamlessly continue their game from their last save point, even if they uninstall and reinstall the game on the same device or switch to a different one.

Plankton enables saving and loading a user's data through GameServices.Save and GameServices.Load methods.

Save

To store data you can call:

GameServices.Save("Filename", "Data to be saved", "Developer description", succeed => Debug.Log($"Save result:{succeed}"));

This method has four arguments:

• filename which act as a key to create multiple saved games with different names
• the savedData which is a string value that is going to be stored on the player's account.
• description is a developer-supplied description of the saved game.
• a callback argument which gets called when the save process is finished. It returns a bool parameter indicating whether it was succcessful or not.

tip

The saved data can be a serialized form of a user profile that you know how to deserialize. For example, it can be in the JSON format or any other format you prefer.

Load

For loading the data that you have saved earlier, you can call:

GameServices.Load("Filename", data => Debug.Log($"Load result:{data}"));

This method has two argument:

• filename which act as a key to create multiple saved games with different names
• a callback argument which gets called when the loading process is finished. It returns a string parameter containing the saved data.

note

If the loading process fails or it doesn't find any saved games, the returned data in the callback of Load method will be empty.

API Refrences

---

Defined Types

In this section, we will discuss the classes associated with this feature:

Classes

GameServices.SignResult

Name	Type	Default Value	Description	Platform
success	bool	false	A flag indicating if the sign-in process was successful or not	Android/iOS
user_id	string	string.Empty	A unique identifier for the account in the game	Android/iOS
displayName	string	string.Empty	the name of the signed in user which is displayed to others	Android/iOS
email	string	string.Empty	The email address which the user has signed in with	Android
token	string	string.Empty	An ID token that you can send to your server. Must provide serverClientId in the SignIn method in order to receive token.	Android
serverAuthCode	string	string.Empty	A one-time server auth code to send to your web server which can be exchanged for access token. Must provide serverClientId in the SignIn method in order to receive serverAuthCode.	Android

Method Summaries

Method	Arguments	Return Type	Description
SignIn	Action<SignResult> callback, bool androidForceInteractive = false, string androidServerClientId = ""	void	To prompt the user to sign-in to their Google/Apple account call this method which takes a callback that gets invoked when the sign-in result is ready. It also takes two other arguments only in Android. When androidForceInteractive is true, the sign-in dialog will always display. The serverClientId is neccessary for receiving token and serverAuthCode in the SignResult
Save	string fileName, string json, string description, Action<bool> callback	void	You can save a string value in Game Services, whether using Google Play Services on Android or iCloud through Game Center on iOS. This could be a serialized form of a user profile or any game data you can deserialize later, such as in JSON or any format you prefer. This method takes multiple arguments. fileName which specifies the name of the saved data. json is the data to be saved. description is an explanation about the saved game(Android only). The last parameter is a callback that gets invoked when the saving result is ready.
Load	string fileName, Action<string> onCompleted	void	For loading the data that was saved for the user, call this method which takes two arguments. First a fileName which specifies which saved game to load. Second is a callback that gets invoked when the load result is ready.