von: 
am: 13.06.2012
in: Entwicklung

Facebook Achievements API Grundlagen

© Krakus324 | Dreamstime.com

Für die Programmierung von Spiele-Apps hat Facebook nicht nur das Scores API erschaffen, sondern auch ein nettes Achievements-System.

Die wesentlich Infos:

  • Jedes Achievements benötigt eine eigene/spezielle Seite mit Open Graph Tags.
  • Jedes Achievements hat eine bestimmte Punktezahl (Score) zugeteilt, insgesamt darf die Anzahl der Punkte von allen Achievements nicht 1000 übersteigen.
  • Erreicht ein User ein Achievement, so werden ihm allerdings nicht die Punkte auf sein “Scores” Konto gut geschrieben.
  • Jede App kann maximal 1000 Achievements besitzen.
  • Ein User kann ein Achievement nur einmal erhalten.
  • Achievements dürfen nicht gelöscht werden, ausser zu Testzwecken.
  • Wie beim Scores API wird auch hier die Permission “publish_actions” benötigt.
  • Ein Achievement kann pro User nur ein einziges Mal zugeteilt werden.

Facebook postet das Erreichen von Achievements je nach Punktezahl. Je mehr Punkte einem Achievements zugeteilt sind, desto eher wird es automatisch gepostet. Wie bei den Scores hat Facebook hier die Kontrolle:

Achievements which are scarcer and have higher point values will receive more distribution. For example, achievements which have point values of less than 10 will get almost no distribution. Apps should aim for between 50-100 achievements consisting of a mix of 50 (difficult), 25 (medium), and 10 (easy) point value achievements. (Quelle: Facebook Achievements)

Achievement Seite

Kernstück der Achievements ist eine eigene Seite die mit bestimmten Open Graph Tags befüllt werden muss. Eine vollständige Auflistung der benötigten Tags findet sich in der Facebook Doku zu den Achievements. Die Daten sollten gut überlegt sein, ab einer bestimmten Anzahl von verteilten Achievements können sie nicht mehr gändert werden.

Das Achievement-Image gibt Facebook in der Doku mit einer Mindestgrösse von 50×50 Pixel an, der Debugger allerdings hätte gerne mindestens 200×200 Pixel. Da ein grösseres Bild nicht schadet sollte man sich also nach dem Debugger richten. Generell ist es natürlich immer sinnvoll jede Seite nach der Verwendung von Open Graph Tags im Facebook Debugger zu überprüfen.

Die Seite sollte nicht nur OG-Daten beinhalten, klickt ein User auf die Achievement-Meldung im Stream dann kommt er nämlich genau auf diese Seite und sollte nicht gähnende Leere vorfinden.

Achievement registrieren

Der nächste Schritt ist die Registrierung des Achievements bei Facebook. Wie beim Scores API brauchen wir auch hier wieder einen App Access Token, da dies pro Achievement nur ein einziges Mal passiert verwenden wir das PHP SDK:

$response = $facebook->api('/[APP-ID]/achievements', 'POST', array(
    'access_token' => $app_token,
    'achievement' => 'https://myfbserver.com/achievement1.html'
));

Der Aufruf liefert “true” als Boolean wenn er erfolgreich war. Ändert sich etwas an den Open Graph Tags, dann muss dieser Aufruf nicht erneut statt finden. Facebook aktualisiert die Daten automatisch, den Vorgang kann man beschleunigen indem man den Achievement-Link im Debugger aufruft.

Achievements abfragen

Die Auflistung der registrierten Achievements ist ebenso einfach:

$response= $facebook->api('/[APP-ID]/achievements', 'GET', array(
    'access_token' => $app_token
));
var_dump($achievements);

Bzw. die Variante per JavaScript SDK:

FB.api('/[APP-ID]/achievements', 'GET', function(response) {
    console.log(response);
});

Der Aufruf liefert ein umfangreiches Array mit den vollständigen Infos jedes Achievements, inklusive dem letzten Update-Zeitpunkt. Eine genaue Auflistung findet sich wieder auf der Developer Seite von Facebook: Facebook Achievements. In der Doku steht ausserdem dass man für das Auslesen einen App Access Token braucht, es funktioniert aber auch ohne.

