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	Challenge Configurations	/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

Header

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 challenge 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	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	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	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. 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 as an extra reward. 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. voucherType : A string that describes the voucher type. productId : Unique identifier for the product (in case the voucher was of type "Free Product" for example). productName : Name of the product associated with the voucher (in case the voucher was of type "Free Product" for example). value : It represents the value of this 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's 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	Determine the points rewarded for each unit of 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 of 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/[e-mail]",
         "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

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d 
 -v -i 'https://api.gameball.co/api/v3.0/integrations/config'

Ruby

# Example 1
Gameball::Configurations.get_configurations()

# Example 2
Gameball::Configurations.get_configurations({lang: "en"})

PHP

$response = $gameball->config->getConfigurations();

Python

configurations = gameball.get_configurations()

.NET

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	Challenge Name.
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 of creation).
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 levelId
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
productId	integer	Unique identifier of the product.
productName	string	Name of the product.
productDisplayNames	array	An array of display names for the product.
variantId	integer	In case the product has variants this is the id of the variant.
variantName	string	In case the product has variants this is the name of the variant.

group Object

Parameter	Type	Description
handle	string	A unique identifier for the coupon group.
title	string	Title of the coupon group.
url	string	URL of the coupon group.
iconPath	string	Icon path of the coupon group.
description	string	Description of the coupon group.
maxPerPlayer	integer	Maximum number of times a player can achieve coupons from this group.
startDate	DateTime	Date at which coupons can start to be redeemed from this group.
expiryDate	DateTime	Date at which you can no longer redeem coupons from this group.
isAvailable	boolean	A Boolean flag indicating if there are coupons available to be redeemed from this group.
isValid	boolean	Flag indicating if the group is valid (The group is considered valid if the current date falls between the start and expiry dates).
isActive	boolean	Flag indicating if the group is active or not (The group is considered active if the client has marked it as active and if the group's dates are valid).

Sample Response

{
  "isRedemptionActive": true,
  "pointsExpiryPeriod": 720,
  "redemptionRules": [
    {
      "id": 1976,
      "pointsToRedeem": 50,
      "valueOfPoint": 0.0,
      "ruleType": "free_product_settings",
      "startDate": "2022-09-09T12:07:19.269733",
      "endDate": "2023-09-09T12:07:19.269733",
      "coupon": {
        "couponType": "free_product",
        "discountValue": 0.0,
        "minOrderValue": null,
        "product": {
          "productId": "6932183449758",
          "productName": "7 Shakra Bracelet",
          "variantId": "40691241877662",
          "variantName": "Blue",
          "productDisplayNames": []
        },
        "applicableTo": {
          "collections": [],
          "productIds": []
        },
        "group": {
          "handle": "free_macdo",
          "title": "Free MACDO",
          "url": "https://www.mcdonalds.eg/eat/menu/Item/Chicken-MACDO-",
          "iconPath": "https://www.mcdonalds.eg/Cms_Data/Contents/En/Media/images/Menu/large-Image/Chicken-MACDO.png",
          "description": "Coupons in this group give a free macdo and can be rdeemed in all Mcdonalds branches",
          "maxPerPlayer": 10,
          "startDate": "2022-09-09T12:07:19.269733",
          "expiryDate": "2023-09-09T12:07:19.269733",
          "isAvailable": true,
          "isValid": true,
          "isActive": true
        }
      },
      "availableTo": {
        "level": {
          "levelName": "silver",
          "levelId": 21
        },
        "tags": []
      },
      "howToRedeem": "How to redeem text"
    }
  ]
}

Get - Cashback Rules

https://api.gameball.co/api/v3.0/integrations/client/cashback

This API endpoint is used to return all client’s cashback rules.

Request

Header

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

Response

Parameter	Type	Description
isCashbackActive	boolean	A boolean flag indicating if the Cashback program is active for the client.
returnWindowDuration	integer	Number of days that the player can return an order and points get deducted accordingly.
cashbackRules	array	An array of cashback objects of the client.

cashback Object

Parameter	Type	Description
id	integer	Id of the cashback rule.
isDefaultRule	boolean	A boolean indicating if the cashback rule is the default one.
minAmountToSpend	double	Amount needed to be spent in order to be rewarded the cashback.
pointsRewardedAsCashback	double	Points awarded for the amount specified in minAmountToSpend .
availableTo	object	An AvailableTo object specifying the availability of the rule (To whom this rule will be applied on).

Sample Response

{
    "isCashbackActive": true,
    "returnWindowDuration": 14,
    "cashbackRules": [
        {
            "id": 12345,
            "isDefault": true,
            "minAmountToSpend": 10.0,
            "pointsRewardedAsCashback": 1.0,
            "availableTo": {
                "level": {
                    "levelId": null,
                    "levelName": null
                },
                "tags": []
            }
        },
        {
            "id": 12344,
            "isDefault": false,
            "minAmountToSpend": 10.0,
            "pointsRewardedAsCashback": 2.0,
            "availableTo": {
                "level": {
                    "levelId": 234,
                    "levelName": "Silver"
                },
                "tags": ["VIP"]
            }
        }
    ]
}