Mittwoch, 4. Januar 2012

Facebook Tab App tutorial

Heute möchte ich mich mit einem kleinen tutorial der "Facebook Tab App" widmen. Eine App im "tab" einer Facebook Seite verhält sich etwas anders als eine canvas page app. Hier ist besonders der "signed_request" wichtig, da darin auch die Parameterübergabe von Get Parameter der URL stattfindet.  Das wichtigste gleich vorab, möchte man einen Parameter mittels URL an die App übergeben dann geht das mittels app_data als GET Parameter in der url.
 Facebook wird dann den Parameter "app_data" an die Anwendung weitergeben aber innerhalb des signed requests.
Zur Aufgabenstellung:
Die App soll dem Nutzer angezeigt werden mit einem Willkommensscreen. Es soll zwischen Fans und nicht Fans der Facebook Page unterschieden werden, und die Nutzerrechte sollen beim klick auf einen "button" abgefragt werden! Wenn der Nutzer die App Authorisiert wird ein Formular angezeigt mit welchem Daten verschickt werden können.
Hier noch gleich der komplette Source Code dieses Tutorial als laufende App:
https://github.com/KaySchneider/hackTutTabApp
Und die Demo App in Arbeit:
http://www.facebook.com/pages/Hack-the-graph/282796838435859?sk=app_302177259823891

Hier gehts los:
Zu erst müsst ihr eine neue App auf Facebook anlegen:
https://developers.facebook.com/apps
Wénn das gemacht ist als nächstes die Basic Information der App bearbeiten. Dort müsst ihr unter:
"Page tab" euren Server mit und ohne https angeben. Das gleiche macht ihr am besten auch unter "Canvas Page" mit den gleichen Daten. Also:
http://meinServer.de/Unterverzeichniss/

Nun klickt ihr unten auf der Seite auf "save changes" und nun seht ihr in der Überischt eure canvas page url.
Diese benötigt ihr.
Nun müsst ihr noch fix die "config.php" mit eurem facebook stuff befüllen. Also App_id und App_Secret. Jetzt ruft ihr die canvas page url von eurer Seite auf und nun solltet ihr folgendes sehen:
YOU ARE NOT ON AN FACEBOOK PAGE TAB :) Dialog


Dialog ist ein link, klickt ihr auf diesen so erscheint ein dialog von Facebook mit welchem ihr die Application einer Facebook Seite hinzufügen könnt. Was in diesem Fall ja elementar ist. Ihr könnt aber nur eure eigenen Facebook Seiten benutzen. Ihr müsst also Page Admin sein.

Hier die canvas Page der Demo App:
http://apps.facebook.com/hacktutapptab/

So und nun kommen ein paar kurze Erläuterungen zum Source Code:

Den signed_request parsed das  facebook php sdk für uns.
["id"]=>$config = array();

$config['appId'] = APP_ID;//Your AppId

$config['secret'] = APP_SECRET;//Your App Secret

$facebook = new Facebook($config);

$signedRequest = $facebook->getSignedRequest();



Hier der Inhalt der Variablen $signedRequest:


array(4) {
  ["algorithm"]=>
  string(11) "HMAC-SHA256"
  ["issued_at"]=>
  int(1325712721)
  ["page"]=>
  array(3) {
    ["id"]=>
    string(15) "282796838435859"
    ["liked"]=>
    bool(true)
    ["admin"]=>
    bool(true)
  }
  ["user"]=>
  array(3) {
    ["country"]=>
    string(2) "de"
    ["locale"]=>
    string(5) "en_US"
    ["age"]=>
    array(1) {
      ["min"]=>
      int(21)
    }
  }
}



Nun machen wir einen sogenannten "fangate" und sagen dem User er muss diese Page "liken" damit er die App nutzen kann.  Das realisiere ich jetzt im JavaScript teil, da in diesem kleinen Beispiel sich alles auf einer Seite abspielt. Zu diesem zweck lade ich den parsedSignedReqeust vom Server in das Javascript und entscheide nun anhand des Wertes page->liked ( true/false ) ob der Nutzer ein Fan ist oder nicht. Je nachdem werden unterschiedliche Seiten angezeigt.



file js/pageControl.js line: 104-120
pageControl.prototype.showCurrentPageMode = function () {
    if(this.signedRequest.page.liked === false) {
        //noFan
        $('#noFan').show();
    } else if(this.signedRequest.page.liked === true) {

        if( facebookHelper.checkAppAuth() == true) {
            //the user has granted the app permissions
            $('#userHasAppPermitted').show(); 
        } else {
           $('#isFan').show();
        }
        //isFan
        $('#isFan').show();
    }
}
Kurze Erläuterung zum code snippet. Hier wird im signedRequest geprüft ob der Nutzer ein Fan ist oder nicht. Und wenn er ein Fan ist wird mittels der Helfer Funktion "facebookHelper.checkAppAuth()" überprüft ob der Nutzer die App bereits zugelassen hat.  Und für jeden Fall werden hier einzelne Blöcke ein oder ausgeblendet.

Nun haben wir den ersten Schritt schon gemacht, wir haben geprüft ob die Person uns schon rechte gegeben hat, haben die Rechte vom Nutzer abgefragt und den signed_request verarbeitet und die darin enthaltenen Informationen ausgelesen.

Nun werden wir uns noch die Parameterübergabe anschauen, mittels GET Parameter.
Wir möchten einen Externen link auf unsere Page Tab App anlegen und wir möchten sagen das die Hintergrundfarbe diesesmal Blau sein wird. Also gestalten wir den link folgendermaßen:

http://facebook.com/pageName?sk=APP_ID&app_data=color|blue

Nun müssen wir auf der Serverseite diesen Wert parsen.
File:index.php line: 31-35

if (isset($signedRequest['app_data'])) {
    $data = explode("|", $signedRequest['app_data']);
    if ($data[0] == 'color') {
        $color = htmlspecialchars($data[1]);
    }
}
Kurze Erläuterung:
Hier wird im signedRequest auf den Key app_data geprüft und ahnand vom trenner "|" aufgeteilt. Nun können wir die Daten abgreifen. Oder wie in diesem Fall die Hintergrundfarbe ändern.

Nun kommen wir zum letzten Teil, der Parameterweitergabe via ajax. Da verhält es sich eigentlich wie ein ganz normaler Ajax request. Nur mit dem kleinen Unterschied dass wir hier den signed_request als Post Parameter an das Backend übergeben. Hier ein kleiner Code Ausschnit:

 var dataString = { 
            mode:'getSignedRequest',
            signed_request:signedRequest //add the signed request 
        };
   
        $.ajax({
            type: "POST",
            url: "ajax.php",
            data: dataString,
            dataType:'json',
            success: function(data)
            {
                //set on success the parsed data out of the signed request
            //do something with the data  
            }
        });


Das waren im Prinzip auch schon alle besonderheiten einer Tab Page App. Man bekommt über den signed_request die aktuelle Facebook Page Id und den "user like status" dieser App mit. Alles andere ist annähernd gleich wie bei einer Canvas App. Ich hoffe dieses Tutorial hat dem ein oder anderen geholfen. Lob und auch Kritik ist herzlich Willkommen.

2 Kommentare: