Get started with Leaderboards#

The first step in using Leaderboards is to learn how to implement the feature. This section describes how to set up Leaderboards for your project.

Unity Dashboard#

You can access Leaderboards in the Unity Dashboard. You can find Leaderboards after selecting LiveOps in the Main Menu.

The Dashboard is used to create and manage your leaderboards and view their entries.

Unity SDK installation and setup#

The Leaderboards SDK requires Unity 2020.3.0 or newer.

Install Leaderboards SDK#

You can install the Package through the Unity Editor.

Navigate to Window > Package Manager and select Unity Registry in the Packages dropdown on the top left. You can either:

• Search for Leaderboards in the search bar on the top right.
• Add the package by name. Open the dropdown indicated by +, and select "Add package by name...". Search the SDK package ID, "com.unity.services.leaderboards", without its version.

After installation the Leaderboards SDK is available in Unity scripts from the Unity.Services.Leaderboards namespace:

C#

using Unity.Services.Leaderboards;

Install Authentication SDK#

The Leaderboards package relies on the Authentication package. The Unity Authentication service creates an account to persist player scores where you can use anoynymous sign-in or platform-specific authentication.

The Authentication package is installed as a dependency when you install the Leaderboards package. For information on installing packages manually, refer to Install a package from a registry.

After installation the Authentication SDK is available in Unity scripts from the Unity.Services.Authentication namespace:

C#

using Unity.Services.Authentication;

Link your Unity project#

Once installed, the Authentication package prompts you to link your Unity project to a Unity Game Services Project ID, as demonstrated below. Follow the instructions in the prompt on the screen to link your project.

If you do not see this prompt, follow these steps to link your Unity project to a Project ID:

• In the Unity Editor, select Edit > Project Settings....
• Select Services,
  • Sign in if you have an Unity ID.
  • Otherwise, select Create a Unity ID.
• Select your project.
• Select Link.

Initialize the SDKs and authenticate the player#

You must initialize the Leaderboards SDK and its dependencies from inside a Unity script lifecycle callback before use. The following example uses the Awake callback. This is done by initializing all installed services via the Core SDK by calling await UnityServices.InitializeAsync();, available from the Unity.Services.Core namespace.

After the SDK initialization is complete, the player is authenticated. The following example uses anonymous authentication to create an anonymous account for the player to persist their scores. Other methods of authentication are available as outlined in the Unity Authentication documentation.

C#

using UnityEngine;
using Unity.Services.Core;
using Unity.Services.Authentication;

public class LeaderboardsSample : MonoBehaviour
{
  private async void Awake()
    {
        await UnityServices.InitializeAsync();
        await AuthenticationService.Instance.SignInAnonymouslyAsync();
    }
}

Next steps#

After completing the above steps the Leaderboards SDK is now ready to use from the Unity.Services.Leaderboards namespace. Review the features, SDK documentation, and the SDK sample to find out more about the Leaderboards feature set and how to use them.

Leaderboards in the UGS CLI#

The Unity Gaming Services (UGS) command line interface provides a scalable and automatable alternative to the Unity Dashboard and improves your team's workflows and productivity. The CLI is used to manage, test and deploy your Leaderboards configuration.

See the documentation on how to install and use the CLI.

Leaderboards REST API#

Developers that do not use Unity can access APIs via web endpoints or REST APIs. REST APIs provide more flexibility and allow you to automate your workflows by using your favorite language and game development engine.

The Leaderboards service provides the following REST APIs:

• Leaderboards Player API for performing player actions (e.g. submitting a score or fetching scores).
• Leaderboards Admin API for performing admin actions (e.g. creating or updating a leaderboards, deleting or resetting scores) and is also used to perform player actions on behalf of a player.

Additional resources#

• Unity Dashboard
• Package Manager
• Unity Authentication