Develop

Leaderboards sample overview

Updated: May 8, 2026

Overview

This sample demonstrates the Horizon Platform SDK’s leaderboard functionality through a minimal Android application. The sample reads leaderboard definitions and entries, submits scores, and handles pagination using the SDK’s coroutine-based API surface. View the sample source code on GitHub⁠.

What you will learn

Reading leaderboard definitions and retrieving ranked entries

Submitting scores with and without supplementary metrics

Querying leaderboard entries for specific user IDs

Handling paginated results from the SDK

Integrating the Horizon Platform SDK with Jetpack Compose and StateFlow

Requirements

Meta Quest device with developer mode enabled

Android Studio Ladybug or later

Horizon Platform SDK configured for your application

For detailed platform setup, see the Horizon Platform SDK setup guide.

Get started

The sample is available in the horizon-platform-sdk-samples⁠ repository under the leaderboards/ directory. Open the project in Android Studio and configure your application ID in MainActivity.kt by replacing the APPLICATION_ID property getter. For detailed build instructions, see the repository README⁠.

Explore the sample

File	What it demonstrates	Key concepts
`MainActivity.kt`⁠	Service connection and UI layout	`HorizonServiceConnection` setup, two-column Compose layout with controls and output
`LeaderboardsViewModel.kt`⁠	All five leaderboard API methods	Read operations (`get`, `getEntries`, `getEntriesByIds`), write operations (`writeEntry`, `writeEntryWithSupplementaryMetric`), pagination handling

Runtime behavior

When you launch the sample, you see a two-column layout. The left column contains input controls: a text field for the leaderboard name (pre-populated with sample_leaderboard_visible), preset buttons for switching between leaderboards, a score stepper for adjusting values, and buttons for each of the five SDK methods. The right column displays operation results as formatted text or error messages.

Key concepts

Service connection

The sample establishes a connection to the Horizon Platform Service before rendering the UI:

HorizonServiceConnection.connect(
    APPLICATION_ID,
    this@MainActivity.applicationContext,
    lifecycleScope,
)

See MainActivity.kt⁠.

Reading leaderboard data

The sample demonstrates three read methods:

get() retrieves leaderboard definitions with metadata

getEntries() fetches ranked entries with scores and user IDs

getEntriesByIds() queries entries for specific user IDs

All three return paginated results that require calling fetchInitialPage() followed by getFetchedPages().

See LeaderboardsViewModel.kt⁠.

Writing scores

The sample provides two write methods:

leaderboards.writeEntry(name, score, null, null)

writeEntry() submits a score to a leaderboard. writeEntryWithSupplementaryMetric() adds a supplementary metric alongside the primary score.

Pagination pattern

All read methods follow a consistent pagination approach: call fetchInitialPage() on the paged results object, retrieve the fetched pages collection, and extract the first page’s contents. The sample only processes the initial page — multi-page iteration is not demonstrated.