Spil SDK – Social Login Feature
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 lose 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, do the following:
- Download the latest version of the Facebook SDK. It is available from: https://developers.facebook.com/docs/ios/downloads
- Add the Facebook SDK to your IDE project as described in https://developers.facebook.com/docs/ios/getting-started. Use the Facebook app ID provided by your Spil Games Account Manager.
Implementing the Facebook Login
Follow the implementation stated at this Facebook documentation: https://developers.facebook.com/docs/facebook-login/ios/
To get the access token use the steps described here: https://developers.facebook.com/docs/facebook-login/ios/advanced#access-tokens
Implementing the Spil Games SDK Login
Before implementing any of the methods, register the following callbacks:
Use the following method to login the user:
where:
- socialProvider should be “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.
- socialToken should be the Facebook access token retrieved earlier from Facebook.
Success
After a successful user login, the parameters are:
- 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 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.
| Code | Description |
|---|---|
| 32 | Invalid Spil Games token! Please login again. |
| 33 | Event requires user login. |
| 34 | The provided social token could not be verified by the Spil Games backend. Please login again. |
| 35 | The user already has a social provider account. Please first logout. |
| 36 | The specified social ID is already linked to another user. |
Checking if a user is already logged in:
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).
Logout and 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 user. Each game play 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.
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 Facebook login process should be re-initiated after this event.
Resetting the User Data
The user data (described in Wallet, Shop & Inventory) 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.
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.
After initialization has been completed, it is possible to using and modifying the use data using the methods described in Wallet, Shop & Inventory).
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. Call the requestUserData() method to re-synchronize the locally stored user data. It is recommended that game play 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”).
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.
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.
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 callback OnRequestLogin is triggered by the showMergeConflictDialog(…) method.
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: