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:
- Add the Leaderboard custom component to the hierarchy within Orthographic Camera.
- Ensure the Render Layer matches with the Orthographic Camera.
- 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.
- Subscribing on score updates
- Submitting score
- Using async functions
//@input Component.ScriptComponent Leaderboard
script.Leaderboard.onLeaderboardRecordsUpdated.add(
(leaderboardRecordsWrapper) => {
print(leaderboardRecordsWrapper.userRecords);
print(leaderboardRecordsWrapper.currentUserRecord);
}
);
//@input Component.ScriptComponent Leaderboard
/*
For example some custom logic for calculating score
*/
let score = Math.ceil(Math.random() * 100); // creating random score
script.Leaderboard.submitScore(score);
//@input Component.ScriptComponent Leaderboard
script.Leaderboard.getLeaderboard()
.then((leaderboard) => {
print('Leaderboard loaded');
print('Leaderboard ' + leaderboard);
})
.catch(() => {
print('Error loading leaderboard');
});
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.
- Usage example
- Declarations
//@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));
});
type LeaderboardInitializationOptions = {
name: string,
userType: Leaderboard.UsersType,
scoreOrdering: Leaderboard.OrderingType,
scoreResetInterval: ScoreResetIntervalOption,
userLimit: number,
useTimer: boolean,
leaderboardStartDate?: string //format "mm/dd/yyyy"
}
enum ScoreResetIntervalOption = {
Day = 0,
Week = 1,
Month = 2,
Year = 3
}
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.
- JavaScript
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:
- UserContextSystem:
requestBirthdate
requestBirthdateFormatted
requestCity
- Text component:
- Reading from text property when Dynamic Text is being used.
- ProceduralTextureProvider:
getPixels
- DepthTextureProvider:
getDepth
- DeviceTracking:
hitTestWorldMesh
raycastWorldMesh
getPointCloud
- DeviceLocationTrackingComponent:
distanceToLocation
- ScanModule
- OutputPlaceholder:
data
- MicrophoneAudioProvider:
getAudioFrame
- TensorMath:
textureToGrayscale
- LocalizationSystem:
getLanguage