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.
Topic | Description |
---|---|
Leaderboards in the Unity Dashboard | Learn where to find Leaderboards in the Unity Dashboard. |
SDK Installation & Setup | Learn how to link your project with a Unity Gaming Services project and install and setup the SDK. |
Leaderboards in the UGS CLI | Learn how to interact with Leaderboards using the Unity CLI. |
Using the Leaderboards REST API | Learn about the available REST API for accessing Leaderboards without the Unity SDK. |
Using Leaderboards with Cloud Code | Learn how to access Leaderboards using the Cloud Code service. |
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.
Note: There is a Samples
section where you can import example code to your project to assist you calling the Leaderboards SDK from your game.
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.