Configurations πŸ‘‘

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

Available Endpoints

TypeDescriptionEndpoint

GET

/integrations/config

GET

/integrations/client/redemption/config

GET

/integrations/config/challenge/{handle}

GET

/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 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/7e38bd4a-10b9-4c2f-8d94-56ab0b59da1aicon-icon-basic@2x.png",
         "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 -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d 
 -v -i 'https://api.gameball.co/api/v3.0/integrations/config'

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

ParameterTypeDescription

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

ParameterTypeDescription

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

ParameterTypeDescription

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

ParameterTypeDescription

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

ParameterTypeDescription

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

ParameterTypeDescription

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

AttributeTypeRequiredDescription

APIKey

string

Yes

Client API key

secretKey

string

Yes

Client Secret key

Response

ParameterTypeDescription

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

ParameterTypeDescription

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"]
            }
        }
    ]
}

Last updated