v3.0 (Beta)
Installing Gameball
Tutorials
Third Party Integrations
Build Custom UI 👑
This guide helps you to customize your UI in order to make a better experience for your system.
Many modern businesses & brands prefer to build their own UIs for their apps or web pages. This helps them maintain their branding, look-and-feel, and most importantly control their user experience.
Gameball offers an extensive set of personalizations to its widget, but for brands & businesses that are looking for their own customization, we offer a set of APIs that can be used for this purpose. These APIs can be used for creating UIs for apps and web pages that respond to players’ data changes, and all the great declaratives that Gameball offers.
You can make use of these APIs to create native mobile apps and custom web apps with your own branding and look-and-feel.
Sample App
In this tutorial we will be exploring different APIs that can be used to support building your own custom UIs; customizing your own players' Gameball experience.
Before we dive in, you may find it useful to take a look at the following APIs that will be used throughout this tutorial, where we will demonstrate how each one can contribute to build a different custom UI for your players.
Used API Endpoints
Type
Description
Purpose
GET
Provides information about program configurations across Gameball like cashback, referrals, challenges and levels. In addition to control declaratives.
GET
Provides a player's progress in available configured Gameball programs
What you'll learn
After you've finished this tutorial, you'll have an understanding of the following:
Use of the Configurations API
Configurations API can be used in many scenarios when building your own UI. It provides information about the current program's configurations, in addition to control declaratives that can be managed from your Gameball’s account dashboard.
Let's assume that within your app you would like to build a page for your players, where they can see the available levels that they can reach, along with each of the benefits they will get when reaching this level.
In order to display current player progress, you need to make use of the Player Progress endpoint to get current player's progress after using Config API.
In order to do so all you need to do is to call the configurations API and process the levels array within the response. Take a look at the below snippet where it shows a sample levels list as returned within the configuration response.
1
{
2
...
3
...
4
"levels":[
5
{
6
"minProgress":0,
7
"order":1,
8
"icon":"https://cdn.gameball.co/uploads/007/7e3.png",
9
"name":"Basic",
10
"benefits":{
11
"amountRewardThreshold":null,
12
"rankReward":null,
13
"walletReward":null,
14
"levelDiscount":null,
15
"discountCapping":null,
16
"others":[]
17
}
18
},
19
{
20
"minProgress":5000,
21
"order":2,
22
"icon":"https://cdn.gameball.co/uploads/007/7es3.png",
23
"name":"Silver",
24
"benefits":{
25
"amountRewardThreshold":null,
26
"rankReward":null,
27
"walletReward":null,
28
"levelDiscount":5,
29
"discountCapping":null,
30
"others":[]
31
}
32
},
33
{
34
"minProgress":10000,
35
"order":3,
36
"icon":"https://cdn.gameball.co/uploads/007/ae3.png",
37
"name":"Gold",
38
"benefits":{
39
"amountRewardThreshold":null,
40
"rankReward":null,
41
"walletReward":null,
42
"levelDiscount":15,
43
"discountCapping":null,
44
"others":[
45
"Next day delivery for free"
46
]
47
}
48
},
49
{
50
"minProgress":20000,
51
"order":4,
52
"icon":"https://cdn.gameball.co/uploads/007/ae4.png",
53
"name":"Platinum",
54
"benefits":{
55
"amountRewardThreshold":null,
56
"rankReward":null,
57
"walletReward":null,
58
"levelDiscount":35,
59
"discountCapping":null,
60
"others":[
61
"Next day delivery for free",
62
"Selected Free Product each month"
63
]
64
}
65
}
66
]
67
...
68
...
69
}
Copied!
Four levels are configured within the program: Basic, Silver, Gold and Platinum. Each with its benefits, name and icon. In your custom UI screen you can bind the levels array accordingly to build your own levels screen.
Using the Lang filter
In case your app or web page supports different locales and changes based on your player’s preferences. After configuring your supported locales in Gameball, you will need the API response text to match the locale of the current player.
To do so, you can provide the optional Lang query filter to your API call so that Gameball can respond using the corresponding configured locale.
In order to better understand how to configure your languages and know their respective language codes, check this article in our Help Center.
For example, if your app supports English and French, and the current player using the app selected French as his preferred language. All you need to do is to call the API as follows:
1
https://api.gameball.co/api/v3.0/integrations/config?lang=fr
Copied!
Making use of the control declaratives
In addition to returning your program's configurations, the Configurations API returns a list of control flags to help in decoupling UI changes from business decisions and changes. For example, consider a business decision to disable all of Gameball programs during the financial year closing.
To avoid re-deployment, you can make use of the control declaratives which reflect business decisions managed through the dashboard like enable/disable Gameball, show Gameball notifications, enable cashback, and many others.
The control declarative object provided along with the response body will look like this:
1
{
2
...
3
...
4
"controlConfig":{
5
"gameballEnabled":true,
6
"redemptionEnabled":true,
7
"cashbackEnabled":true,
8
"referralEnabled":true,
9
"enableVisitorProfile":true,
10
"enableUserProfile":true,
11
"enableLeaderboard":true,
12
"enableNotifications":true,
13
"enableAchievements":true
14
}
15
...
16
...
17
}
Copied!
Use of the Notifications APIs
Gameball generates player notifications for the player as he progresses through your Gameball configured program. The notifications generated can be for Challenge achievements, level achievements, wallet points rewards, or any other event as per your program's configurations.
In case you would like to build a custom notification tab/inbox for your player within your app or web page, you can easily achieve this using the Notifications API.
The Notifications API returns a paged list of player’s notifications ordered by date. Each notification item in the list has all the information you need to display the notification.
1
{
2
"notifications": [
3
{
4
"notificationId" : "123",
5
"title": "New level!",
6
"body": "Keep it up! You are now on Bronze ",
7
"isRead": true,
8
"createdAt": "2021-05-12T00:08:09.646174",
9
"lang": "en",
10
"icon": "https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb-icon-level-13.png"
11
},
12
{
13
"notificationId" : "124",
14
"title": "Congratulations! ",
15
"body": "Welcome earned. Enjoy your rewards and keep earning more!",
16
"isRead": true,
17
"createdAt": "2021-05-12T00:08:09.623367",
18
"lang": "en",
19
"icon": "https://cdn.gameball.co/uploads/client776/bcc5d9be-3861-415f-bdf9-34b4064a1320Group 2144.png"
20
}
21
],
22
"count": 50,
23
"total": 200
24
}
Copied!
For each notification, you have its title, message, icon, and status - if it has been read by the player or not.
Once a notification is seen by the player, you can update Gameball to set the notification as read using the Notifications PUT API. All you have to do is to call the PUT API with the list of notification ids that have been read by the player.
1
curl -X PUT -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
2
"notificationIds" : ["123", "3441", "3245"]
3
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/notifications'
Copied!
Using the query string filters, you can set the desired inbox page size by setting the limit value. The below API call returns the first page with size of 20 notifications.
1
https://api.gameball.co/api/v3.0/integrations/notifications/:playerUniqueId?
2
limit=20
Copied!
You can also control the desired page by setting the page number as a query filter. The following example returns the second page where a page size is 20 notifications.
1
https://api.gameball.co/api/v3.0/integrations/notifications/:playerUniqueId?
2
limit=20&page=2
Copied!
The notifications API also supports the Lang query string filter, where you can return the notifications displayed in the current player's locale as configured on your Gameball account.
Use of the Leaderboard API
In your app or web page you may need to display the leaderboard for your players. In that case you can make use of the Leaderboard API that can help you build the desired leaderboard UI in a flexible way that handles different cases.
The leaderboard API returns a list of players ordered by their rank for a given period of time. A single element in the leaderboard list represents a player with his status
1
{
2
"displayName": "Player 1",
3
"playerUniqueId": "5097238429738",
4
"progress": 1748,
5
"rank":1,
6
"levelName": "Bronze",
7
"levelIcon": "https://cdn.gameball.co/uploads/c007/[email protected]"
8
}
9
…
10
…
Copied!
Each player element in the list has the player’s name, unique id, progress in the given period, rank among the leaderboard, and info about their level.
Note: Gameball doesn't currently support images for players. In order to map your players and their respective images, it has to be done manually.
The leaderboard API accepts two important filters (from, to) as query strings. These filters control the returned leaderboard time window. Let's consider the following scenarios:
Show today’s leaderboard
This can be done by sending the from query parameter as today’s date. Lets say today is the 24th of Dec 2021, then the request would be as following
1
https://api.gameball.co/api/v3.0/integrations/leaderboard?
2
from=2021-12-24 00:00
Copied!
Show last month leaderboard
This can be done by sending the from and to query filter setting the boundaries of last month. For example if the current month is December, and you are looking for the previous month's (November) leaderboard. Then we would be setting the from and to dates as below
1
https://api.gameball.co/api/v3.0/integrations/leaderboard?
2
from=2021-11-01 00:00&to=2021-11-30 00:00
Copied!
Show the all time leaderboard
From and to filters are omitted from the request.
1
https://api.gameball.co/api/v3.0/integrations/leaderboard
2
Copied!
The leaderboard API can also be used to show a specific player's rank by sending the Player Unique Id as a filter
1
https://api.gameball.co/api/v3.0/integrations/leaderboard?
2
from=2021-11-01 00:00&to=2021-11-30 00:00&playerUniqueId=player456
Copied!
This will return a
playerRank object with the leaderboard list within the response that shows the player rank even if he is not listed within the leaderboard.1
"playerRank": {
2
"rank": 70,
3
"playersCount": 100
4
}
Copied!
Use of the Progress API
Player Progress API helps you display the player’s progress in different Gameball programs within your app or web page. It returns the player's progress in challenges, levels, wallet points balance, and referral, in addition to other information related to the player.
Lets begin with a simple use case where you would like to show the player their progress in achieving the available challenges
All the needed information is available in the challenge progress array within the player’s progress API response, as follows:
1
"challengesProgress":[
2
{
3
"id":"123",
4
"name":"Welcome",
5
"description":"Welcome Challenge",
6
"isUnlocked":true,
7
"highScoreAmount":null,
8
"completionPercentage":0,
9
"isRepeatable":false,
10
"achievedCount":0,
11
"icon":"https://cdn.gameball.co/uploads/client776/643323652begb.png"
12
},
13
{
14
"id":"p123",
15
"name":"Place Order",
16
"isUnlocked":true,
17
"highScoreAmount":null,
18
"completionPercentage":55,
19
"isRepeatable":true,
20
"achievedCount":2,
21
"icon":"https://cdn.gameball.co/uploads/client776/a643323652begb.png"
22
}
23
]
Copied!
The challenge progress holds the progress of the player against every eligible challenge. Let's examine each challenge attribute returned by the challenge progress array and see how they can help us in building the UI.
First thing we may use is the id, name, description and icon. These attributes can be used to draw the eligible challenges list for the player without progress information.
Now let's say you want to highlight the achieved challenges and dim the non achieved challenge on your UI. You can easily do this by checking the
achievedCount attribute. Where a 0 represents not yet achieved and 1 or more denotes that a challenge was achieved at least once.
In our example the Welcome challenge achieved count is equal to 1 and First Order challenge achieved count is equal to 0, hence we will be adding a dimming style for the First Order challenge icon.
For challenges where a player has done a progress but not yet completed, you can make use of
completionPercentage attribute where it represents the current progress. Let's say we have a challenge “Tenth Order” that the user will achieve when making 10 orders. If the user completed 6 orders, the response will look like this:1
{
2
"id":"p123",
3
"name":"Tenth Order",
4
"isUnlocked":true,
5
"highScoreAmount":null,
6
"completionPercentage":60,
7
"isRepeatable":false,
8
"achievedCount":0,
9
"icon":"https://cdn.gameball.co/uploads/client776/a643323652begb.png"
10
}
Copied!
Art work to show 60% completion
The Player Progress API also returns the wallet points balance of the player. This can be used to show the player the amount of points he has and their equivalent value.
1
"points": {
2
"pointsBalance":1230,
3
"pointsValue":200,
4
"currency":"USD",
5
"pointsName":"Points"
6
}
Copied!
Using this the following screen can be built within your app or web page.
