Get started with Leaderboards

Set up and integrate Leaderboards into your project using the Unity Dashboard, Software Development Kit, CLI, or REST API.

Read time 4 minutes

Last updated 2 months ago

Warning

The Digital Services Act (DSA) requires Unity to notify our customers’ end users if Unity takes an action that impacts those end users under the DSA. To comply with this requirement, if you use Unity Gaming Services (UGS) products that rely on the Unity Authentication Service, you must integrate the notification API. For more information on DSA, refer to the Digital Services Act - compliance update. To make your game compliant, refer to DSA notifications.

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.
Leaderboards Authoring	Learn how to deploy Leaderboards configurations from the editor using the Deployment window.
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 set up and manage Leaderboards in the Unity Dashboard:

In the Unity Dashboard, go to Development > Products.
Select Leaderboards.

When you launch Leaderboards for the first time, this adds Leaderboards to the Shortcuts section on the sidebar and opens the Leaderboards Overview. You can use the Unity Dashboard 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 in 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 Gaming Services Project ID. Follow the instructions in the prompt on the screen to link your project. Alternatively, follow the steps to Link your project in the Unity Editor.

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, Unity SDK tutorial, 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.

Deploy a Leaderboards configuration

To make your Leaderboards configurations accessible to the game client, you must deploy the configuration to the Leaderboards service. Refer to write configuration to learn more about script deployment.

Configure the UGS CLI

To get started with the UGS CLI, perform the following steps:

Install the UGS CLI.

Configure your Project ID and Environment as such:

ugs config set project-id <your-project-id>

ugs config set environment-name <your-environment-name>

Configure a Service Account with the required roles for Leaderboards and environments management. Refer to Get Authenticated.

Deploy the script

Run the following command:

ugs deploy <path-to-configuration-file>

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, such as submitting or fetching scores.
Leaderboards Admin API for performing admin actions, such as creating or updating leaderboards, and deleting or resetting scores. It is also used to perform player actions on behalf of a player.

Leaderboards Authoring

This module allows users to author, modify, and deploy Leaderboard configuration assets directly from the Unity Editor.

Note

Leaderboards Authoring is only supported on Unity 2021.3 and above.

Deployment Window

The Deployment Window is a core feature of the Deployment package. The purpose of the Deployment Window is to allow all services to have a single cohesive interface for Deployment needs. The Deployment Window provides a uniform deployment interface for all services. It allows you to upload cloud assets for your respective cloud service. For more information, refer to the com.unity.services.deployment package documentation.

Create Leaderboards Assets

Use the right click menu in the Project window to create a Leaderboard asset. The Deployment Window automatically detects these files to be deployed at a later time. For more information on how to create and modify Leaderboards Assets, refer to Leaderboards assets.

Documentation

Development

User Acquisition

Monetization

Industry