Comment on page

Configurations πŸ‘‘

The Configurations Endpoints can be used to retrieve client different configurations.

Available Endpoints

Type
Description
Endpoint
GET
​Configurations​
/integrations/config
GET
​Redemption Rules​
/integrations/client/redemption/config
GET
/integrations/config/challenge/{handle}
GET
​Cashback Rules​
/integrations/client/cashback

GET - Configurations

https://api.gameball.co/api/v3.0/integrations/config
This API call is used to retrieve your configured Gameball Settings along with all Gameball Programs Configurations. This endpoint allows you to retrieve your configured settings on Gameball account which can be used while creating your custom UI for the player profile on your website or mobile app.
It is very important to use this endpoint while building your own UI to keep all configurations related to Gameball are variable. No need to update your loyalty program static content inside your website or mobile app every time you change them through Gameball admin dashboard.
This endpoint is only available for our GURU customers only πŸ‘‘

Request

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
lang
string
No
Language filter. This could be used to specify the language needed to display your configurations in. If not provided, the response would be in default language. Note: The language provided should be as per configured languages in your account.
Example: "en", "fr".

Response

Parameter
Type
Description
currency
string
Configured Currency
Example: "USD", "EUR".
programName
string
Name of your program.
Example: "TRIPLE H Store"
rankPointsName
string
Name of the rank points, measuring player's progress.
walletPointsName
string
Name of the points (monetary value).
botMainColor
string
The main color of your bot as configured from your Gameball dashboard.
controlConfig
object
An object describing the activity of the main factors.
levels
array
An array of level objects describing each level along with its configurations
challenges
array
An array of challenge objects describing each level along with its configurations
referral
object
An object describing the referral program configurations.
cashback
object
An object describing the cashback program configurations
redemption
object
An object describing the redemption configurations The redemption object is described as follows
  • redemptionFactor: Indicates the monetary value which one point is equivalent to. Example: Redemption Value of 1 point is 0.01 (redemption factor).
  • redemptionRules: Array of Redemption Rule objects​

controlConfig Object

Parameter
Type
Description
gameballEnabled
boolean
Indicates whether Gameball is enabled or not.
redemptionEnabled
boolean
Indicates whether redemption configurations is enabled or not.
cashbackEnabled
boolean
Indicates whether cashback program is enabled or not.
referralEnabled
boolean
Indicates whether referral program is enabled or not.
visitorProfileEnabled
boolean
Indicates whether guest view is enabled or not.
userProfileEnabled
boolean
Indicates whether user view is enabled or not.
leaderboardEnabled
boolean
Indicates whether Leaderboard configurations are enabled or not.
notificationsEnabled
boolean
Indicates whether Notifications configurations are enabled or not.
achievementsEnabled
boolean
Indicates whether Achievements configurations are enabled or not.

level Object

Parameter
Type
Description
minProgress
integer
The required score to reach the level.
order
integer
Level Order
icon
string
icon URL of the level.
name
string
Level Name
benefits
object
"benefits":{
"rankReward":0,
"walletReward":0,
"levelDiscount":0,
"discountCapping":0,
"others":[]
}
The benefits object is defined as follows:
  • rankReward: Score rewarded upon reaching that level.
  • walletReward : Points rewarded upon reaching that level.
  • levelDiscount: The discount amount that the level grants.
  • discountCapping: The maximum value to which the discount is applicable. Example: 10% discount for maximum order price 100 USD
  • others: An array of statement(s) that can be used to describe the benefits of the level.

challenge Object

Parameter
Type
Description
id
integer
Unique identifier for the challenge.
name
string
Challenge Name
description
string
Challenge Description
rankReward
integer
Awarded rank upon challenge completion
walletReward
integer
Awarded points upon challenge completion
repeatable
boolean
A flag that indicates whether the challenge is repeatable or not.
maxAchievement
integer
An integer that defines how many times a player can achieve that challenge.
type
string
The type of the challenge. Possible values are as follows: SignUp
SocialMedia
ScheduledChallenge
EventBased
HighScore
Birthday
Anniversary
visibility
string
Defines the visibility of the challenge. Possible values are:
  • "AlwaysVisibile"
  • "NotVisible"
  • "VisibleIfEarned"
