Stellar Loyalty Developer Portal

« Back to Kits References

The Leaderboards kit displays member rankings across multiple metrics, and allowing members to view their position in the rankings.

To include the Leaderboard kit, open the Gradle Scripts | build.gradle (Module: app) and add the following to the dependencies section:

   implementation 'com.cheetahdigital.android:leaderboard:<version>'

On this page:

Overview
Theme Customization
Layout Customization
Fully Custom UI

Overview

Cheetah Digital supports multiple leaderboards per program: the marketer uses the Marketing Console to define the parameters for each leaderboard.

By default, the main_leaderboard will be used. To override this, define the internal name of the leaderboard that you want to use, add the following in the strings.xml file:

<!-- Leaderboard Configuration -->
<string name="leaderboard_main">main_leaderboard</string>
<integer name="top_leaderboard_size">30</integer>

Launching the Leaderboard Activity

Add the following Activities that will be used by this kit to the app’s AndroidManifest.xml:

 <activity android:name="com.cheetahdigital.leaderboard.ui.leaderboard_list.LeaderboardsListActivity"
     android:exported="false">
     <intent-filter>
         <action android:name="${applicationId}.BOARDS_LIST"/>
         <category android:name="android.intent.category.DEFAULT"/>
     </intent-filter>
 </activity>
   
<activity android:name="com.cheetahdigital.leaderboard.ui.leaderboard_detail.LeaderboardDetailsActivity"
     android:exported="false">
     <intent-filter>
         <action android:name="${applicationId}.BOARD_DETAILS"/>
         <category android:name="android.intent.category.DEFAULT"/>
     </intent-filter>
</activity>

Then start the activity with use of Actions:

 Intent intent = new Intent();
 intent.setAction(Actions.BOARD_DETAILS);
startActivity(intent);

 Intent intent = new Intent();
 intent.setAction(Actions.BOARD_LIST);
startActivity(intent);

Theme Customization

The Kits leverage on Android’s built-in support for Styles and Themes. Overriding the Styles and Themes of the app will also change the corresponding Views used in this kit.

Layout Customization

Customizing Layouts via XML

You can customize the layouts of the different screens in the Leaderboards kit by copying the layout XML’s and overriding as desired. To read more about style-able layout XMLs, please visit the Layout Customization via XML document. The XML’s used are:

activity_boards_list - container layout used for fragment that displays the leaderboard list
fragment_boards - layout used for fragment that displays leaderboard list
activity_board_details.xml - layout for the leaderboard screen
list_item_all_leaderboards.xml - list item layout for the leaderboard

Customizing Layouts via Code

There are certain cases that you may want to use a highly-customized layout for an Activity/Fragment. To read more about this, please visit the Layout Customization via Code document. The classes used for the Leaderboards kit are:

LeaderboardDetailsActivity and LeaderboardPagerFragment for displaying both the top and friends ranking in a ViewPager,
LeaderboardFragment for displaying the rankings for a specific leaderboard,
LeaderboardsListActivity and LeaderboardsListFragment for displaying the list of leaderboards.

Customizing Handlers

There are certain cases that you may want to change the default behavior of an Activity/Fragment. You can achieve that by extending the Activity/Fragment that you want to customize and overriding as necessary.

Handlers may occur in different places:

Adapters - for lists
Member variables inside Activities or Fragments
Member variables inside custom Widgets - for stand-alone custom Widgets

To start with, you may look at the classes mentioned in Customizing Layouts via Code, along with LeaderboardsListAdapter which is used to display the list of leaderboards.

Fully Custom UI

If changing the layout does not suffice for your case, you can always do a full customization. You can use the following method from the LeaderboardAPI class:

Get Leaderboards

getLeaderboards(LeaderboardParams leaderboardParams, boolean clearCache, ListenerModel<BaseModel<BoardData>, BoardData> listener)

Get Ranking of User in a Leaderboard

getTopNLeaderboard(LeaderboardParams leaderboardParams, boolean clearCache, ListenerModel<BaseModel<LeaderData>, LeaderData> listener)

Query Members with Ranking Around the User in a Leaderboard

getLeaderboardAroundMe(LeaderboardParams leaderboardParams, boolean clearCache,
                                       ListenerModel<BaseModel<LeaderData>, LeaderData> listener)

Query Top Leaderboard Ranking Members

getLeaderboardMemberRank(LeaderboardParams leaderboardParams, boolean clearCache, ListenerModel<BaseModel<MemberRankData>, MemberRankData> listener)

Query Leaderboard Ranking of Friends

getLeaderboardFriendsRank(LeaderboardParams leaderboardParams, boolean clearCache,
                                          ListenerModel<BaseModel<LeaderData>, LeaderData> listener)