Unity3D SDK
Download the GameSparks Unity SDK Package.
SDK downloaded from Unity Asset Store? If you've downloaded the GameSparks SDK directly from the Unity Asset Store, please register for an account on the GameSparks platform. This is where you'll build and configure your game.
Use this page to work through the steps for integrating the GameSparks Unity 3D SDK into a new Unity Project:
For the current version of the SDK and a version release history see:
The source repository for the Unity library can be found here:
Using the SDK
The following steps will show in detail how to integrate the GameSparks Unity 3D SDK into a new Unity Project.
Creating a new Unity project
Downloading the new SDK
The GameSparks Unity3D SDK is provided as a standard unity package and can be downloaded above.
Importing the SDK
Select the package you just downloaded, you will then be presented with the following screen. Make sure that all items are ticked and click Import.
Your project folder should now contain Assets/GameSparks and Assets/Plugins.
Configuring the SDK
To configure the SDK for use with your game, select GameSparks -> Edit Settings from the menu bar.
GameSparks not Showing? If the GameSparks menu item is not visible, click another one and it will appear. This is a nuance of menu items in Unity - clicking the other item rebuilds the menu and brings in the GameSparks item.
You will then be presented with an Editor pane that allows you to configure the SDK for your needs.
Fill the pane with the following settings:
1. GameSparks Api Key and Secret:
Api Key – The GameSparks API Key value from the Game Overview page in the portal.
Api Secret – The GameSparks API Secret value from the Game Overview page in the portal. You can click Show at the right-hand side of this field to reveal it and then click Copy:
2. Credential - Specify the Credential you want to use when connecting to the GameSparks platform. You might want to use a custom Credential you've created for your game's players and to check the permissions set defined by that custom Credential. See the Credentials page for more details on creating and configuring Credentials.
3. Preview Build - Select this option when you want to run the SDK against the unpublished configuration.
4. Debug Build - Select this option to get extended debugging out of the SDK (useful for support purposes).
5. Get My Custom SDK - This will check your GameSparks game for custom Events, Leaderboards, and so on, and create a C# file with custom functions.
6. Update SDK - This will get the latest GameSparks SDK version.
7. Test Configuration - You can use this to submit requests to the GameSparks platform and test your game's configuration. See the following section for details.
Testing your Configuration
Click the Test Configuration button in the GameSparks settings editor. This will open the test scene:
- You'll be prompted to save your current scene.
- Using the test scene, you'll be able to submit requests to GameSparks from within the editor and test your configuration.
- You should see JSON messages being sent and received by Unity from the service.
Authenticating against the service
On the first run, you will see the label “NOT AUTHENTICATED”. To send requests to the platform, you need to be authenticated. There are a number of requests that can authenticate you:
RegistrationRequest – Allows a new user to be created with a username & password.
AuthenticationRequest – User to authenticate using details previously provided in a RegistrationRequest.
DeviceAuthenticationRequest – Uses the unique identifier for the device to create an anonymous user, the Unity SDK deals with all the parameters required for this.
FacebookConnectRequest – Uses a Facebook authentication token to register and or authenticate with the platform - this requires you to have set up an app on: https://developers.facebook.com/
The test scene contains a button to do a device authentication - DeviceAuthenticationRequest. Click this button and the current player will be authenticated:
Automatic Authentication! Note that when you set up a new project with the Unity SDK and perform an authentication request, an authentication token is stored locally. If you then start your scene again and do not call an authentication request, one is still performed in the background, authenticating the user and using the stored authentication token.
Adding the SDK to your Own Game
To add to your own game, you need to add the GameSparksUnity class to one of your own components. A good way to do this is to create an Empty GameObject, name it GameSparks, and drag the GameSparksUnity.cs script onto the GameSparks GameObject.
Note: It’s best to do this on the very first scene your game load, so you can begin analytics or start logging your user in as soon as possible.
You only need to add it to one scene. GameSparksUnity.cs uses DontDestroyOnLoad(), which ensures that the script will live throughout your game’s scene changes.
Sending Requests
You’ll need the following using directives:
1
2 using GameSparks.Api.Requests;
3 using GameSparks.Api.Responses;
4
Each request type in the platform now has it’s own class. To send an authentication request, you can use the following:
1
2 AuthenticationResponse authResponse = new AuthenticationRequest ().SetUserName ("gabriel").SetPassword ("password").Send ();
3
4 if (authResponse.HasErrors) {
5 //It didn't work
6 } else {
7 //It worked!!
8 }
9
There are 4 variants of the Send method. Where “OUT” is the specific response type, the request will return
public void Send (Action<OUT> callback)
- Async send method, the provided action will be invoked when the response is received, the action should check for errors in the response using response.HasErrors.
public void Send (Action<OUT> callback, int timeoutSeconds)
- As above, with user provided timeout value.
public void Send (Action<OUT> successCallback, Action<OUT> errorCallback)
- Async send method, the SDK will invoke the correct action based on the HasErrors property of the reponse.
public void Send (Action<OUT> successCallback, Action<OUT> errorCallback, int timeoutSeconds)
- As above, with user provided timeout value.
All async methods are null safe. You can pass a null action in if you do not want to do anything on response:
new DeviceAuthenticationRequest ().Send (null);
All responses from the SDK are also strongly typed, so you can use your IDE’s auto complete to the available properties.
Sending JSON
To send a JSON Object as part of a request you can construct a GSRequestData object and add the attributes to it. This is useful for both setting JSON on events, or setting the scriptData attribute on requests.
1
2 GSRequestData sd = new GSRequestData ().AddNumber ("somekey", 1).AddString ("another", "data");
3
4 AuthenticationResponse authResponse = newAuthenticationRequest ().SetUserName ("gabriel").SetPassword ("password").SetScriptData(sd).Send ();
5
6 if (authResponse.HasErrors) {
7 //It didn't work
8 } else {
9 //It worked!!
10 }
11
Registering for messages
Using the SDK, you can listen for all async messages sent to the SDK using GameSparks.Api.GSMessageHandler and setting the _AllMessages Action:
1
2 GSMessageHandler._AllMessages = (GSMessage e) => {
3 Console.WriteLine ("ALL HANDLER " + e.MessageId);
4 }
5
If you want to be more selective, you can listen to each message with an individual action. Each message type has a “Listener” property that you can set, and the SDK will execute it if a message of that type is received. Using this mechanism allows you to be passed a strongly typed object, removing the need to query the message for it’s type information.
2 ScriptMessage.Listener = ((ScriptMessage message) => { Debug.Log("We just got a ScriptMessage"); });
3
4 FriendMessage.Listener = ((FriendMessage message) => { Debug.Log("We just got a ScriptMessage"); });
5
SDK Current Version
V5.6.5.214 - June 15th, 2018
- Updated API
- Removed old REST API functionality
SDK Version Release History
V5.6.4.207 - April 19th, 2018
- Fixed an issue that occurred during reconnection to the GameSparks server
V5.6.3.205 - March 7th, 2018
- Fixed obsolete SamsungTVPlayer warning on Unity 2017.3
- Added Real-Time over Websockets for Xbox One
- Fixed durable requests
V5.6.2.189 - January 17th, 2018
- Fixed UWP Support
- Fixed crash that could happen when re-compiling Windows
V5.6.1.172 - January 11th, 2018
- Fixed durable requests
- Fixed retries
- Fixed WebGL plugin
- Other minor bugs addressed
V5.6.0.156 - December 7th, 2017
- New retries connection system
- Fixed application quit on Windows platform
- Fixed GetUploadUrlRequestAndUploadFile issue
- Fixed floating numbers on WebGL
- Other minor bugs addressed
V5.5.7.137 - October 26th, 2017
- Enabled Tizen support
- Fixed old crash application quit on Windows standalone
- Added GetBooleanList method in GSData
V5.5.6.130 - September 18th, 2017
- Enabled RT module for WebGL platform
- Fixed some issues on Unity2017
- Fixed DeviceStats for tvOS
- Fixed DeviceID for Android on Unity 5.3
V5.5.5.114 - August 15th, 2017
- Fixed the clash between DnsEndPoint class implementation and the corresponding .NET 4.6 DnsEndPoint class implementation on Unity 2017
V5.5.5.108 - July 13th, 2017
- Updated for Unity 2017
V5.5.5.92 - June 1st, 2017
- Added callback function to verify certificate from server
- Updated API
- Added support for Nintendo Switch
- Minor bug fixes
V5.5.4.66 - April 24th, 2017
- Fixed an issue with debug output on WebGL
- Fixed tokens parsing in GSJson
V5.5.4.59 - April 10th, 2017
- Fixed Inspector Window
- Completed support for floating point numbers in GSJson
- Fixed other minor bugs
V5.5.4.48 - April 4th, 2017
- Added splash screen
- Updated API
- Added DeviceStats
- Fixed several minor bugs
V5.5.3.204 - February 20th, 2017
- Updated API
- Fixed DeviceID (for PS4 and XBox One) and DeviceOS attributes.
V5.5.1.198 - January 27th, 2017
- Fixed a crash that occurred when a user sent requests after a disconnection event on Win8/10
- Updated API
- Added pdb files
V5.5.0.189 - January 1st, 2017
- Added ApiDomain and ApiCredential support
- Fixed Plugins folder and its files
- Fixed the support for Windows 10 plus IL2CPP Scripting Backend
- Resolved several other minor bugs
V5.4.0.104 - November 25th, 2016
- Resolved Meta file issues
- Restored native code for Xbox one
- Addressed CultureInfo bug in GSJson file
V5.4.0.91 - November 8th, 2016
- Resolved tendency to hang in Windows Unity Editor
- Fixed IPv6
- Addressed other minor bugs
V5.4.0 - September 7th, 2016
- Remove native plugins for sockets
- Use TLSv1.2 for all socket connections
- Add update checker to keep SDK up to date
- API Updates to V67
V5.3.3 - March 1st, 2016
- Added PS4 Support (Contact customer services for PS4 specific unitypackage).
- Added XBOX One Support (Contact customer services for XBOX specific unitypackage).
- Resolved connection pauses with malformed query string.
- API Updates to include all Server requests for V59
V5.3 - August 19th, 2015
- Fixed potential deadlock on WP8 devices.
- Durable queue updates to enforce processing in order.
- xcodeproj post processing updates for new project version.
- API Updates to include all Server requests.
V5.2
- IL2CPP updates.
- xcodeproj post processing modified to support append and replace.
- API Updates to include all Server requests.
V5.1
- Per player durable queue, this means a request sent with durable as a player will only ever go as that player.
- Unity 5.1.0 Support (There is currently a defect in Unity preventing WP8 builds).
- API Updates to include all Server requests.
- Ability to have multiple GSInstance objects to aid testing
V5.0
- Full Unity 5 support
- WebGL
- IL2CPP
- Version number visibility within Unity.