icon
string
The icon's URL of the challenge.
availability
object
"availability":{
"minLevel": 4,
"tags": ["VIP"]
}
An object that describes challenge availability to players.
  • minLevel : Minimum required level for the player to be eligible to the achieve the challenge.
  • tags: Array of tags for which the challenge is available.
redirectionButtonText
string
Defines the text written on the redirection button (In case the redirection button is enabled for this challenge).
redirectionButtonLink
string
Defines the redirection link (In case the redirection button is enabled for this challenge).

referral Object

Parameter
Type
Description
referralMethod
string
Defines how the referral program rewards your players, Possible values:
  • "PlayerAndFriend" denotes that both the referring and the referred player should be rewarded. The referred player also should complete the sign up process and perform a certain action according to your configurations.
  • "PlayerOnly" denotes that only the referring player that should be rewarded after a successful referral.
  • "PlayerAndGuest" denotes that both the referring and the referred player should be rewarded. Referred Player Registration is optional, but he would be rewarded after placing a successful order.
eventName
string
The name of the event which is linked to the referral action
eventMetaData
string
The event metadata which value should be monitored and checked for completing the referral.
playerReward
object
"playerReward":{
"extraReward":{
"rewardEvery":5,
"rewardType":null,
"score":2,
"point":1,
"voucher":null
},
"rewardType":"Vouchers",
"score":0,
"point":0,
"voucher":{
"voucherType":"Free Shipping",
"productId":"",
"productName":"",
"value":0
}
}
An object that defines the referring player's reward.
The playerReward object is defined as follows:
  • extraReward: An object that defines the extra reward the referring player is granted after completing specific number of referrals. "extraReward":{
    "rewardEvery":5,
    "rewardType":null,
    "score":2,
    "point":1,
    "voucher":null
    }
    • rewardEvery:Defines the frequency upon which the referring player is rewarded
    • rewardType : Defines the type of the reward, possible values are:
      • "Vouchers"
      • "Score&Points"
    • score: Score rewarded as an extra reward.
    • points: Points rewarded as an extra reward.
    • voucher: An object that defines the rewarded voucher.
    "voucher": {
    "voucherType":"Free Product",
    "productId":"6161866621123",
    "productName":"Antique Drawers",
    "value":250
    }
  • rewardEvery:Defines the frequency upon which the referring player is rewarded
  • rewardType : Defines the type of the reward, possible values are:
    • "Vouchers"
    • "Score&Points"
  • score: Score rewarded as an extra reward.
  • points: Points rewarded as an extra reward.
  • voucher: An object that defines the rewarded voucher.
friendReward
object
Defines the referred player reward configurations in case the referralMethod is "PlayerAndFriend" meaning that the referred player should also be rewarded.
The object is the same as the playerReward object excluding the extraReward.

cashback Object

Parameter
Type
Description
rewardFactor
number
In case you have different merchants (brands) on your platform, The rewardFactor defines the specific cashback percentage for the paid amount to be rewarded to your players.
Example: If you give 5% cashback (when the customer pays 100 USD, they will get 5 USD cashback). The rewardFactor would be 0.05
amountRewardThreshold
integer
Defines the amount of unit currencies needed to reward the player as per cashback rules. Example: For every 10 USD spent the player gets rewarded by 5 points, implies that the amountRewardThreshold is "10".
rewardWalletFactor
integer
Determines the points rewarded for each unit currency your player spends.
Example: 2 points for every 1 USD spent, implies that the rewardWalletFactor is "2"
rewardRankFactor
integer
In case your level up method is score, this factor determines the score rewarded for each unit currency your player spends.
Example: 2 Score for every 1 USD spent, implies that the rewardRankFactor is "2"

Sample Response

