von: 
am: 06.06.2012
in: Entwicklung

Facebook User Scores API Grundlagen

© Angelo Gilardelli | Dreamstime.com

Die meisten Spiele speichern Highscores in einer eigenen Datenbank und kümmern sich selbst um die Speicherung und Verwaltung. Bei umfangreicheren Spielen mit einem hohen Programmieraufwand macht das sicher Sinn, die Programmierung einer eigenen Punktelogik fällt da nicht wirklich ins Gewicht und man bleibt offener für Portierungen auf andere Plattformen. Für kleinere Spiele auf Facebook kann ich aber eine meiner Meinung nach zu unrecht sehr vernachlässigte Funktion des Facebook API empfehlen: die sogenannten “User Scores“.

Vorweg ein paar wichtige Infos und Einschränkungen:

  • Die Punkte bleiben auch erhalten wenn der User die App aus den Anwendungseinstellungen entfernt und sie später wieder autorisiert.
  • Im “Leaderboard” (siehe unten) scheinen immer nur User auf welche die App zum aktuellen Zeitpunkt autorisiert haben.
  • Es gibt keine Möglichkeit Punkte zu addieren, zu diesem Zweck muss der aktuelle Stand ausgelesen, erhöht und neu eingestellt werden.
  • Es ist nur ein Punktestand von 0 bis 1000 möglich.

App Settings

Bereits in den App Settings muss man sich überlegen ob man Scores verwenden will. Diese stehen nämlich nur zur Verfügung wenn man als Hauptkategorie für die App “Spiele” auswählt:

App Settings

Permissions

Für das Auslesen der Scores braucht man keine zusätzlichen Permissions, sehr wohl allerdings für das Löschen und Einfügen/Ändern. Es macht also Sinn die Permission “publish_actions” in jedem Fall vom User zu verlangen. Braucht man vom eingeloggten User die Punkte aus ALLEN Game-Apps dann ist zusätzlich die Permission “user_games_activity” (bzw. “friends_games_activity“) notwendig, das ist aber sicher sehr selten bis nie der Fall.

“publish_actions” braucht man weil Facebook automatisch den Punktestand im Stream postet. Keine Sorge, es wird nicht jede Änderung gepostet, Facebook geht hier sehr intelligent vor um der Spamgefahr vorzubeugen.

Der Autorisierungsdialog zeigt dass man die Scores nicht unbedingt für simple Promotions auf Facebook Pages verwenden sollte, beim Button “Spiel spielen” erwartet sich ein User eventuell dass die App wirklich ein Spiel beinhaltet:

Autorisierungsdialog

Für Gewinnspiele könnte das aber dennoch interessant sein. Zum Beispiel: “Wer zuerst 100 Punkte bei einem kleinen Minigame erreicht nimmt an der Verlosung teil”. Ich bin kein Anwalt und meine Angaben sind natürlich ohne Gewähr, aber das müsste absolut richtlinienkonform sein, obwohl automatisch und absolut ohne User-Bestätigung etwas in den Stream gepostet wird (wie erwähnt, sehr intelligent und nicht jede einzelne Änderung). So sieht das dann zum Beispiel aus:

Wallpost Test 1

Wallpost Test 1

Auch in der Timeline verewigen sich die User Scores, und auch hier mit dem gebührenden “Pluralis Majestatis“:

User Scores in der Timeline

Programmierung

Meine Erklärung basiert auf dem Javascript SDK, natürlich kann man zur Programmierung der Scores jedes verfügbare SDK nutzen. Die Graph URLs und Parameter sind sowieso immer gleich. Ich bevorzuge allerdings das Javascript SDK weil es sehr dynamisch ist und keinen Page Refresh benötigt.

Für manche Aufrufe braucht man einen “App Access Token”, den holen wir uns per PHP:

$token_url =    "https://graph.facebook.com/oauth/access_token?" .
                "client_id=" . FBAPPID .
                "&client_secret=" . FBSECRET .
                "&grant_type=client_credentials";
$app_token = file_get_contents($token_url);
$app_token = str_replace('access_token=','',$app_token);

Für alle anderen Aufrufe braucht man nur den “User Access Token”, der aber automatisch per Javascript SDK übertragen wird. Natürlich kann anstellt der Facebook ID auch immer “/me/scores” für den aktuell eingeloggten/autorisierten User verwendet werden.

User Score setzen

Das Eintragen des User Scores ist nur über den App Access Token möglich, ansonsten keine Hexerei:

FB.api('/[FB-ID]/scores', 'POST', {
   'score':50,
   'access_token':'<?php echo $app_token; ?>'
   }, onResponse);

function onResponse(response)
{
   console.log(response);
}

Der Graph URL beinhaltet die Facebook ID des jeweiligen Users welche natürlich ohne die eckigen Klammern anzugeben ist. Als Parameter übergibt man die neue Punktezahl als Integer-Wert und den vorhin erstellen App Token. Die Callback-Funktion “onResponse” liefert in der Variable “response” den Wert “true” als Boolean wenn der Aufruf erfolgreich war, ansonsten eine Fehlerbeschreibung.

User Score auslesen

Für das Auslesen ist kein App Access Token notwendig, ebenso auch keine zusätzlichen Parameter. In der Callback-Funktion erhält man den aktuellen Score-Wert des Users, die length-Abfrage ist notwendig für den Fall dass noch keine Punkte gesetzt wurden:

FB.api('/[FB-ID]/scores', onResponse);

function onResponseUserScore(response)
{
   if (response.data.length)
   {
      console.log(response.data[0].score);
   }
}

User Score löschen

Man kann entweder nur den Score eines einzelnen Users löschen oder alle Score-Werte der App. Letzteres ist sinnvoll wenn man zum Beispiel jede Woche die Highscore eines Spiels zurücksetzen will. In jedem Fall braucht man wieder den App Access Token:

FB.api('/[FB-ID]/scores', 'DELETE', {
   'access_token':'<?php echo $app_token; ?>'
   }, onResponse);

function onResponse(response)
{
   console.log(response);
}

Für das zurücksetzen der gesamten Scores muss nur die Facebook-ID im Graph URL durch die App-ID ersetzt werden. Rückgabewert ist wie beim Eintragen entweder “true” (Boolean) oder eine Fehlermeldung.

Leaderboard

Die interessanteste Möglichkeit der User Scores ist das sogenannte “Leaderboard”, also eine Highscore-Liste. Ein einfacher Aufruf an das Graph API liefert eine Liste aller Freunde des eingeloggten Users welche die App ebenfalls benutzen, sortiert nach ihrem Score-Wert:

FB.api('/[APP-ID]/scores', onResponse);

function onResponse(response)
{
   var length = response.data.length;
   for (var i = 0; i < length; i++)
   {
      console.log('User: '+response.data[i].user.name);
      console.log('Punkte: '+response.data[i].score);
   }
}

Das API liefert ein vollständiges Array zurück, Jedes Array-Element beinhaltet ein User-Objekt (Name und ID des Users), die Punktezahl und ein Application-Objekt (Name und ID der App).

Fazit

User Scores werden wie erwähnt offensichtlich sehr selten eingesetzt, sind aber eine nette und einfache Spielerei. Eine App die sehr viele API Aufrufe braucht könnte die Scores einfach zusätzlich in einer eigenen Datenbank zwischenspeichern, sodass der API Aufruf auf das Posten neuer Scores oder das Zurücksetzen/Löschen beschränkt werden kann. Jeder Aufruf an das Facebok API kostet immerhin Zeit und es gibt ja dann auch noch die API Limits. Nähere Infos gibt es auf der Developer Seite von Facebook: https://developers.facebook.com/docs/score/

Trackbacks/Pingbacks

  1. Facebook Achievements API Grundlagen | LimeSoda BlogLimeSoda Blog - 13.06.2012

    […] | Dreamstime.com Tweet Für die Programmierung von Spiele-Apps hat Facebook nicht nur das Scores API erschaffen, sondern auch ein nettes […]

Hinterlasse einen Fingerabdruck für die Ewigkeit:
Ein Kommentar bei LimeSoda!