Sign In
Register

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:

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:

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)

public void Send (Action<OUT> callback, int timeoutSeconds)

public void Send (Action<OUT> successCallback, Action<OUT> errorCallback)


public void Send (Action<OUT> successCallback, Action<OUT> errorCallback, int timeoutSeconds)

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

SDK Version Release History

V5.6.4.207 - April 19th, 2018

V5.6.3.205 - March 7th, 2018

V5.6.2.189 - January 17th, 2018

V5.6.1.172 - January 11th, 2018

V5.6.0.156 - December 7th, 2017

V5.5.7.137 - October 26th, 2017

V5.5.6.130 - September 18th, 2017

V5.5.5.114 - August 15th, 2017

V5.5.5.108 - July 13th, 2017

V5.5.5.92 - June 1st, 2017

V5.5.4.66 - April 24th, 2017

V5.5.4.59 - April 10th, 2017

V5.5.4.48 - April 4th, 2017

V5.5.3.204 - February 20th, 2017

V5.5.1.198 - January 27th, 2017

V5.5.0.189 - January 1st, 2017

V5.4.0.104 - November 25th, 2016

V5.4.0.91 - November 8th, 2016

V5.4.0 - September 7th, 2016

V5.3.3 - March 1st, 2016

V5.3 - August 19th, 2015

V5.2

V5.1

V5.0

Privacy | Site Terms | Cookie preferences | © Game Sparks Technologies Ltd 2021
2022-03-31T23:23