{
"currency":"EGP",
"programName":"my program",
"rankPointsName":"Score",
"walletPointsName":"Points",
"botMainColor":"#e7e23f",
"controlConfig":{
"gameballEnabled":true,
"redemptionEnabled":true,
"cashbackEnabled":true,
"referralEnabled":true,
"visitorProfileEnabled":true,
"userProfileEnabled":true,
"leaderboardEnabled":false,
"notificationsEnabled":true,
"achievementsEnabled":true
},
"levels":[
{
"minProgress":0,
"order":1,
"icon":"https://cdn.gameball.co/uploads/Client 1/[email protected]",
"name":"Basic",
"benefits":{
"rankReward":0,
"walletReward":0,
"levelDiscount":0,
"discountCapping":0,
"others":[
"benefits1",
"benefits2"
]
}
}
],
"challenges":[
{
"id":3350,
"name":"view product + tag internal",
"description":"",
"rankReward":3,
"walletReward":10,
"repeatable":true,
"maxAchievement":0,
"type":"EventBased",
"visibility":"AlwaysVisible",
"icon":"gb-icon-challenge-10@2x",
"availability":{
"minLevel":5,
"tags":[
"2nd tag"
]
},
"redirectionButtonText": "Free Gift",
"redirectionButtonLink": "https://claires.myshopify.com/products/jeans"
}
],
"referral":{
"referralMethod":"PlayerAndFriend",
"eventName":"",
"eventMetaData":null,
"playerReward":{
"extraReward":{
"rewardEvery":5,
"rewardType":null,
"score":2,
"point":1,
"voucher":null
},
"rewardType":"Vouchers",
"score":0,
"point":0,
"voucher":{
"voucherType":"Free Shipping",
"productId":"",
"productName":"",
"value":0
}
},
"friendReward":{
"rewardType":"Vouchers",
"score":0,
"point":0,
"voucher":{
"voucherType":"Free Product",
"productId":"6161866621123",
"productName":"Antique Drawers",
"value":250
}
}
},
"cashback":{
"rewardFactor":0.3,
"amountRewardThreshold":10,
"rewardWalletFactor":3,
"rewardRankFactor":1
},
"redemption":{
"redemptionFactor":0.01,
"redemptionRules":[
{
"ruleId":1097,
"type":"Level",
"equivalentPoints":0,
"equivalentPointsValue":0,
"productId":"",
"productName":""
},
{
"ruleId":1156,
"type":"FreeProduct",
"equivalentPoints":100,
"equivalentPointsValue":50,
"productId":"6161869406403",
"productName":"Striped Skirt and Top"
}
]
}
}

Usage Example

cURL
Ruby
PHP
Python
.NET
curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d
-v -i 'https://api.gameball.co/api/v3.0/integrations/config'
# Example 1
Gameball::Configurations.get_configurations()
​
# Example 2
Gameball::Configurations.get_configurations({lang: "en"})
$response = $gameball->config->getConfigurations();
configurations = gameball.get_configurations()
var response = Gameball.GetConfigurations();

GET - Challenge Configurations

This API is used to get the configurations of a specific challenge. ​
https://api.gameball.co/api/v3.0/integrations/config/challenge/{handle} ​

Request

Header

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key

Path Parameters

Attribute
Type
Required
Description
handle
string
Yes
Challenge handle could be either the Challenge Id or the Challenge internal name.

Response

Attribute
Type
Description
challengesConfig
object
A single object array of ChallengeConfig object

challengesConfig object

Attribute
Type
Description
id
integer
A single object array of ChallengeConfig object
name
string
​
description
string
Challenge description( In default language if not specified in query parameter)
rewards
array
An array of Reward objects, these are the rewards that are achieved by completing the specified challenge
isRepeatable
boolean
A boolean indicating if the challenge is repeatable for the specified Player or not
maxAchievement
integer
Maximum number of times the specified challenge can be achieved (-1 if can be achieved for an unlimited number of times)
type
string
Challenge type, can be one of the following:
  • Amount Based
  • Action Based
  • Amount & Action Based
  • High Score
  • Upon Login
  • NonCumulative Amount Based
  • Join Anniversary
  • Event Based
  • Social Activities
  • Scheduled Challenge
  • Streak
