Portal-API

In contrast to both other APIs, this one contains methods for you to call at Bigpoint's side. Among others, here you can request the deletion of an user's gameaccount or send an user a specific email (e.g. a registration confirmation mail).

portal.sendUserMail

Using the “sendUserMail”-call, you can send emails to specifically targeted users. You need to create these mails in the content-area of the Devlounge first, as you need an existing sysmail-ID for this call to work.

The system doesn't differentiate between mails containing only text and those composed using HTML, as the sending of mails is handled by Bigpoint's own mailing systems.

However, if you want to send an email to a bulk of users, you might be better off using the newsletter-feature in the Livecare-area of the devlounge, which does not require you to send any calls at all.

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.
sysMailID Integer The ID of the system-mail created in the Devlounge setup wizard.
userID Integer A numerical representation of an user in your game. This ID is assigned during the registration-process in your game.
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 (5 signs: 'en_US', 'pt_BR' (only those two), 2 signs (examples): 'en', 'de', 'fr', …). Important: The Game-API uses ISO-language codes which differ from country-codes (e.g. SE for Sweden, SV for Svenska)
params Struct If the system-mail you created contains placeholders, they will be replaced with the values in this hash (array('foo' ⇒ 'bar') will replace the placeholder '{foo}' with 'bar'). Please make sure that this associative array uses the exact placeholders' names as array-keys, the replacement will fail otherwise.
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.

portal.getPageTags

Bigpoint's success is in no small part due to it's exceptional relationships with external partners and its ability to make its games available for marketing.

To this regard, Bigpoint's games can contain anything from special branding images to special tracking pixels and additional marketing code, that is injected directly into a game's website depending on the given parameters.

Now you can profit from this system as well: Using the “getPageTags”-method, you can request the needed HTML-code for injection in your own site:

  • headTag - Contains HTML code that needs to be injected right into the <head>-area of your site.
  • startTag - Contains HTML code that needs to be injected right after the opening <body>-tag.
  • endTag - Contains HTML code that needs to be injected right before the closing </body>-tag.
  • affiliateTitle - Additional text for use in the <title>-tag.
  • popupTag - Additional code for affiliate-popups.
  • firstLoginTag - Additional tracking-code that should only be displayed at the time of an user's first login.
  • thirdLoginTag - Additional tracking-code that should only be displayed at the time of an user's third login.

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 will be different from the userID as used in your game.
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 (5 signs: 'en_US', 'pt_BR' (only those two), 2 signs (examples): 'en', 'de', 'fr', …). Important: The Game-API uses ISO-language codes which differ from country-codes (e.g. SE for Sweden, SV for Svenska)
pageID String An unique string identifier for your current page. Please make sure that you don't use the same identifier twice.
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”.
headTag String HTML code for inclusion in the <head>-area of your site.
startTag String HTML code for injection right after the opening <body>-tag.
endTag String HTML code for injection right before the closing </body>-tag.
affiliateTitle String Additional text for the <title>-attribute of your site.
popupTag String HTML code that might trigger the opening of a partner's popup.
firstLoginTag String HTML code that should be injected at the time of an user's first login.
thirdLoginTag String HTML code that should be injected at the time of an user's third login.

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.

portal.getGeneralPageTags

This method allows you to get all necessary HTML code pieces to integrate a partner's tracking pixels into your site, just like the “getPageTags”-call.

The important difference in this case is the possibility to use these tags on a page where the user is not in a logged-in state. As there is no affiliate information available for a given user, you need to supply this information with the call.

