While exploring the Gamification service, I came across few blogs like Hands On: Using the SAP HCP Gamification Service and Integrating SAP HANA Cloud Platform Gamification Service into an Issue Tracking Tool (JIRA) which are really helpful in understanding the concept and the features of this service with in depth technical information. When the real use case is on applying the gamification concepts using some game design techniques along with engaging and motivating people to achieve their goals, the APIs of Gamification platform plays a big role and act as the central integration point of the gamified application. This blog is just to explain how and from where we can consume these Web APIs that are provided from Gamification service.
From SAP HCP standpoint, Gamification Service web API is based on JSON-RPC (JavaScript Object Notation Remote Procedure Call), a very simple protocol for calling Java methods remotely using a JSON-based serialization via HTTP POST. Authorization is generally based on roles.
The web APIs mostly consist of 2 endpoints.
- Technical endpoint for backend Integration: /gamification/api/tech/JsonRPC: This is used to send gamification relevant events and perform user/player management task from application backend.
- User endpoint for frontend integration: /gamification/api/user/JsonRPC: This endpoint is used to implement an user profile that comes with the gamification service subscription as an iFrame in the application's web front end.
The Integration Overview Architecture diagram is provided below. This shows how a gamified application (gamified app) running on SAP HANA Cloud Platform is typically integrated with the gamification service.
Using the Technical Endpoint:
- Create technical user and assign roles via the HCP Cockpit. The following roles are available for the technical endpoint:
- App Standard: Send events, read achievements
- App Admin: User management
- Create new request in REST client (e.g. POSTMAN) and configure it to use BASIC authentication, i.e. set header field “Authorization” to value “Basic” + Base64-encoded "username:password" for requests.
- Send request
Using the User Endpoint:
Integration of the user endpoint should normally be done via the available ProxyServlet in combination with App-to-App SSO destinations. For manual testing of calls follow the procedure below:
- Assign roles via HCP Cockpit. User can have the following roles:
- GamificationDesigner: Modify game mechanics; import apps; read aggregated player data and analytics
- GamificationReviewer: Read game mechanics; read aggregated player data and analytics
- TenantOperator: Read game mechanics; full app management; modify player data
- Player: Read own achievements; edit own profile; read team inforamtion
- Open Browser and logon to gamification service via IDP, e.g. by opening the workbench.
- Open REST client (e.g. POSTMAN) in same browser (otherwise SAML token is not available).
- Get XSRF token by executing a HTTP GET on the user endpoint with the following header set: Key: "X-CSRF-Token", Value: “Fetch”.
- Extract XSRF token from response headers. Key= X-CSRF-Token
- Create new request in REST client (e.g. POSTMAN) and include token in request header field “X-CSRF-Token”.
- Send request
Opening the API Documentation:
We can navigate to API Documentation for Gamification service from the Gamification workbench launching page under "Help" link.
On opening the API Documentation, we can navigate to the page where all the API information related to all set of interactions and integration points that the service is providing.
These are the set of API documentation links, that are currently supported ( Even the deprecated ones are also highlighted for easy reference)
- IAdminAPIExternal (JavaSDK 1.18.1 API)
- IRuleAPIExternal (JavaSDK 1.18.1 API)
- IEntityQueryAPIExternal (JavaSDK 1.18.1 API)
- IEntityUpdateAPIExternal (JavaSDK 1.18.1 API)
- IImportExportAPIExternal (JavaSDK 1.18.1 API)
- IAnalyticsAPIExternal (JavaSDK 1.18.1 API)
- IPlayerAPIExternal (JavaSDK 1.18.1 API)
- IAppAPIExternal (JavaSDK 1.18.1 API)
- IRuleEngineProxyExternal (JavaSDK 1.18.1 API)
Using these API, several operations can be performed on Workbench and they can be controlled directly from the Gamified application. I have tried to show some examples in general on how to use those APIs.
- IAppAPIExternal: For App management:Method name: getApps(): This returns the list of Apps in the currently logged in gamification Workbench:
The response is returned by reading the Applications list from Workbench:
{
"result": [
{
"name": "HelpDesk",
"description": "This is our help desk app.",
"owner": "helpdesk@sap.com",
"autoCreatePlayers": false
},
{
"name": "defaultApp",
"description": "default app, can not be deleted",
"owner": "none",
"autoCreatePlayers": false
}
],
"error": null
}
- Creating a new App using API: Method: createApp:
Request URL: https://gamification-p1173326trial.hanatrial.ondemand.com/gamification/api/tech/JsonRPC?json={"method":"createApp", "params":["MyDemoApp", "Testing from API", "Sourav", true]}Response:
{
"result": {
"name": "MyDemoApp",
"description": "Testing from API",
"owner": "Sourav",
"autoCreatePlayers": true
},
"error": null
}
Reading data related to gamification users: (Players):
Lets try to read for mine :smile:
Request:: https://gamification-p1173326trial.hanatrial.ondemand.com/gamification/api/tech/JsonRPC?json={"method":"getNotificationsForPlayer", "params":["P1173326", 1464589586]}&app=HelpDesk
Response:
Creating a notification for some External gamified Application: here let us use the HelpDesk application for example. We will create a new notification using API that will be consumed in this application.
Request: https://gamification-p1173326trial.hanatrial.ondemand.com/gamification/api/tech/JsonRPC?json={"method":"addCustomNotificationToPlayer","params":["P1173326", "congratulations Sourav for your new achievement", "POINT", " Experience Points"]}&app=HelpDesk
Response:
This will create a custom Notification for that player and he can get it in the Notifications Tab:
How to consume the APIs from Java application:
Unlike any kind of API calls, the request needs to be built from the Gamified application itself. for example, if in your application, you want to create players(gamification users) for your application, you can use the method createPlayer and build the request as shown below:
com.sap.gamification.views.PlayerView createPlayer(String playerId,String playerName,boolean isPublic, com.sap.gamification.communication.send.GamificationFile image)
Code snippet for building the request:
private boolean createPlayer(String playerId) throws ClientProtocolException, IOException, DestinationException, NamingException {
String jsonRPCrequest = "{\"method\":\"createPlayer\",\"params\":[\"" + playerId + "\"]}";
String gamificationServiceResponse = sendGamificationEvent(jsonRPCrequest);
JsonParser parser = new JsonParser();
JsonObject result = (JsonObject)parser.parse(gamificationServiceResponse);
if (result.get("result").toString().equals("true")){
return true;
}
else {
return false;
}
}
To implement a user profile or single widgets (for example a progress bar tailored to the application's front end), it is recommended to use the user endpoint in combination with a local proxy servlet (shown in below screenshot for Helpdesk application, the code for the same is available in github https://github.com/SAP/gamification-demo-app) and an app-to-app SSO destination. The proxy servlet prevents running into cross-site scripting issues and the app-to-app SSO destination automatically forwards the credentials of the authenticated user to the gamification service. This allows reuse of the access control mechanisms offered by the gamification service.
You can browse through all the Web APIs from the documentation and test it from any RESTFUL client on the functionality and based on the response, you can process it in your own gamified application as per. For more information on Code snippet, please refer to the demo helpdesk application from the following link
- SAP Managed Tags:
