By default, a user’s data is lost when they remove a game from their device. If they later re-install it, they start again as a new user. The social login feature solves this problem by binding the user’s progress to a specified Facebook account. After re-installing the game on the same or another device via a Facebook login, they can continue from their previous state. In addition, this feature can also be used to enable users to play across multiple devices while preserving their game progress. In this way, the user’s game experience can be enhanced.

Important

This feature is not compatible with games developed with the Spil Games SDK prior to version 2.7.0. There is a serious risk of data loss when using game versions based on older SDK versions. It is strongly recommended that you implement a forced update of older games using a pop-up dialog.

In addition, you should coordinate with our Spil Games Account Manager to ensure that the required Facebook app has been set up for your game. They will also provide you with the necessary Facebook app ID. The Facebook login flow should be implemented in your game before implementing the social login feature.

Facebook SDK Requirements

To start using the social login feature with Facebook, do the following:

1. Download the latest version of the Facebook SDK. It is available from: https://developers.facebook.com/docs/unity/downloads/
2. Add the Facebook SDK to your IDE project as described in https://developers.facebook.com/docs/unity/gettingstarted. Use the Facebook app ID provided by your Spil Games Account Manager.

Implementing the Facebook Login

Within the game, login the user via the provided Facebook app using the following method and handle the result:

Note that additional permissions (such as the user’s e-mail address) can be specified as part of the call. For further information, consult the Facebook SDK documentation. If the Facebook login is successful, retrieve the Facebook user ID and Facebook token from the Facebook SDK using the following properties:

Note that both items are required for the Spil Games SDK login.

Implementing the Google Play Games

To start using the social login feature with Google Play Games, follow the instructions found here:
https://github.com/playgameservices/play-games-plugin-for-unity

Implementing Game Center

Game center can be implemented using the Unity Social API:
https://docs.unity3d.com/Manual/net-SocialAPI.html
After login the game center’s user auth details can be retrieved using a library like this: https://github.com/abivz/unity3d-gamekit-identity-plugin/.
The auth details can be passed to the UserLogin method in a dictionary as 4th parameter containing 3 key/value pairs: “publicKeyUrl”, salt” and “timestamp”.

Implementing the Spil Games SDK Login

Use the following method to login the user:

where:   

• socialProvider should be SocialLoginNetworks.GooglePlayGames, SocialLoginNetworks.GameCenter or SocialLoginNetworks.Facebook. Because this parameter is used across multiple methods, it is recommended that you maintain consistency by defining it statically.
• socialId should be the Facebook user ID, Google Play Games User Id or Game Center User Id.socialToken should be the Facebook access token retrieved earlier from Facebook, token from Google Play Games or Game Center authentication information (should be passed in the optional parameter).           

Success

After a successful user login, the Spil Games SDK triggers the following event:

where:

• resetData specifies if the current loaded data should be reset. Typically, this happens when a different existing user logged in.
• socialProvider and socialId specify which user was login in. Both will be null in the case of a guest user.
• isGuest specifies whether the user is a social or guest user. It will only be true if the user performed a re-login after their Spil Games session token expired and they choose to continue as a guest user.

Failure

If the user login failed, the following event is triggered:

The errorMessage parameter describes what went wrong. The ShowNativeDialog() method call can be used to display a dialog with the error message directly to the user. Within SpilErrorMessage, the error codes shown in the table below can be returned. Description Invalid Spil Games token! Please login again. Event requires user login. The provided social token could not be verified by the Spil Games backend. Please login again. The user already has a social provider account. Please first logout. The specified social ID is already linked to another user.   33343536

Code
32

 

Checking if a user is already logged in

Sometimes it is useful to know whether a user is already logged in. For example, when re-starting the game. The current user login status can be retrieved by calling the following method:

Logging out a user

Use the following method call to log out a user:

global specifies whether the user should be globally logged out of all devices they are currently playing on (TRUE), or remained logged in on any other devices (FALSE). One of the following events will be triggered to indicate whether the logout was successful:

Note that it is only important to handle the fail event in the case of a global logout. In this case, the ShowNativeDialog() call can be used to display a dialog with errorMessage.

Logout and continue as a guest user

Use the following method to logout the user and let them continue as a guest user:

It will reset the user ID and user data. This method be called after their session token expired (explained in Handling Expired Session Tokens). This method has almost the same functionality as the normal logout call, but performs additional tracking and triggers a different success event to indicate that the user is playing as a guest:

Handling Expired Session Tokens

