Latest revision as of 17:24, 25 February 2008

Summary

The score keeper is an interface to allow game widgets to post high scores to the server, then fetch those high scores back to show the "community high scores" and promote friendly competition.

Usage

Posting new scores

Posting scores will add new entry to the list of scores for the given game. If a score is posted for a game that isn't in the game table, a new entry is created for the game, and the new score is posted. (This is a potential area for abuse. If it becomes a problem, then an admin interface will be created to maintain the list of games)

To post a new score, make a post to

http://content.chumby.com/score/create?id=<widget_instance_id>&score=<score>&custom=<custom_string>

widget_instance_id 

The widget instance id of the game (GUID - Required)

score 

The score to post (Integer - Required)

custom 

A free form field (String shorter than 120 characters - Optional - Default nil)

The response will either be:

<response>success</response>

indicating successful posting or

<response msg="Some message">failure</response>

indicating failure, with a message describing what failed.

NOTE If a score is posted more than once for the same widget instance within 5 seconds, only the first posting will be accepted.

Retrieving Posted scores

This request is used to get the list of scores for a given game. It can be limited based on a time window (all scores posted within the last X days), as well as count limited (the top 10, 50, 100 scores). It can also be limited to just the scores posted by the current user. The widget_instance_id is used to determine which game is being requested, and who the current user is.

To retrieve a list of scores for a given game, make a request to

http://content.chumby.com/score/list?id=<widget_instance_id>&time=<days>&all_time=1&user=1&unique=1

widget_instance_id 

The widget instance id of the game (GUID - Required)

time 

The number of days to limit the list to (Integer - Optional - Default 14)

all_time 

If present, indicate the list should have all scores posted (Anything - Optional)

user 

If present, indicate that the list should only include scores from the current user (Anything - Optional)

limit 

The number of scores to limit the query to (Integer - Optional - Default 100)

unique 

If present, indicate the list will only contain the highest score for each user in the specified timeframe (Anything - Optional)

Response will be

<scores game="Widget Name">
  <score submitted_at="timestamp" username="username">score</score>
  <score submitted_at="timestamp" username="username">score</score>
  ...
</scores>

submitted_at 

A timestamp of the form 'Wed Oct 31 10:00:54 -0700 2007'

username 

The username of the user who posted the score

score 

The score posted

or

<response msg="Some message">failure</response>

Please don't abuse

We log the user_id and widget_instance_id of each score that is posted. If a user is found to be abusing the system, their score records will be deleted, and add logic will be activated to prevent them from posting any more scores. While we've taken some steps to prevent blatant abuse, it's still easy to fill score tables with bogus scores. Please don't do that, so we can spend our time doing more development instead of cleaning the score databases.