Gigya Job Openings

gm.setChallengeConfig REST

Skip to end of metadata
Go to start of metadata

Note: If you plan on integrating the Loyalty platform, we highly recommend reading the Loyalty - Gamification and User Behavior Guide. Loyalty is a premium Gigya platform that requires separate activation. If it is not yet a part of your existing site package, please contact Gigya Support via the Support link in the top menu of your Console Dashboard or email support@gigya.com.

Description

This API creates or overwrites an existing Gamification challenge. Read more about Gamification Challenges

If a challenge already exists, it's stored configuration will be overwritten using this method.  

  • Top-level parameters - You must specify all top level parameters, unspecified parameters will be cleared and/or set to their default.
  • Complex parameters, i.e., actions and levels - must be set as a whole, you cannot update a single level for example.

Notes:

  • Challenges created via this API can be further edited via the Challenge Settings page on Gigya's site.
  • If you plan on integrating the Game Mechanic platform, we highly recommend reading the Game Mechanics Guide.
  • Game Mechanics is a premium platform that requires separate activation. If Game Mechanics is not part of your site package please contact your Gigya account manager or contact us by filling in a support form on our site.

Request URL


Where <Data_Center> is:
  • us1.gigya.com - For the US data center.
  • eu1.gigya.com - For the European data center.
  • au1.gigya.com - For the Australian data center.
  • ru1.gigya.com - For the Russian data center.
  • cn1.gigya-api.cn - For the Chinese data center.

If you are not sure of your site's data center, see Finding Your Data Center.

Parameters

RequiredNameTypeDescription

challengeIDstringThe unique ID of the challenge. 
challengeActions *array

*This parameter is only required if you define any requiredActions parameters or have any actions defined elsewhere. If this parameter is not set, all actions will be removed and the method will fail since actions and/or points are required when defining levels within the challenge.

An array listing the challenge actions. Each action is represented by an object that includes the following fields:

  • actionID - the unique ID of the action. 
  • points - the number of points a user earns for performing this action. 
  • lifetimeCap - the set amount of times that performing this action awards the user points.

You may find more information about action fields in the Action Properties section of the Game Mechanics  Guide.

*If you include any requiredActions parameters or have any actions defined elsewhere, and fail to set the challengeActions parameter, all actions will be removed and the method will fail.



namestring or JSONThe name of the challenge. The name should be in the following format:
{
    "default":"<challenge name in default language>",
   "<language code>":"<challenge name in specified language>"
  ...
}
The name parameter is constructed of the name in the default language, e.g. {"default":"Music Lover"}, and also of a pair or pairs of language codes with their respective challenge names, e.g.: 
{
    "default":"Music Lover",
"es":"Persona aficionada a la música",
    "ar":"محبي الموسيقى"
}
In this case the name of the challenge is provided in the default language (English), and in Spanish (es) and Arabic (ar). The available language codes can be found here. The parameter can be passed as a string only, without the language codes, in which case the string represents the name of the challenge in the default language, e.g. "Music Lover". 
Note: This parameter is optional, but for the best practice implementation, we recommend adding a challenge name to each challenge.
descriptionstring or JSONThe description of the challenge. The description has the same format as the name parameter - it is constructed of the description in the default language, and also of a pair or pairs of language codes with their respective challenge descriptions:
{
"default":"<challenge description in default language>",
"<language code>":"<challenge description in specified language>",
...
}
The available language codes can be found here. The parameter can be passed as a string only, without the language codes, in which case the string represents the description of the challenge in the default language, e.g. "Earn points for sharing songs to advance in Music Fan challenge."
enabledBooleanIndicates whether the challenge is enabled or not. The default value is 'false'.
enableTimeWindowBooleanIndicates whether to define a "time window" in which the challenge will be active (not the same as enabled).  Outside of the "time window" the user actions assigned to the challenge will not be counted.  The default value is 'false'.
startDatestring The start date of the "time window" in which the challenge will be active (not the same as enabled). Outside of the "time window" the user actions assigned to the challenge will not be counted. The format is MM/DD/YYYY hh:mm:ss tt. Note that the time component is optional. If not specified, midnight will be assigned automatically.
endDatestringThe end date of the "time window" in which the challenge will be active (not the same as enabled).  Outside of the "time window" the user actions assigned to the challenge will not be counted. The format is MM/DD/YYYY hh:mm:ss tt. Note that the time component is optional. If not specified, midnight will be assigned automatically.
hideUntilFirstLevelBooleanIndicates whether to hide the specified challenge from being displayed in any of the GM plugins if the user hasn't yet achieved at least one level (minimum threshold).
hideUnlockedBadgesBooleanWhen enableTimeWindow is set to true, this parameter indicates whether to hide the unlocked badges from the user when not in the defined time window. The default value is 'true'.
enableVariantTemplatesBooleanIndicates whether to allow the use of challenge variants, meaning that the specific challenge will support Action Attributes. When set to 'true', a challenge variant will be automatically created for each attribute that is reported for a relevant action. Read more about Action Attributes.
levelsarray

An array listing the challenge levels. Each level is represented by an object that includes the following fields:

RequiredNameTypeDescription
levelIntegerThe level ID. (incrementing)
points*integer

The number of points the user needs to earn in order to reach ("unlock") the level. If both points and requiredActions are specified, achieving both of them are needed in order to level up.

*You must choose either points and/or requiredActions. Choosing both, however, will require achieving both of them in order to level up.

requiredActions*JSON

The actions that the user needs to perform in order to reach ("unlock") the level. The actions should be in the following format:
[
   {
    "actionID":"<actionID>",

     "count":"<count>",
   }
]
When actionID represents the unique action ID, and count represents the number of times the action must be performed in order to level up.

*You must choose either points and/or   requiredActions . Choosing both, however, will require achieving both of them in order to level up.

titlestring or JSON

The title of the level The title has the same format as the name  parameter of this API - it is constructed  of the title in the default language, and also  of a pair or pairs of language codes with their respective level titles:
{
  "default": "< level title in default language >",
   "<language code>":"<level title in specified language>",
  ...
}
The available language codes can be found here
The parameter can be passed as a string only, without the language codes, in which case the string re presents the title of the level in the default language, e.g., "Beginner".

Note: This parameter is optional, but for the best practice implementation, we recommend adding a level title to each level. 

badgeURLstring or JSON

The URL of the icon representing the level badge. The URL has the same format as the name parameter of this API - it is constructed  of the URL in the default language, and also  of a pair or pairs of language codes with their respective URLs:
{
  "default": "< badgeURL in default language >",
   "<language code>":"<badgeURL in specified language>",
  ...
}
The available language codes can be found here.
The parameter can be passed as a string only, without the language codes, in which case the string re presents the badgeURL of the level in the default language.

Note: This parameter is optional, but for the best practice implementation, we recommend adding a badge URL to each level. 

description string or JSONThe description you want displayed for the level.  The description has the same format as the name parameter of this API - it is constructed  of the description in the default language, and also  of a pair or pairs of language codes with their respective descriptions:
{
  "default": "< description in default language >",
   "<language code>":"<description  in specified language>",
  ...
}
The available language codes can be found here
The parameter can be passed as a string only, without the language codes, in which case the string re presents the description of the level in the default language.
lockedBadgeURL string or JSONThe URL of the icon representing the locked level badge. The URL has the same format as the name parameter of this API - it is constructed  of the URL in the default language, and also  of a pair or pairs of language codes with their respective URLs:
{
   "default": "< lockedBadgeURL in default language >",
   "<language code>":"<lockedB adgeURL  in specified language>",
  ...
}
The available language codes can be found here
The parameter can be passed as a string only, without the language codes, in which case the string re presents the lockedB adgeURL of the level in the default language.
actionURL  string or JSONA URL to which a user can be redirected to perform an action and earn points. The URL has the same format as the name parameter of this API - it is constructed  of the URL in the default language, and also of a pair or pairs of language codes with their respective URLs:
{
  "default": "< action URL  in default language >",
  "<language code>":"<actionURL in specified language>",
  ...
}
The available language codes can be found here.
The parameter can be passed as a string only, without the language codes, in which case the string re presents the actionURL of the level in the default language.
bonusintegerThe number of points that will be awarded to the user when the level is reached ("unlocked"). 

You may find more information about level fields in the Adding a New Level section of the Game Mechanics Guide

format string Determines the format of the response. The options are:
  • json (default)
  • jsonp - if the format is jsonp then you are required to define a callback method (see parameter below).
callback string This parameter is required only when the format parameter is set to jsonp (see above). In such cases this parameter should define the name of the callback method to be called in the response, along with the jsonp response data.
context string/JSON This parameter may be used to pass data through the current method and return it, unchanged, within the response.
dontHandleScreenSet Boolean This parameter may be used in order to suppress the showing of screen-sets as a result of API calls. Default is false.
httpStatusCodes Boolean The default value of this parameter is false, which means that the HTTP status code in Gigya's response is always 200 (OK), even if an error occurs. The error code and message is given within the response data (see below). If this parameter is set to true, the HTTP status code in Gigya's response would reflect an error, if one occurred.

Authorization Parameters

Each REST API request must contain identification and authorization parameters.

Some REST APIs may function without these authorization parameters, however, when that occurs, these calls are treated as client-side calls and all client-side rate limits will apply. In order to not reach client-side rate limits that may impact your implementation when using server-to-server REST calls, it is Recommended Best Practice to always sign the request or use a secret. A non-exhaustive list of REST APIs that this may apply to are as follows:

  • accounts.login
  • socialize.login
  • accounts.notifyLogin
  • socialize.notifyLogin
  • accounts.finalizeRegistration
  • accounts.linkAccounts

Please refer to the Authorization Parameters section for details. 

Response Data

FieldTypeDescription
 
errorCode integer The result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Error Codes table.
errorMessage string A short textual description of an error, associated with the errorCode, for logging purposes. This field will appear in the response only in case of an error.
errorDetails string This field will appear in the response only in case of an error and will contain the exception info, if available.
fullEventName string The full name of the event that triggered the response. This is an internally used parameter that is not always returned and should not be relied upon by your implementation.
callId string Unique identifier of the transaction, for debugging purposes.
time string The time of the response represented in ISO 8601 format, i.e., yyyy-mm-dd-Thh:MM:ss.SSSZ or
statusCode integer The HTTP response code of the operation. Code '200' indicates success.
This property is deprecated and only returned for backward compatibility.
statusReason string A brief explanation of the status code.
This property is deprecated and only returned for backward compatibility.

 

Response Example

{
        "statusCode": 200,
        "errorCode": 0,
        "statusReason": "OK",
        "callId": "bb5d9224614946c58a6771a081cddb9a",
        "time": "2015-03-22T11:42:25.943Z"
}