1 of 5

Cloud API

List of the Cloud APIs

Overview

The coherence Cloud API allows us to access online services like game accounts, key-value store, matchmaking, and others. It also allows you to get the addresses (IP and port number) of the servers the players can connect to.

The Cloud API requires you to use tokens connected to your coherence project.

API tokens and keys

Portal Token

The token you get when creating a project on the developer portal.

You paste it in the Project Settings.

Runtime Key

Once you have pasted the portal token successfully, you need to fetch the runtime key as well.

You can fetch the Runtime Key by clicking on the down-arrow button on the right side of the input field.

Game account

Creating a player account is the first step towards using the coherence Cloud API. It is required in order to use the rest of the services.

Initialization

To initialize the Cloud API you need to provide a Runtime Key that can be obtained from the settings.

public static class Play
{
    // Initialises the Cloud API
    public static void Init(string RuntimeKey)
}

Callbacks

public static class Auth
{
    public enum Result
    {
        // Successful operation.
        Success,
        
        // Network error, e.g. connection failed.
        NetworkError,
        
        // Server error, e.g. exception on the server.
        ServerError,
        
        // User not found, e.g. when trying to login with non-existing user
        UserNotFound,
        
        // Invalid credentials, e.g. when trying to login with wrong password
        InvalidCredentials,
        
        // Session has expired, e.g. when trying to renew an existing session
        SessionExpired,
        
        // Feature is not enabled, e.g. K/V store
        FeatureDisabled,
    }
       
    // Invoked when completing the login process.
    public delegate void OnSession(Result result);
}

Guest Account

The easiest way to get started is by using a guest account. The only thing that is needed is to call LoginAsGuest. This will create a random username / password combination and will authenticate the player with the coherence Cloud.

Once logged in, the credentials are securely persisted so if the game is restarted the player will be able to log in automatically.

If the game is uninstalled then the account credentials will be lost and a new guest account will be created next time the game is installed.

public static class Auth
{
    // Authenticates the players as a guest.
    // callback - invoked upon completion.
    public static void LoginAsGuest(OnSession callback)
}

User Account

Another alternative is to login with a username and a password. You have to provide the user interface.

public static class Auth
{
    // Authenticates the player with a username and a password.
    // userName   - any combination of letters, numbers, underscore and dash.
    // password   - any combination of ASCII characters
    // autosignup - whether to create an account automatically if it
    //              doesn't exist and the username is not taken
    // callback   - invoked upon completion
    public static void LoginAsUser(string userName, string password,
        bool autosignup, OnSession callback)
}

Example

This example initializes the Cloud API, checks for an existing session and, if no session was found or if it expired, logs in the player as guest.

using Play = Coherence.Runtime;

void OnLogin()
{
    Debug.Log(string.Format("Logged in. PlayerId={0}", Play.Auth.UserId));
}

void Start()
{
    // Initialise the Cloud API
    Play.Play.Init(apiToken);
    
    // Check for existing session
    Play.Auth.IsLoggedIn((res) => {
        if (res == Play.Result.Success)
        {
            // Session resumed
            OnLogin();
        }
        else if (res == Play.Result.SessionExpired || res == Play.Result.UserNotFound)
        {
            // No session found, or session expired. Proceed with normal login.
            Play.Auth.LoginAsGuest((res2) =>
            {
                if (res2 == Play.Result.Success)
                {
                    OnLogin();
                    return;
                }
                UnityEngine.Debug.LogError(string.Format("Could not login. Error={0}", res2));
            });
        }
        else
        {
            UnityEngine.Debug.LogError(string.Format("Could not login. Error={0}", res));
        }
    });
}

Key-value store

The key-value store provides a simple persistence layer for the players.

Coherence.Runtime.KvStore

The player needs need to be logged in to use the Key-value store.

This class provides the methods to set, get and unset key-value pairs. This is executed within the context of the currently logged in player.

public static class KvStore
{
    // Sets a value
    // key: lowercase letters, numbers, underscore, dash
    // val: any string (null is not allowed)
    public static void Set(string key, string val)
    
    // Gets a value
    // key: lowercase letters, numbers, underscore, dash
    public static string Get(string key)
    
    // Unsets a value, removing it from the store
    // key: lowercase letters, numbers, underscore, dash
    public static void Unset(string key)
}

Example

Coherence.Runtime.KvStore.Set("foo", "1");

var foo = Coherence.Runtime.KvStore.Get("foo");
Debug.Log(string.Format("foo={0}", foo)); // foo=1

