Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Web and WebWorks Development

Reply
Developer
peardox
Posts: 1,229
Registered: ‎03-20-2011
My Device: Playbook, Z10 LE, Dev Alpha B, 2x Dev Alpha C

Scoreloop for BB10

Hi all

 

In the next few days / week I will release a Scoreloop API

 

This was a hard one but I'm very close to a Scoreloop API for WebWorks

 

I have a few things left to fill in but its functional under BB 10.1 (10.2 is being wierd)

 

I expect these issues to be sorted within sort order (BB want this too)

 

Inorder to give you a heads up here's the API - note that currently missing essentials such as accept/reject a challenge and awards are on the before v 1.0

 

 

Introduction and Background Information
=======================================

The main core of Scoreloop is entirely callback based.

Every function returns a JSON object that includes, at a minimum, status [true|false] and rc [Integer error code].
If status is true then everything is OK, if false rc holds the Scoreloop SC_Error_h code (as defined in scoreloop/sc_errors.h)

Many functions take a JSON argument object and / or a callback so the basic format of any call to this extension is...

Like the calling function callbacks all return a JSON object of the same format (status, rc and optional payload)

rval = community.scoreloop.SOMEFUNCTION{[Argument Object], [Callback Object]);

It is important to check the returns from both the calling function and the callback. If the calling function fails the callback
will never happen. If the callback has an error there will be no useful data.

Basic Usage
===========

1) Sign up at https://developer.scoreloop.com and generate a set of keys for your project as you will need these in the next step

2) In JavaScript starting Scoreloop is as simple as follows...

var res = JSON.parse(community.scoreloop.start( {
        slGameId : "dad29bdb-8eba-4130-8090-ad36608b8d63",
        slGameSecret : "AwLYqVR2KcysTFglIkATlqTf48GXcZ6j2/045YMNDU717AD+9nV25w==",
        slGameVersion : "1.0",
        slCurrency : "AIA",
        slLanguageCode : "en"
        } ) );

Replace the above keys with your own from (1)

3) Check res.status is true, if so you're all ready to go.

Some Notes On Web Inspector
===========================

The start function has an entry counter on it to facilitate debugging in Web Inspector. Pressing F5 in web inspector is safe and
start will return a true - it just wont actually do anything, the increased value of the returned entry_count member of the
returned object denotes how many times start has been called for reference.

To explain this further. Web Inspector loads the extension which immediately initializes the library and puts it in a state whereby
it is ready for use. The start call then creates a Scoreloop client which can send and recieve information from Scoreloop. If running
under Web Inspector and F5 is pressed the library has already been initialized and a client already created using the already passed
credentials - obviously not what you want to do...

The extension therefore ignores any repeat requests to start Scoreloop.

It is advisable, at least while testing, to have a page before the main app as demonstrated in the sltest sample application. Such a
page allows you to debug what happens when Scoreloop is started up if anything odd is happening.

Logging
=======

The Scoreloop extension includes a very basic internal logging system. This is useful in the event that you want to know what's
happening inside the extension. The log is written to data/file.txt within the app and as such can be read by any means the developer
desires. The community.scoreloop.readlog() function returns an object with the log member set to the unformatted text of the log file.

Something like the following will let you inspect it in-app

    res = community.scoreloop.readlog();
    var txt = "";
    
    if(res) {
        txt = res.log.replace(/\n/g, '<br />');
        }
    document.getElementById('logpage').innerHTML = txt;

Awards
======

The Scoreloop developer site includes a (buggy) Award definition section which allows you to assign awards to end-user achievements.

It should be noted that the reward field allows you to grant the player in-game currency. What is not obvious is that Scoreloop returns
the number of coins you have (think cents) but the quantity of currency given as a reward is in 1.xx coins (think dollars). This means
a reward of 1 is 100 coins while a reward of 0.10 is 10 coins.

The currency quirk is present in other areas of the developers site. Most notably the In-Game Currency section which includes an Initial
Credit field which is 15.0 (1500 coins) by default - every player gets 1500 coins as a start-up freebie unless you change this section.

If you use Awards / Achievements in your project then you will need to click the Download Bundle button in the Awards page. Select the
download-json option when presented with the chance and save the resultant ZIP file to disk.

The awards bundle SLAwards.bundle directory extracted from sl_awards_bundle.zip needs to be placed in a directory called scoreloop in
your application so Scoreloop knows where to look for it in oder to find scoreloop/SLAwards.bundle/Info.json used internally to assign
awards within Scoreloop.

It should be noted that any Award updates to your project require the SLAwards.bundle to also be updated. This may be possible to
automate using a private server JSON or Manifest.mf mechanism but has not been tested at the time of writing.

Scores
======

Scoreloop allows the recording of two scores when submitting to the server. The majorScore is the score the user typically sees
on-screen. The minorScore allows the developer to differentiate between the same value for majorScore. The minorScore value is
optional, you can just set it to zero all teh time and ignore it. Uses for minorScore could be anything from number of baddies killed,
the time taken to achieve the majorScore or the percentage kill-ratio.

The choice of whether to use minorScore and if so how is left to the developer.

The Score Definition section of the Scoreloop developer site allows you to configure how rankings work based on these scores and the
level the user is playing at.

Modes and Levels
================

Scoreloop includes two classifications about any score recorded called Level and Mode.

Level is fairly self-evident but can be used as the developer desires.

