Score keeper

From Chumby Wiki
Revision as of 23:37, 22 February 2008 by Bucini (Talk | contribs)

Jump to: navigation, search

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.

Monitoring for abuse

This service is monitored for abuse. We've taken steps to prevent blatant abuse. We also 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.

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 A rate limiter has been added to prevent blatant abuse. If any score is posted for the same widget instance within 5 seconds, the second posting will be rejected.

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>