visibility
string
Challenge visibility type, can be one of the following:
  • Always Visible
  • Not Visible
  • Visible If Earned
icon
string
URI indicating the file path to the icon of the challenge
availability
object
An availability object specifying the conditions where this challenge is available
redirectionButtonText
string
Defines the text written on the redirection button (In case the redirection button is enabled for this challenge).
redirectionButtonLink
string
Defines the redirection link (In case the redirection button is enabled for this challenge).

Sample Response

{
"challenges": [
{
"id": 6128,
"name": "IsRepeatable test",
"description": "DescNew",
"rewards": [
{
"rankReward": 0,
"walletReward": 0,
"couponReward": {
"couponType": "Free Product",
"discountValue": null,
"minOrderValue": null,
"product": {
"productId": "7803615346931",
"productName": "Chequered Red Shirt",
"variantId": "43168747192563",
"variantName": null
},
"collections": []
}
}
],
"isRepeatable": false,
"maxAchievement": 1,
"type": "EventBased",
"visibility": "Always Visible",
"icon": "https://s3.us-east-2.amazonaws.com/gameball.dev.uploads/uploads/gb-library/general/annoncement.png",
"availability": {
"minLevel": 3,
"tags": [
"active",
"inactive"
]
},
"redirectionButtonText": "Free Gift",
"redirectionButtonLink": "https://claires.myshopify.com/products/jeans"
}
]
}

GET - Redemption Rules

https://api.gameball.co/api/v3.0/integrations/client/redemption/config
This API endpoint is used to return all client’s redemption rules.

Request

Header

APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
lang
string
No
Preferred language code. (e.g. "en", "es")

Response

Parameter
Type
Description
isRedemptionActive
boolean
A Boolean flag indicating if the redemption program is active for the client
​
​
​
pointsExpiryPeriod
int
Number of days that the points will expire after being rewarded
redemptionRules
array
An array of redemptionRule objects of the client.

redemptionRule object

Parameter
Type
Description
id
integer
Unique Identifier of the redemption rule.
pointsToRedeem
double
Points needed for the rule to be redeemed
valueOfPoint
double
In the case of a rule of type general_settings, this attribute specifies the monetary value of one point.
ruleType
string
Indicates the type of the rule and can be one of the following:
  • free_shipping_settings For rule that redeems a free shipping coupon
  • percentage_discount_settings: For rule that redeems a percentage based discount coupon
  • free_product_settings: For rule that redeems a free product coupon
  • fixed_rate_settings For rule that redeems a coupon that discounts a fixed amount
  • general_settings For general rule that allows user to trade points for their monetary value
  • custom
startDate
DateTime
Starting date when the rule can be applied (If null then it starts from the date it is created).
endDate
DateTime
Ending date when the rule will expire (If null then it will not expire).
coupon
object
A coupon object describing the coupon that is awarded when the rule is redeemed.
availableTo
object
An AvailableTo object specifying the availability of the rule (To whom this rule will be available).
howToRedeem
string
A text displaying the how to redeem section as configured in the dashboard if lang header was provided the returned text will adapt to the sent lang parameter, else the default lang text will be returned.

availableTo Object

Parameter
Type
Description
level
object
A Level object indicating the level that the rule is available to,
The Level object has the following attributes:
  • levelName
    • String
  • levelId
    • int
tags
array
An array of tag names that the rule is available to

coupon Object

Parameter
Type
Description
couponType
string
Indicates the type of the coupon, the value of the string can be one of the following:
  • free_shipping
  • percentage_discount
  • fixed_discount
  • free_product
  • fixed_rate_discount
  • custom
discountValue
double
Indicating the discount value of the coupon, in the case of percentage it will indicate the percentage value of the discount.
minOrderValue
double
Minimum value the order has to reach in order for the coupon to be applied.
product
object
In the case of free_product coupon, a product object indicates the details of the free product.
applicableTo
object
Indicates if the coupon can only be applied to certain orders. It has the following attributes:
  • collections: Array of collectionIds
  • productIds: Array of productIds
group
object
An object describing the coupon group which the coupon belongs to
product Object
Parameter
Type
Description