Mode is far more abstract. It is important to note that Mode filters the data that is returned in Leaderboard requests. The mode
option can either be always zero (one leaderboard) or can offer a number of different modes. A suggested example on the Scoreloop
developer site is that you could assign one mode per country. Other uses could be such things as allowing factions / clans in your
product or showing leaderboards for specific expansions you offer the user.

Modes are up to the developer as to how to utilize.

The API
=======

Currently the API supports a basic set of features which are being added to as required / possible

In all cases the rc member of the returned objects wants to be zero (no error), anything else denotes an error.

1) community.scoreloop.start( args_object );

Starts Scoreloop

args_object   =    slGameId         : <Game ID from Scoreloop>
                slGameSecret     : <Game Secret from Scoreloop>
                slGameVersion     : <Game Version>
                slCurrency         : <Game Currency Code from Scoreloop>
                slLanguageCode     : <Langugae code(s)>

return_object =    status : [true|false]
                rc : <Return Code>
                entry_count     : <Calls made to start, ideally = 1>
                aGameId         : <slGameId passed to Scoreloop>
                aGameSecret     : <aGameSecret passed to Scoreloop>
                aGameVersion     : <aGameVersion passed to Scoreloop>
                aCurrency         : <aCurrency passed to Scoreloop>
                aLanguageCode     : <aLanguageCode passed to Scoreloop>


2) community.scoreloop.getuser( callback ); *** IMPORTANT ***

Get / Update information about the user. It is important that this call be made directly after start as some data this collects is used
by other functions in the extension.

This call additionally updates the amount of coins a player has at their disposal and as such should also be called after challenge or
award / achievement calls so your project knows what the player has available to them.

return_object = status             : [true|false]
                rc                 : <Return Code>

callback_data =    status             : [true|false]
                rc                 : <Return Code>
                coins             : <Number of coins the player has>
                login             : <The player's login ID>
                image             : <The player's image/avatar if set on Scoreloop>


3) community.scoreloop.getbuddlist( callback );

Get the player's Buddy list.

return_object = status             : [true|false]
                rc                 : <Return Code>

callback_data =    status             : [true|false]
                rc                 : <Return Code>
                buddylist_c        : <Number of entries in buddylist>
                buddylist        : <An array of the player's buddylist>
                    login         : <The buddy login ID>
                    image        : <The buddy image/avatar if set on Scoreloop>


4) community.scoreloop.setscore( args_object, callback );

Record a score on Scoreloop for inclusion in leaderboards

The callback of this function has no payload apart from whether it worked or not and as such is optional

args_object   =    majorScore        : <The major score this user recorded>
                minorScore        : <The minor score this user recorded>
                level            : <The level this score was played at>
                mode            : <The mode this score was played on>

return_object = status             : [true|false]
                rc                 : <Return Code>

callback_data =    status             : [true|false]
                rc                 : <Return Code>


5) community.scoreloop.getleaders( args_object, callback );

Get the leader board for a mode centred on the player.

args_object   =    searchMode         : <Mode to search for>
                searchList         : <0 = All, 1 = Last 24H, 2 = Player's Country>
                range             : <Number of leaders to return>

return_object = status             : [true|false]
                rc                 : <Return Code>

callback_data =    status             : [true|false]
                rc                 : <Return Code>
                leader_c        : <Number of entries in leaders>
                leader            : <An array of the leaders user records>
                    login         : <The user login ID>
                    rank        : <The user ranking>
                    majorScore    : <The major score this user recorded>
                    minorScore    : <The minor score this user recorded>
                    level        : <The level this score was played at>
                    mode        : <The mode this score was played on>


6) community.scoreloop.setchallenge( args_object, callback );

Record a challenge score on Scoreloop

The callback of this function has no payload apart from whether it worked or not and as such is optional. It is useful as a mechanism
to inform the user that their score has been recorded.

args_object   =    majorScore        : <The major score this user recorded>
                minorScore        : <The minor score this user recorded>
                level            : <The level this score was played at>
                mode            : <The mode this score was played on>
                wager            : <The number of coins to bet>
                
return_object = status             : [true|false]
                rc                 : <Return Code>

callback_data =    status             : [true|false]
                rc                 : <Return Code>


7) community.scoreloop.getchallengelist( args_object, callback );

Get the list of challenges the player may play

return_object = status             : [true|false]
                rc                 : <Return Code>

callback_data =    status             : [true|false]
                rc                 : <Return Code>
                challenges_c    : <Number of entries in leaders>
                challenges        : <An array of the leaders user records>
                    login         : <The user login ID>
                    majorScore    : <The major score this user recorded>
                    minorScore    : <The minor score this user recorded>
                    level        : <The level this score was played at>
                    mode        : <The mode this score was played on>
                    stake        : <The stake both players make on winning the challenge>
                    prize        : <The prize the winner collects>
                    created        : <The time/date the challenge was created>


8) community.scoreloop.readlog( );

Returns the internal log from the extension to aid debugging as the log member of the returned object.

As this function is merely for convenience this is all it does at the moment


Changelog
=========

v0.900 - This release

 

 




Click the like button if you find my posts useful!
Contributor
vidueirof
Posts: 25
Registered: ‎04-08-2011
My Device: Torch 9800

Re: Scoreloop for BB10

Hi! I'm really interested on it. Can you send it to me please, and may be I can help you.

New Developer
LeoNoblink
Posts: 25
Registered: ‎09-13-2012
My Device: Playbook, Z10, Z30, Q10, Q5

Re: Scoreloop for BB10

You can now download this api somewhere?

___________________________________

I am in a strange new world...