As before, the response will contain the following pieces of HTML code:

  • headTag - Contains HTML code that needs to be injected right into the <head>-area of your site.
  • startTag - Contains HTML code that needs to be injected right after the opening <body>-tag.
  • endTag - Contains HTML code that needs to be injected right before the closing </body>-tag.
  • affiliateTitle - Additional text for use in the <title>-tag.
  • popupTag - Additional code for affiliate-popups.

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.
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 (5 signs: 'en_US', 'pt_BR' (only those two), 2 signs (examples): 'en', 'de', 'fr', …). Important: The Game-API uses ISO-language codes which differ from country-codes (e.g. SE for Sweden, SV for Svenska)
pageID String An unique string identifier for your current page. Please make sure that you don't use the same identifier twice.
affiliateID (Optional) Integer This parameter contains the affiliateID - if your site has been requested with an aid, please make sure to transmit its value here as well.
affiliateParameter (Optional) String This parameter contains the affiliate parameters- if your site has been requested with an aip, please make sure to transmit its value here as well.
affiliateGroup (Optional) Integer This parameter contains the affiliate group information - if your site has been requested with an aig, please make sure to transmit its value here as well.
affiliateCm (Optional) Integer This parameter contains the affiliate cross marketing information - if your site has been requested with an acm, please make sure to transmit its value here as well.
affiliateCr(Optional) Integer This parameter contains the affiliate cross reference - if your site has been requested with an acr, please make sure to transmit its value here as well.
affiliateHost (Optional) String If your game can be accessed using a special domain for a specified partner, please make sure to send this information back to the API using this parameter (e.g. mtv.mygame.com).
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”.
headTag String HTML code for inclusion in the <head>-area of your site.
startTag String HTML code for injection right after the opening <body>-tag.
endTag String HTML code for injection right before the closing </body>-tag.
affiliateTitle String Additional text for the <title>-attribute of your site.
popupTag String HTML code that might trigger the opening of a partner's popup.

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.

portal.deleteUser

Sometimes you might want to delete users that have been inactive for a very long time. Up until now, this lead to problems, as the Bigpoint portal still had a game account associated with your game saved in the respective user's account.

To delete this association, you can now call “deleteUser”, which will delete the account from the player, enabling him to join your game at any time again.

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 will 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”.

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.

portal.registerToInstance

If you are running more than one instance within your game, you should consider providing an internal instance selection to your users, which may contain some specific instance information (e.g. count of users, start date, etc.). You may use this method to tell us which instance the user actually starts to play. Consequences of not integrating this method would be potential problems with connecting payments to the instance and (or) problems within the accounting for your game.

IMPORTANT: If the user tries to login to the instance again, please use the ”portal.loginToInstance” method to tell us, otherwise the user’s instance account will be deleted/deactivated in our global account system due to inactivity.

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 (this is the userID of the existing account!).
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.
instanceID Integer This is the project-ID of the instance where the user started to play.
instanceUserID Integer A numerical representation of the user at the new instance.
authTimestamp Double A unix-timestamp containing the current number of milliseconds since the begin of the UNIX epoch (1/1/1970).

Return CodesReturn Codes

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

Name of Parameter Type Description
result Bool Shows if the creation of the instance account was successfull. Represents the whole result value (no array will be returned by this method)

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.

portal.loginToInstance

If you are running more than one instance within your game, you should consider providing an internal instance selection to your users, which may contain some specific instance information (e.g. count of users, start date, etc.). You may use this method to inform us about the user’s login to the instance. Failure to do so will result in the deletion of the user’s instance account after approx. 6 month due to inactivity.

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.
instanceID Integer This is the project-ID of the instance where the user logged in.
instanceUserID Integer A numerical representation of the user at the instance.
authTimestamp Double A unix-timestamp containing the current number of milliseconds since the begin of the UNIX epoch (1/1/1970).

Return CodesReturn Codes

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

Name of Parameter Type Description
result Bool Shows if the login into the instance was successfull. Represents the whole result value (no array will be returned by this method)

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.

portal.register (client method only)

In the case you want to integrate a client-game with the Devlounge, you can use special methods that are only available to client-based games.

You basically submit the same information to the Portal-API as will Bigpoint's own registration process. You need to handle the input and transmission however, as well as checking the availability of your game for certain provinces or countries.

