Skip to main content
Version: 5.x
Supported on
Snapchat

Leaderboard

Leaderboard custom component​

Leaderboard custom component is a real-time ranking component that displays user scores, helping users track their progress and compare with friends and users worldwide. Highly customizable, and easy to set up.

Minimal Snapchat app version for the Leaderboard feature is 13.8

Using the Leaderboard Component​

To add the Leaderboard Component to your Lens, go to the Asset Library and find the Leaderboard Component in the Custom Components section.

Once you click the Install button, you can find this component in the Asset Browser and add it to your resources to build the Lens.

In the Scene Panel:

  1. Add the Leaderboard custom component to the hierarchy within Orthographic Camera.
  2. Ensure the Render Layer matches with the Orthographic Camera.
  3. Add Canvas component to the Orthographic Camera

Customizing each entry​

This custom component is distributed as editable. Right click to unpack and edit.

Each entry is customizable by unpacking the component. Double clicking on the LeaderboardEntry ObjectPrefab opens the scene. For even bigger customizations it’s also possible to change the LeaderboardEntry script, which is responsible for rendering each entry/score in the leaderboard.

//@input Component.ScriptComponent Leaderboard

script.Leaderboard.onLeaderboardRecordsUpdated.add(
  (leaderboardRecordsWrapper) => {
    print(leaderboardRecordsWrapper.userRecords);
    print(leaderboardRecordsWrapper.currentUserRecord);
  }
);

Developers don’t have access to Snapchatters' scores/ranks.

Developers are not responsible for user score being valid/invalid.

API​

visible : boolean

Shows is leaderboard is visible.

show() : void

Shows table with scores.

hide() : void

Hides table with scores.

submitScore(score: number) : void

Submits score to leaderboard.

getSideSwitcher() : SideSwitcher

Returns SideSwitcher custom component.

initializeWithOptions(leaderboardInitializationOptions: LeaderboardInitializationOptions) : void

Initializes leaderboard from code.

//@input Component.ScriptComponent Leaderboard

script.Leaderboard.getSideSwitcher().hide();
script.Leaderboard.initializeWithOptions({
  name: 'name',
  userType: Leaderboard.UsersType.Friends,
  scoreOrdering: Leaderboard.OrderingType.Descending,
  userLimit: 10,
  scoreResetInterval: script.Leaderboard.ScoreResetIntervalOption.Week,
  useTimer: true,
  leaderboardStartDate: '9/27/2024',
});
script.Leaderboard.setLeaderboardName('Custom leaderboard');

const tap = script.createEvent('TapEvent');
tap.bind(() => {
  script.Leaderboard.submitScore(Math.ceil(Math.random() * 100));
});

async getLeaderboard() : Promise<Leaderboard>

Returns Leaderboard object.

async getCurrentUser() : Promise<SnapchatUser>

Returns the SnapchatUser object for the current user.

async getCurrentUserBitmoji() : Promise<Texture>

Returns texture with current user bitmoji sticker.

API Events​

onLeaderboardRecordsUpdated : Event<LeaderboardRecordsWrapper>

Triggers when any records are updated and returns a LeaderboardRecordsWrapper object. This object contains two properties:

  • userRecords: UserRecord[] – An array of records for all players.
  • currentUserRecord: UserRecord | null – The record for the current user, or null if none exists.

onShow : Event<>

Triggers when full leaderboard is opened.

onHide : Event<>

Triggers when full leaderboard is closed.

If friends haven’t played a game, the leaderboard will display a fallback placeholder. If the list of friends is large - the leaderboard becomes scrollable. It’s also possible to add a Global Leaderboard, a custom component that displays only the first 10 UserRecords.

Developers shouldn't tie meaningful awards to leaderboard scores because this is not a contest platform.

Inputs​

Leaderboard Name - unique name for the leaderboard;

Auto Initialize - if selected, leaderboard is going to be initialized on first frame with parameters provided. If not, initializeWithOptions(leaderboardInitializationOptions: LeaderboardInitializationOptions)should be called;

Score Reset Interval - options to select how frequently leaderboard is going to be reset;

Leaderboard Start Date - date in mm/dd/yyyy format which is going to be used to determine offset for resetting scores. Leaderboard is going to be working before this date, start date is only used as a date when the leaderboard is going to reset. For example, when Score Reset Interval is set to Weekly and a start date is 8/15/2024 the closest to two challenges to this date are going to be from 8/8/2024-8/15/2024 and 8/15/2024-8/22/2024;

Score Ordering - Ascending order or Descending order;

User Limit - how many User Records to show. For global leaderboards, the limit is automatically set to 10, and for friends this limit is set to 50;

Custom Sticker Id - specify a Bitmoji sticker you want to display at the top of the leaderboard, or leave it blank for a selfie;

Background Customization - option how the full leaderboard is going to look like. Can be None, Bitmoji, Texture. If ScreenTexture is selected additional animation is going to be added;

Customizable Prefabs - when the component is unpacked, it is possible to customize the appearance of the leaderboard;

Use Single Badge - also want to show the current user's result? It’s possible with this parameter set to true;

Changing the Leaderboard name will reset the Leaderboard.

Customizing each entry​

This custom component is distributed as editable. Right click to unpack and edit.

Each entry is customizable by unpacking the component.


Double clicking on the LeaderboardEntry ObjectPrefab opens the scene.


For even bigger customizations it’s also possible to change the LeaderboardEntry script, which is responsible for rendering each entry/score in the leaderboard.

script.setEntryIndex(index: number) - receives index of the current entry. Each entry is reusable for multiple indexes so this value can change

script.setUserRecord(userRecord: UserRecord) - receives UserRecord and determines which text component to enable

script.setBitmoji(bitmoji: Texture) - receives a Bitmoji sticker texture

Leaderboard Template

Leaderboard template is showcasing Leaderboard Custom Component.

On each tap, multiple visual effects are played. You can easily customize them just by adding and removing them from the MainLogic script component.

In the example, each tap triggers multiple scripts with their own response.

Duration of game is controlled by TweenValue progressTween so the duration can be changed in just one click. Also, each click is customizable using GPU Particles, which can fully change the lens appearance just in a couple of clicks.

Restrictions​

When Using Leaderboard Lenses, some APIs will be restricted in order to protect the user’s privacy. The following APIs will be disabled:

Was this page helpful?
Yes
No