Documentation

Retrieve User's Badge Status

From KickApps Documentation

Jump to: navigation, search

Contents

Overview

This method returns the list of all badges for a given location, and the progress towards achieving said badges for a given userId. This specifically uses the Badge Requirements Data and the User Action data to return what requirements the user needs to meet to attain each badge (if not already achieved).


Request URL 

http://api.kickapps.com/rest/user/badges/getstatus/{as}


Request Parameters

Required

  • t - the user token generated via the "Create Token" API call.
  • as - The site Id to search. as is unique for each of the affiliate's sites.
  • user_id – the ID of the user whose badges are being retrieved.


Optional

  • location – A location identifier that corresponds to a page / area within the community. When not provided, all locations are returned. For this iteration of the API it is assumed that Client will handle creation of these identifiers in their existing CMS system.
  • callback. String. Optional. The name of your JavaScript callback function.
  • pgNum. The current page number in the search results. For your first call, set pgNum to "1". For subsequent calls, set pgNum to the page you want to display. If not provided, this value is defaulted to 1.
  • pageSize. The number of results to display on each page. Max pageSize is "1000". If not provided, this value is defaulted to 10.

Response

Note: if callback is provided as an optional argument, the results illustrated below will be returned within the callback string provided for execution of a JavaScript function; e.g. callback=”MyCallbackFunc” will return something similar to: 

MyCallbackFunc({…the success or failure response contained in curly braces you see below…});
</code>

<code lang="javascript">
Success:
{
   "status":1,
   "totSize":100,
   "userId":"1234",
   "badges":[
      {
         "location":"XXXX",
         "badgeId":"1",
         "name":"Good Badge",
         "verbosename":"Good Badge, good, good badge",
         "url":"http://www.kickapps.com/image1.png",
         "link":"http://someurlontheweb.com" ,
         "awarded":true
      },
      {
         
         "location":"XXXX",
         "badgeId":"2",
         "name":"Good Badge plus",
         "verbosename":"Good Badge, good, good badge plus",
         "url":"http://www.kickapps.com/image2.png",
         "link":"http://someurlontheweb2.com" ,
         "awarded":false,
         "remainingRequirements":[
            {
               "actionId":"1",
               "quantity":"1",
               "location":"51, area",
               "requirementId":"1"
            },
            {
               "actionId":"2",
               "quantity":"3",
               "location":"area 42",
               "requirementId":"91"
            }
         ]
      }
   ]
}

Failure:  {"status": -1, "errorId": "123", "error": "Error Message"}


Response Parameters

  • status – 1 on success and -1 on error.
  • totSize – Indicates the total number of badges this user + location has status for.
  • error – A message indicating the error condition
  • errorId – A numeric reference to the error condition
  • userId – the ID of the user whose badges are being retrieved.
  • location – A location identifier that corresponds to a page / area within the community. For this iteration of the API it is assumed that Client will handle creation of these identifiers in their existing CMS system.
  • badges – The set of all badges for a given userId and location:
  • badgeId – The ID of the badge.
  • name – The Name of the badge.
  • verbosename – The Verbose Name of the badge.
  • url – A URL to the badge's image file.
  • link – A link/url associated with this badge.
  • awarded – Boolean value that indicates whether or not the user has been awarded the badge.
  • remainingRequirements – This is a conditional set of remaining requirements for badges that haven't been awarded to the user. This element will not exist if awarded = true.
  • actionId – The ID of the action the user still needs to complete to receive the badge.
  • quantity – The number of times the action must be completed by the user to receive the badge.
  • location – A location identifier that corresponds to a page / area within the community.
  • requirementId - The badge requirement ID of an existing badge requirement in the system.


Error codes:

  • 1 = invalid token
  • 8 = location cannot be blank
  • 13 = invalid userId
  • 16 = Invalid pgNum
  • 17 = Invalid pageSize
  • 20 = location cannot exceed 64 characters
  • 25 = pageSize cannot exceed 1000
  • 44 = token required


List of KickApps API Calls


Note: Occasionally (and without advanced warning) we modify our API calls by adding new parameters in the response payload. Please keep this in mind when designing your strategy for parsing our responses.

Retrieved from "http://www.kickapps.com/documentation/index.php/Retrieve_User%27s_Badge_Status"