Achievements löschen

Hier braucht man in jedem Fall den App Access Token, ansonsten ist der selbe Code wie beim Registrieren notwendig. Man tauscht lediglich “POST” gegen “DELETE”.

PHP SDK:

$response = $facebook->api('/[APP-ID]/achievements', 'DELETE', array(
    'access_token' => $app_token,
    'achievement' => 'https://myfbserver.com/achievement1.html'
));

JavaScript SDK:

FB.api('/[APP-ID]/achievements', 'DELETE', {
    achievement:'https://myfbserver.com/achievement1.html',
    access_token:'[APP-ACCESS-TOKEN]'}, function(response) {
        console.log(response);
});

Rückgabewert ist wieder “true” als Boolean wenn der Aufruf erfolgreich war, ansonsten erhält man eine Fehlermeldung.

User-Achievements verteilen

Jetzt kommt der spannende Teil den man vermutlich am Häufigsten benötigt. Hier muss folgendes beachtet werden:

  • Beim PHP SDK ist ein try-catch Block zwingend notwendig.
  • Die Zuteilung per “me” funktioniert nicht, man braucht immer eine User-ID.
  • Es muss der App Access Token verwendet werden.

PHP SDK:

try
{
    $response = $facebook->api('/[FB-ID]/achievements', 'POST', array(
        'access_token' => $app_token,
        'achievement' => 'https://myfbserver.com/achievement1.html',
    ));
    var_dump($response);
}
catch(FacebookAPIException $e)
{
    var_dump($e);
}

JavaScript SDK:

FB.api('/[FB-ID]/achievements', 'POST', {
    achievement:'https://myfbserver.com/achievement1.html',
    access_token:'[APP-ACCESS-TOKEN]'}, function(response) {
        console.log(response);
})

Rückgabewert ist die ID des zugeteilten Achievements oder eine Fehlermeldung.

User-Achievements abfragen

Analog zur Abfrage der gesamten Achievements einer App tauscht man einfach App ID gegen User ID, bzw. “me”. Den App Access Token benötigt man nur wenn die Achievements eines anderen Users gelesen werden sollen, zum Beispiel für einen Vergleich zwischen eingeloggtem User und einem Freund dieses Users. Der Aufruf liefert eine Liste aller erreichten Achievements des Users.

PHP SDK:

$response = $facebook->api('/me/achievements', 'GET');
var_dump($achievements);

JavaScript SDK:

FB.api('/me/achievements', 'GET', function(response) {
    console.log(response);
})

User-Achievements löschen

Diese Aktion wird wohl selten benötigt, der Vollständigkeit halber (und weil man sie für Tests dann doch braucht) aber auch hier der notwendige Code:

PHP SDK:

$response = $facebook->api('/me/achievements', 'DELETE', array(
    'achievement' => 'https://myfbserver.com/achievement1.html'
));
var_dump($response);

JavaScript SDK:

FB.api('/me/achievements', 'DELETE', {
    achievement:'https://myfbserver.com/achievement1.html'},
    function(response) {
        console.log(response);
});

Rückgabewert ist “true” als Boolean bei erfolgreicher Löschung oder eine Fehlermeldung. Für einen User der nicht aktuell eingeloggt ist natürlich wieder der App Access Token notwendig.

Fazit

Achievements sind für Spiele eine tolle Sache, im Sinne der “Gamification” die schon seit Jahren ein wichtiger Bestandteil von Promotions ist kann man sie durchaus auch zum Beispiel für Gewinnspiele als Belohnungssystem einsetzen. Relativ unklar ist jedoch die Punkteverteilung zu Achievements, jedes Achievement muss eine Punktezahl beinhalten, diese wirkt sich jedoch in keiner Weise auf die Scores des Users aus sondern regelt im Prinzip nur wie prominent Facebook das Achievement beim Erreichen behandelt/postet. Natürlich ist der Programmieraufwand nicht zu unterschätzen, immerhin braucht jedes Achievement eine eigene Seite die eventuell auch designed werden möchte.

Was? Noch kein Kommentar? Sei der Erste!

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