Coherence.Runtime.KvStore.Unset("foo");

Limitations

Size: there are no limits to the number of stored key/values as long as the total size is less than 256 kB.

Requests: Set/Get/Unset can be called unlimited amount of times but the execution may be throttled.

Matchmaking

The matchmaking provides a powerfull service to group players together in teams.

Coherence.Runtime.Matchmaking

The player needs to be to use matchmaking.

The matchmaking module has only one method.

Example

Key-value store

The key-value store provides a simple persistence layer for the players.

Coherence.Runtime.KvStore

The player needs need to be logged in to use the Key-value store.

This class provides the methods to set, get and unset key-value pairs. This is executed within the context of the currently logged in player.

public static class KvStore
{
    // Sets a value
    // key: lowercase letters, numbers, underscore, dash
    // val: any string (null is not allowed)
    public static void Set(string key, string val)
    
    // Gets a value
    // key: lowercase letters, numbers, underscore, dash
    public static string Get(string key)
    
    // Unsets a value, removing it from the store
    // key: lowercase letters, numbers, underscore, dash
    public static void Unset(string key)
}

Example

Coherence.Runtime.KvStore.Set("foo", "1");

var foo = Coherence.Runtime.KvStore.Get("foo");
Debug.Log(string.Format("foo={0}", foo)); // foo=1

Coherence.Runtime.KvStore.Unset("foo");

Limitations

Size: there are no limits to the number of stored key/values as long as the total size is less than 256 kB.

Requests: Set/Get/Unset can be called unlimited amount of times but the execution may be throttled.

Game account

Creating a player account is the first step towards using the coherence Cloud API. It is required in order to use the rest of the services.

Initialization

To initialize the Cloud API you need to provide a Runtime Key that can be obtained from the settings.

public static class Play
{
    // Initialises the Cloud API
    public static void Init(string RuntimeKey)
}

Callbacks

public static class Auth
{
    public enum Result
    {
        // Successful operation.
        Success,
        
        // Network error, e.g. connection failed.
        NetworkError,
        
        // Server error, e.g. exception on the server.
        ServerError,
        
        // User not found, e.g. when trying to login with non-existing user
        UserNotFound,
        
        // Invalid credentials, e.g. when trying to login with wrong password
        InvalidCredentials,
        
        // Session has expired, e.g. when trying to renew an existing session
        SessionExpired,
        
        // Feature is not enabled, e.g. K/V store
        FeatureDisabled,
    }
       
    // Invoked when completing the login process.
    public delegate void OnSession(Result result);
}

Guest Account

Once logged in, the credentials are securely persisted so if the game is restarted the player will be able to log in automatically.

If the game is uninstalled then the account credentials will be lost and a new guest account will be created next time the game is installed.

public static class Auth
{
    // Authenticates the players as a guest.
    // callback - invoked upon completion.
    public static void LoginAsGuest(OnSession callback)
}

User Account

Another alternative is to login with a username and a password. You have to provide the user interface.

public static class Auth
{
    // Authenticates the player with a username and a password.
    // userName   - any combination of letters, numbers, underscore and dash.
    // password   - any combination of ASCII characters
    // autosignup - whether to create an account automatically if it
    //              doesn't exist and the username is not taken
    // callback   - invoked upon completion
    public static void LoginAsUser(string userName, string password,
        bool autosignup, OnSession callback)
}

Example

This example initializes the Cloud API, checks for an existing session and, if no session was found or if it expired, logs in the player as guest.

using Play = Coherence.Runtime;

void OnLogin()
{
    Debug.Log(string.Format("Logged in. PlayerId={0}", Play.Auth.UserId));
}

void Start()
{
    // Initialise the Cloud API
    Play.Play.Init(apiToken);
    
    // Check for existing session
    Play.Auth.IsLoggedIn((res) => {
        if (res == Play.Result.Success)
        {
            // Session resumed
            OnLogin();
        }
        else if (res == Play.Result.SessionExpired || res == Play.Result.UserNotFound)
        {
            // No session found, or session expired. Proceed with normal login.
            Play.Auth.LoginAsGuest((res2) =>
            {
                if (res2 == Play.Result.Success)
                {
                    OnLogin();
                    return;
                }
                UnityEngine.Debug.LogError(string.Format("Could not login. Error={0}", res2));
            });
        }
        else
        {
            UnityEngine.Debug.LogError(string.Format("Could not login. Error={0}", res));
        }
    });
}