What?
This page describes the API for external app developers who wish to save game sessions in the personal data store of a GameBus user.
Why?
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?
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
- 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:
- how you can obtain GameBus OAuth tokens specific to your app/wearable/website (general GameBus token information is already available here),
- what are the IDs for your game descriptor and its corresponding properties.
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://APPID@api.gamebus.eu/ where APPID is an ID unique to your integration
- 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.
That’s all!