The social login feature works by internally assigning a session token to the currently logged in Facebook, Google Play Game or Game Center user. Each gameplay session receives a new token. This token, called “spilToken”, is sent with each request made by the Spil Games SDK to the Spil Games backend. The token is used to validate that the user is still correctly logged in.
It can happen that the session of a logged in user is no longer valid, either because the session token has expired or due to a global logout on a different device. In these cases, an authorization error is triggered, and the user should either re-login or continue as a guest user. The following event will be triggered after an authorization error:

After an authorization error, a popup is displayed to the user asking whether they want to re-login or continue as a guest user. The Spil Games SDK provides a default popup that can be used to show this error by calling the following method:

The default dialog triggers the following event to inform the developer that the user selected the re-login option:

The Facebook login process should be re-initiated after this event.  

Resetting the User Data

The user data (described in Supporting Wallet, Shop and Inventory Control) and game state (described in Working with Game States) can be reset after a logout or a non-guest login by calling the following method:

Displaying the Current Device ID

The device ID can be displayed together with the Spil Games user ID in the game. This can be useful for Customer Support when resolving issues. See Implementing Customer Support for more information.

The device ID can be retrieved using the following method:

 

Implementing Cross-Device Data Synchronization

The user data synchronization feature can be used to enable the synchronizing of user data when a logged in user is playing across multiple devices.  

Requesting the latest user data

After initializing the Spil Games SDK, it is recommended that you request the latest user data. Normally, this is loaded successfully and is ready to use. However, in some cases merge conflicts can occur which must be resolved. The procedure to do so is described later in this section. The following method can be used to retrieve the user’s data from the Spil Games backend:

Note that if the data cannot be retrieved from the Spil Games backend, it will be loaded from the data stored locally on the device. The following event is triggered when the data is available for use:

After initialization has been completed, it is possible to use and modify the user data using the methods described in Supporting Wallet, Shop and Inventory Control.  

Playing on Multiple Devices

When a second device is being used to play the same game using the same Facebook ID, synchronization errors can occur. If this happens, the following event will be triggered:

Call the RequestUserData() method to re-synchronize the locally stored user data. It is recommended that gameplay is suspended at this point, and does not resume until the user data has been successfully synchronized again. There is a utility method available to show a native dialog that handles this case. It is described in Useful Utility Dialog Methods.

Resolving Merge Conflicts

When a merge error occurs, the following event will be triggered:

This indicates that the current local user data cannot be merged with the remote user data. This must be resolved by either selecting the current local data, the remote server data, or by creating a merge of both data sources. Both local and remote states are returned to resolve the conflict. The following method should be called whenever a merge conflict was resolved:

where:

• mergeData specifies the merged user data.
• mergeType specifies the selected merge resolution type (“remote”, “local”, or “merge”).

If the merge was successfully accepted by the Spil Games backend, the following event will be triggered:

If the merge failed, the following event will be triggered:

In this case, you should retry the merge resolution with the MergeUserData method (described above) using the data returned by this event. The default Spil.Instance.ShowMergeFailedDialog method can also be used to display a native error dialog box that automatically retries as soon as the user clicks the Retry button.

Other Possible Errors

It is not possible for the Spil Games backend to accept user data from two devices at the same time. When the first device sends its changes, a lock is applied to prevent other devices from attempting to send data while the update is in progress. If this happens, the following event will be triggered:

It is recommended that the game waits and then tries to resend the changes later. Since Spil Games SDK version 2.7.0 the OnPlayerDataError() and OnGameStateError() events have been removed. They have been merged into the new OnUserDataError() event. The conditions in which this new event is triggered remain the same as the two replaced events, and the errorMessage payload is also unchanged. The new event has the following format:

A synchronization error can occur when user data is handled through SLOT. It indicates that the data on the Spil Games backend is different from that on the device. In this case, the same flow is required to resolve the merge conflict.

Useful Utility Dialog Methods

The following utility method can be useful during development to display a native dialog box indicating that the user data on the Spil Games backend is different from that on the device:

The following utility method can be used to display a native dialog box asking the user whether to use the remote or local user data:

Note that there will also be a button in the dialog when a mergeButtonText string is provided. It is recommended that this method is only used during development and that a dialog in the style of the game is created for the final product.

The following event is triggered by the ShowMergeConflictDialog() method:

It specifies the choice made by the user: mergeType can be “remote”, “local”, or “merge”. The following utility method can be used to display a native merge failed dialog box asking the user whether they want to retry merging of the user data:

It is recommended that this method is only used during development and that a dialog in the style of the game is created for the final product.

The following method is available for displaying login/logout errors: