Game-API

The Game-API contains all methods sent to your game from Bigpoint's portal, to allow each user to be channeled directly into your game.

Flowchart explaining registration and login

game.registerAndLogin

The method called “registerAndLogin” is used as soon as a new user needs to be created on your side. Bigpoint's systems keep track of memberships inside games, so if a player wants to play your game but hasn't registered yet, the portal will try to fix this be calling this method in your game.

As soon as you receive this call, you are supposed to create a new user in your own systems and take all necessary steps to generate a new gameplay-session in your game. As this new player will enter your game in an already-logged-in state, the very first login is covered by this method as well.

To enable the player entering the game already-logged-in, the method expects an URL in your response, which will be used to redirect him into your game - to recognize this user, you might use one of the following options:

  • You could use already available session-possibilities of your webserver, thus recognizing the player and his session using the session-key
  • Alternatively you could use the IP-address as it is transmitted in the call to recognize the player entering your game.
  • Or you could use a special token that will only be valid for a certain amount of time right after you have received the call, which will then be used in the URL transmitted back to Bigpoint.

Important: After the user has been channeled into the game using the URL transmitted back to us, you need to give him the chance to choose a new username. Due to the fact that most games contain existing userbases already, it was opted not to force any names during the process.

Parameters in use

Name of Parameter Type Description
partnerID Integer This is the partner-ID assigned to your account when you registered at the DevLounge.
projectID Integer This is the project-ID assigned to your current project. Note that this ID will change for each new instance of your game and after it has been put into live.
bpUserID Integer A numerical representation of an user from Bigpoint's portal. This ID is assigned during the registration-process at the Bigpoint portal and might be different from the userID as used in your game.
affiliateID Integer A numerical represnation of an affiliate-partner of Bigpoint's. This way marketing-efforts and their conversion rates can be tracked.
username String The name of the user self-determined during the registration-process at the Bigpoint portal.
userIP String Current IP-address of the user.
userLang String The language as it was selected by the user at the Bigpoint portal - your game should show the same language when the user enters it (the language codes have 2 (e.g. for 'en', 'de', 'fr') or 5 (only for 'en_US' and 'pt_BR') signs). Important: The Game-API uses ISO-language codes which differ from country-codes (e.g. SE for Sweden, SV for Svenska)
userCountry String The country as detected using Geo-IP-detection and using ISO-notation. (e.g. 'DE', 'GB' or 'FR'). (ISO-Standard 3166-alpha 2)
authTimestamp Double A unix-timestamp containing the current number of milliseconds since the begin of the UNIX epoch (1/1/1970).

Return Codes

On success the following parameters are expected to be returned for this call:

Name of Parameter Type Description
result String Simple string containing “OK”.
userID Integer A numerical ID representing the new user created during the process.
redirectURL String An URL that will be used to channel the user into your game (e.g. http://example.yourproject.com/?loginToken=130834b55f01e6278e4a7f7b23d8e2f4)

In the event of an error, please use an error construct as outlined by the JSON-RPC or XML-RPC specifications. For help on how to create such a construct manually, please refer to the Error Handling wiki-page.

game.login

The “login”-method is called by the portal if it was able to find a game-account associated to the active user, thus no registration at your game is necessary.

If you receive this call, please check the validity of the supplied combination of userID and bpUserID and generate an URL that will channel the user directly into your game. Here are some options to achieve this:

  • You could use already available session-possibilities of your webserver, thus recognizing the player and his session using the session-key
  • Alternatively you could use the IP-address as it is transmitted in the call to recognize the player entering your game.
  • Or you could use a special token that will only be valid for a certain amount of time right after you have received the call, which will then be used in the URL transmitted back to Bigpoint.

Parameters in use

Name of Parameter Type Description
partnerID Integer This is the partner-ID assigned to your account when you registered at the DevLounge.
projectID Integer This is the project-ID assigned to your current project. Note that this ID will change for each new instance of your game and after it has been put into live.
userID Integer A numerical representation of an user in your game. This ID is assigned during the registration-process in your game.
bpUserID Integer A numerical representation of an user from Bigpoint's portal. This ID is assigned during the registration-process at the Bigpoint portal and might be different from the userID as used in your game.
userIP String Current IP-address of the user.
userLang String The language as it was selected by the user at the Bigpoint portal - your game should show the same language when the user enters it (the language codes have 2 (e.g. for 'en', 'de', 'fr') or 5 (only for 'en_US' and 'pt_BR') signs). Important: The Game-API uses ISO-language codes which differ from country-codes (e.g. SE for Sweden, SV for Svenska)
userCountry String The country as detected using Geo-IP-detection and using ISO-notation. (e.g. 'DE', 'GB' or 'FR'). (ISO-Standard 3166-alpha 2)
authTimestamp Double A unix-timestamp containing the current number of milliseconds since the begin of the UNIX epoch (1/1/1970).

Return Codes

On success the following parameters are expected to be returned for this call:

Name of Parameter Type Description
result String Simple string containing “OK”.
redirectURL String An URL that will be used to channel the user into your game (e.g. http://example.yourproject.com/?loginToken=130834b55f01e6278e4a7f7b23d8e2f4)

In the event of an error, please use an error construct as outlined by the JSON-RPC or XML-RPC specifications. For help on how to create such a construct manually, please refer to the Error Handling wiki-page.

game.getUserStats

Using “getUserStats”, the Bigpoint portal will request statistical information about an user for display on his profile page. This currently amounts to:

  • Virtual currency balance of the user
  • Real currency balance of the user
  • Current rank or level of the user in your game.

If your game doesn't discern between two different currencies, feel free to leave one value empty. In the Bigpoint ecosystem, real currency is the money that can be purchased using the Bigpoint payment.

Parameters in use

Name of Parameter Type Description
partnerID Integer This is the partner-ID assigned to your account when you registered at the DevLounge.
projectID Integer This is the project-ID assigned to your current project. Note that this ID will change for each new instance of your game and after it has been put into live.
userID Integer A numerical representation of an user in your game. This ID is assigned during the registration-process in your game.
bpUserID Integer A numerical representation of an user from Bigpoint's portal. This ID is assigned during the registration-process at the Bigpoint portal and might be different from the userID as used in your game.
authTimestamp Double A unix-timestamp containing the current number of milliseconds since the begin of the UNIX epoch (1/1/1970).

Return Codes

On success the following parameters are expected to be returned for this call:

Name of Parameter Type Description
result String Simple string containing “OK”.
virtualCurrency Integer The user's current balance of virtual money in your game - in the Bigpoint ecosystem, virtual currency is money that can be earned by playing the game.
realCurrency Integer The user's current balance of real money in your game - in the Bigpoint ecosystem, real currency is money that can only be earned by using the Bigpoint Payment.
userRank (Optional) Integer Aktueller Rang oder Level des Spielers in ihrem Game.

In the event of an error, please use an error construct as outlined by the JSON-RPC or XML-RPC specifications. For help on how to create such a construct manually, please refer to the Error Handling wiki-page.

game.deleteUser

At the Bigpoint portal, any user has the ability to delete his game-accounts at the time of his liking. To enable this feature in games connecting to Bigpoint using the Devlounge, the “deleteUser”-method was introduced.

If you receive this call, you can decide whether you want to delete the specified user's account complete or just freeze this account, thus making it dormant. There is no “right” way to do this, as this is dependent on your game's design.

Important: If you are just putting an account in a dormant state, please be aware that the same user might choose to play your game again. You will receive another “registerAndLogin”-call and the user might want to choose his old username back. Make sure that your systems are covering this usecase as well as the simple deletion of an account.

Parameters in use

Name of Parameter Type Description
partnerID Integer This is the partner-ID assigned to your account when you registered at the DevLounge.
projectID Integer This is the project-ID assigned to your current project. Note that this ID will change for each new instance of your game and after it has been put into live.
bpUserID Integer A numerical representation of an user from Bigpoint's portal. This ID is assigned during the registration-process at the Bigpoint portal and might be different from the userID as used in your game.
userID Integer A numerical representation of an user in your game. This ID is assigned during the registration-process in your game.
authTimestamp Double A unix-timestamp containing the current number of milliseconds since the begin of the UNIX epoch (1/1/1970).

Return Codes

On success the following parameters are expected to be returned for this call:

Name of Parameter Type Description
result String Simple string containing “OK”.

In the event of an error, please use an error construct as outlined by the JSON-RPC or XML-RPC specifications. For help on how to create such a construct manually, please refer to the Error Handling wiki-page.

en/apis/game-api.txt · Last modified: 2012/08/31 10:08 (external edit)
www.chimeric.de Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0