The GameBus OAuth Token

Please contact us if you want to learn more about API functionality beyond what is documented here. The API should be accessed via HTTPS REST calls with JSON payload and an OAuth 2 token in the Authorization header. In the following, we describe how to get a user-specific token for your app/website/device.

Request a OAuth Token

If you are a developer of a mobile health app (or any app that can benefit from the GameBus leaderboards) then you may want to access the GameBus API directly from the end user’s mobile device. We can make available an app-specific token on the end user’s file system.


For the sake of prototyping, you can rely on the following example file content:

{
	"playerId":	100023,
	"token":	"c7665dad-cbae-4037-a49a-c19b86fea1a0"
}

If you manage to push activity data for this test user with name “Fien”, then please contact us. We will check the maturity of your integration and

  • provide a “connect” button for your app in the GameBus base app, and
  • provide you with a decrypt key for accessing from the user device’s filesystem a token file dedicated to your app.

GameBus Token for your website/device

If you are not providing an app on the end user’s device, we can provide from within the GameBus base app a “connect” button which will send the OAuth token to your website. You are expected to provide a user login page and store the token for future use for that user.

API for pushing GameSessions

Integrating an external game with the GameBus Open API enables GameBus sponsors to define challenges in terms of sessions of that external game. Then, furthermore, end users can gain GameBus points by playing the external game. As the developer of mobile games, there are various incentives for realizing this integration:

  • apps integrated with GameBus are part of a more holisitic, social gaming experience;
  • apps in the GameBus ecosystem will benefit from the large scale marketing efforts that will be performed in 2016 and beyond;
  • developers without much expertise in server-side development can use the GameBus personal data store as a convenient "database as a service" (note: this page does not document how to read again the sessions that were saved by an app -- please contact us if you are interested in this capability);
  • similarly, developers can save operational costs since they no longer need to maintain their own database server for saving game states (the same note applies here).

How to use the API

First, the external app needs access to a user-specific token for the GameBus API.

Second, the external app needs to describe its metadata on the GameBus platform. Specifically, you will have to provide a so-called "game descriptor" for the app, listing which properties are available for each game session. For each property, a type needs to be specified. The currently -available types are: BOOL, COORDINATE, DATE, DOUBLE, INT, PERCENTAGE, STRING, and TIME.

In summary, for your external app, you should supply the following metadata:

  • A name for the game descriptor (e.g., the name of the external app),
  • A list of properties, with their corresponding type.

In order to register your game descriptor, please contact info@GameBus.eu. Please also clarify how you plan to explain to end users what kind of data you are sending to GameBus. Specifically, please send us your (draft) policy description, so we can include it later in the GameBus terms of use / privacy policy. We will contact you soon after, clarifying:


Once you have your own game descriptor, you can finalize the actual integration code. In the following, we assume that we have registered your game descriptor and we also assume that your external app has access to a user-specific GameBus OAuth token.

To push a new session, you should make an HTTPS REST call with JSON payload and an OAuth 2 token in the Authorization header.

API Base URL: https://gamebus.synersec.eu/
Path to the service for inserting new sessions: /activity/new
Method: POST 
Payload example:
{
	"gameDescriptorId": 101,
	"properties": [
		{
			"id": 		1001,
			"value": 	"2015-09-29",
			"name": 	"Started at date",
			"type": 	"DATE"
		},
		{
			"id": 		1002,
			"value": 	"01:30 AM",
			"name": 	"Started at time",
			"type": 	"TIME"
		},
		{
			"id": 		1003,
			"value": 	72,
			"name": 	"Seconds to Complete",
			"type": 	"INT"
		},
		{
			"id": 		1004,
			"value": 	321,
			"name": 	"Score",
			"type": 	"INT"
		},
		{
			"id": 		1005,
			"value": 	123,
			"name": 	"Level",
			"type": 	"INT"
		}
	]
}

In this example, the name and type attributes are provided just for documentation purposes. They are fully ignored by our API since the actual property name and type information is already known inside GameBus. Put differently, only the attributes id and "value" matter in the array of property instance.