Just like the iFrames, the registration processed started by this call will result in Game-API-calls being sent to your game, so you just need to implement the registration process on your end once.

Important: The Portal-API will check the availability of the supplied username and return an error if the name is already taken. You need to check the availability in your own game as well, however and make sure that all errors during this process are displayed in an informative way.

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.
username String The username as entered by the user. Limited to 4-20 signs.
password String The password as entered by the user. Limited to 4-20 signs.
email String The email address as entered by the user.
birthday String The birthday as entered by 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 (5 signs: 'en_US', 'pt_BR' (only those two), 2 signs (examples): 'en', 'de', 'fr', …). Important: The Game-API uses ISO-language codes which differ from country-codes (e.g. SE for Sweden, SV for Svenska)
userIP String The user's IP, which he is using during his registration
betacode (Optional) String If you have created a closed beta program for your game in cooperation with Bigpoint, you users might have received special beta keys. These keys will allow an user to create a new account in your game. If they don't have a valid code (and your game requires one), the registration will fail.
newsletter Boolean indicates, if the user wants to receive game related newsletters
partnerNewsletter Boolean indicates, if the user wants to receive newsletters from Bigpoint's affiliate partners
affiliateID (Optional) Integer This parameter contains the affiliateID - if your site has been requested with an aid, please make sure to transmit its value here as well.
affiliateParameter (Optional) String This parameter contains the affiliate parameters- if your site has been requested with an aip, please make sure to transmit its value here as well.
affiliateGroup (Optional) Integer This parameter contains the affiliate group information - if your site has been requested with an aig, please make sure to transmit its value here as well.
affiliateCm (Optional) Integer This parameter contains the affiliate cross marketing information - if your site has been requested with an acm, please make sure to transmit its value here as well.
affiliateCr(Optional) Integer This parameter contains the affiliate cross reference - if your site has been requested with an acr, please make sure to transmit its value here as well.
affiliateHost (Optional) String If your game can be accessed using a special domain for a specified partner, please make sure to send this information back to the API using this parameter (e.g. mtv.mygame.com).
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 The numerical ID the user received in your game during the registration process.
bpUserID Integer The numerical ID the user received when he registered at the Bigpoint portal.

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.

portal.checkLogin (client method only)

Just like the method for registering new users directly, “checkLogin” allows you to check the entered username and password at Bigpoint's systems.

To ease the whole process, users that already got a portal account will be silently registered in your game in the background and don't need to register again just to play your game.

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.
username String The username as entered by the user.
password String The password as entered by 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 (5 signs: 'en_US', 'pt_BR' (only those two), 2 signs (examples): 'en', 'de', 'fr', …). Important: The Game-API uses ISO-language codes which differ from country-codes (e.g. SE for Sweden, SV for Svenska)
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 The numerical ID the user received in your game during the registration process.
bpUserID Integer The numerical ID the user received when he registered at the Bigpoint portal.

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.

portal.requestPassword (client method only)

If an user forgot his password, he might still try to recover his account be requesting the password to be mailed to the email-address he registered with.

For this method to work, you need to send at least a username or an email-address or both. If you only have one of these two available, you can leave the other parameter blank.

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.
usernameOrEmail String Name OR e-mail of the user who requested his password to be mailed to him.
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.

portal.changePassword (client method only)

If an user chooses to change his password, this method will help (Password change will only affect game account, not the portal account). Important: the user has to be logged in.

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.
oldPassword Integer old password of logged in user
newPassword Integer new password
userID Integer A numerical representation of an user in your game. This ID is assigned during the registration-process in your game (this is the userID of the existing account!).
userLang Double The language the user chosed to log into. You can either select this parameter with the two-lettered shortcut ('en' or 'de') or as full local-code (only for 'en_US' or 'pt_BR').

Return Codes

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

Name of parameter Type Description
result boolean true/false
en/apis/portal-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