Facebook, uno dei più popolari servizi di social networking, nasce nel 2004 per mano di Mark Zuckerberg, e raggiunge il successo molto velocemente, in un primo momento tra i soli studenti della Harvard University, quindi in tutti gli Stati Uniti, per raggiungere infine più di 150 milioni di utenti attivi in tutto il mondo. All'interno del servizio, un utente può creare la propria rete di amici, con i quali comunicare e condividere foto, filmati, link e altri contenuti, oppure può utilizzare una delle tante applicazioni a disposizione.
Nel maggio del 2007 è stata lanciata Facebook Platform, un framework che mette gli sviluppatori in grado di creare applicazioni che interagiscono con il nucleo di Facebook. Contemporaneamente, lo stesso Facebook ha proposto le prime applicazioni, ad esempio Events, per condividere informazioni sugli eventi a cui gli utenti sono invitati a partecipare, oppure Video, per la condivisione di filmati. Ad oggi, le applicazioni segnalate sono migliaia e le loro funzionalità sono le più disparate, dai giochi alle utility.
Lo scopo di questo articolo e degli altri che seguiranno è capire la struttura di un'applicazione Facebook, conoscere gli strumenti messi a disposizione dalla sua piattaforma, per affrontare infine lo sviluppo di applicazioni da condividere con gli altri utenti. Gli esempi proposti sfrutteranno la libreria PHP 5 fornita dallo stesso Facebook, anche se è possibile costruire le proprie applicazioni anche con altri linguaggi (leggi anche Applicazione per Facebook in PHP).
Cosa ci serve per iniziare
Per lo sviluppo di un'applicazione Facebook, questi sono gli ingredienti assolutamente necessari:
- un account su Facebook: potrebbe sembrare una banalità, ma la creazione di applicazioni richiede che lo sviluppatore sia registrato al servizio;
- un proprio spazio web che supporti un linguaggio lato server, ed eventualmente un database: Facebook non fornisce hosting per le applicazioni di terzi, ma si limita ad integrarle nel proprio servizio (vedi il prossimo paragrafo);
- la conoscenza dell'API messa a disposizione da Facebook: quest'ultimo punto non è strettamente necessario se si sfrutta una libreria ad hoc, come ad esempio PHP Facebook Client Library, che faccia il lavoro sporco per noi.
Struttura e funzionamento di un'applicazione
Prima di analizzare nel dettaglio l'anatomia di un'applicazione, introduciamo in questo paragrafo alcuni particolari che ci servono per comprendere come Facebook vada ad integrare le nostre applicazioni all'interno del suo servizio.
Ogni applicazione viene identificata dagli utenti con un indirizzo chiamato Canvas Page URL. Tale indirizzo è sempre nella forma apps.facebook.com/mia- applicazione dove "mia-applicazione" è una stringa dai 7 ai 20 caratteri (alfanumerici, underscore o il segno meno). Questo indirizzo fa da tramite tra Facebook e la nostra applicazione: quando un utente richiama la Canvas Page di un'applicazione, la richiesta viene girata alla Callback URL, che sarà l'indirizzo, sul nostro spazio web, dove l'applicazione effettivamente risiede, ad esempio www.html.it/mia-applicazione. Teniamo presente che l'applicazione può essere formata da più pagine, per cui se ad esempio l'utente richiama la pagina apps.facebook.com/mia- applicazione/pippo.php, la richiesta verrà girata alla corrispondente pagina www.html.it/mia-applicazione/ pippo.php. La "homepage" dell'applicazione è la classica pagina index.
In Figura 1 viene sintetizzato quanto appena descritto.
Il dialogo tra Facebook e la nostra applicazione avviene mediante un approccio REST-based, secondo quanto descritto dall'API del servizio. In sostanza, Facebook mette in moto la nostra applicazione, la quale invia delle richieste HTTP allo stesso Facebook aspettando le relative risposte, per fornire infine l'output che Facebook servirà all'utente. La conoscenza dell'API non è necessaria se si decide di appoggiarsi ad una libreria che ne implementa le funzionalità. Nel nostro caso sfrutteremo la PHP Facebook Client Library, libreria in PHP 5 fornita dallo stesso Facebook.
La nostra prima applicazione
I dettagli di cui parlare sono molti, per cui preferiamo condurre il lettore attraverso un approccio di learning-by-doing, ossia passando direttamente all'implementazione di una prima semplice applicazione Facebook, per poi descriverne i particolari.
Dopo aver scaricato la PHP Facebook Client Library, diamo un'occhiata all'interno del pacchetto: la cartella footprint contiene un'applicazione di esempio, mentre la cartella php contiene i sorgenti della libreria. Sarà nostra cura caricare questi sorgenti sul nostro spazio web.
Una volta effettuato il login a Facebook, il primo passo consiste nell'aggiungere l'applicazione Developers, che sarà il nostro pannello di controllo per tutte le applicazioni che creeremo. Per aggiungere Developers, è sufficiente visitare l'indirizzo www.facebook.com/developerse confermare l'aggiunta dell'applicazione.
Dalla schermata principale di Developers, il link da seguire è Set Up New Application, che ci porta alla pagina di inserimento delle informazioni basilari. L'unica informazione obbligatoria è il nome dell'applicazione, ma è bene dare un'occhiata a tutti i campi. Le parti fondamentali sono:
- Application Name: il nome dell'applicazione, nel nostro caso HTML.it Hello World
- Callback URL: l'indirizzo dove risiede la nostra applicazione, come descritto nel paragrafo precedente
- Canvas Page URL: l'indirizzo che identifica l'applicazione su Facebook, nel nostro caso http://apps.facebook.com/ htmlit-tutorial/, a cui associamo l'uso di FBML, Facebook Markup Language, il linguaggio di markup che ci consente di utilizzare alcuni particolari tag all'interno della nostra applicazione
- Can your application be added on Facebook? Yes: necessaria affinché l'applicazione possa essere aggiunta ad un account Facebook, in modo tale da essere integrata nel profilo ed essere sempre accessibile per gli utenti che la aggiungeranno. Questa funzione rende disponibili numerose altre opzioni relative all'integrazione dell'applicazione.
Completata questa procedura, l'applicazione è stata creata. Tutte le informazioni inserite nel passo precedente sono comunque modificabili in un secondo momento (tramite la voce Edit settings). Facebook ci mette ora a disposizione due codici, API Key e Secret, che dovremo integrare nella nostra applicazione. Entrambi i codici sono stringhe di 32 caratteri esadecimali.
Il codice PHP dell'applicazione
Il file index.php mostrato di seguito comprende tutto il codice del nostro primo Hello World.
<?php
/**
* HTML.it tutorial: Hello World
* index.php
*/
// Includo il codice della PHP Facebook Client Library
require_once 'facebook.php';
// API Key e Secret
$app_apikey = 'mio-codice-api-key';
$app_secret = 'mio-codice-secret';
// Creo un oggetto Facebook
$facebook = new Facebook($app_apikey, $app_secret);
// Autenticazione
$user_id = $facebook->require_login();
// Messaggio di benvenuto, usando FBML
echo "
<p>
Ciao, <fb:name uid="{$user_id}" useyou="false" />!
</p>
";
// Lista amici dell'utente loggato
$friend_list = $facebook->api_client-> friends_get();
// Richiamo tre elementi casuali dalla lista amici
shuffle($friend_list);
$friend_list = array_slice($friend_list, 0, 3);
// Stampo i nomi dei tre amici
echo ' <p>Alcuni tuoi amici su Facebook:</p> <ul> ';
foreach ($friend_list as $friend) {
echo "<li><fb:name uid="{$friend}" useyou="false" /></li>";
}
echo '</ul>';
// Dump dell'oggetto $facebook
// echo '<pre>'; var_dump($facebook); echo '</pre>';
?>
Codice e commenti sono abbastanza autoesplicativi, ma vediamo ora di spendere qualche parola in più per fugare eventuali dubbi. Lo faremo nella pagina successiva.
Tutti i sorgenti della PHP Facebook Client Library sono stati copiati nella stessa cartella in cui risiede index.php, dal quale includiamo facebook.php che è il file principale della libreria. $app_apikey e $app_secret sono le due variabili dedicate a contenere i codici forniti da Facebook quando abbiamo creato la nuova applicazione. Questi sono necessari per creare l'oggetto $facebook che sarà il punto centrale del nostro codice.
Dopo la creazione dell'oggetto Facebook, è fondamentale verificare l'autenticazione dell'utente, sfruttando il metodo require_login() che restituisce l'ID numerico dell'utente stesso all'interno del servizio.
Il messaggio di benvenuto sfrutta l'utilizzo di codice FBML, un insieme di tag che possono essere immersi nel normale HTML e che vengono poi trasformati da Facebook. Nel nostro caso, il tag fb:name mostra il nome dell'utente sotto forma di link al suo profilo. L'attributo uid serve per specificare il suo ID numerico, mentre l'attributo useyou, se impostato a true, mostra la dicitura you invece del nome.
Il passo successivo è recuperare la lista degli amici: l'oggetto $facebook contiene una proprietà $api_client, a sua volta un oggetto, la quale funge appunto da client per l'API di Facebook. Il suo metodo friends_get() restituisce un array con tutti gli ID numerici degli amici. Decidiamo quindi di stampare tre nomi casuali (mescolando l'array con shuffle() ) sfruttando ancora le funzionalità di FBML.
Per un'occhiata più dettagliata all'interno dell'oggetto $facebook, basta togliere il commento sulla riga relativa al dump della variabile.
In Figura 2 vediamo l'output del nostro Hello World.
Considerazioni finali e link
Facebook suggerisce delle linee guida per lo sviluppo di applicazioni di qualità. Secondo queste linee guida, un'applicazione dovrebbe essere:
- significativa, ossia essere utile, espressiva, e sociale (coinvolge il grafo degli amici, consente all'utente di esprimere qualcosa di se stesso, invoglia l'utente ad utilizzarla ancora)
- fidata, ossia deve rispettare la privacy, deve rispettare i bisogni degli utenti e deve essere assolutamente trasparente, mostrando quello che fa e come lo fa
- ben disegnata, ossia intuitiva, semplice, senza errori, ma anche scalabile e robusta, garantendo un buon uptime (questo può dipendere anche dalla qualità dal vostro hosting)
Il primo punto dipende ovviamente dalla creatività dello sviluppatore. Le potenzialità offerte da Facebook sono numerose, e noi andremo ad approfondirle nel prossimo articolo, analizzando più nel dettaglio l'API di Facebook ed il linguaggio FBML.
Link utili:
- Documentazione per gli sviluppatori
- Wiki per gli sviluppatori, contiene anche link a librerie client in vari linguaggi
- Sorgenti di PHP Facebook Client Library
- Approfondimento sul Social Networking
- Il termine Facebook su Wikipedia, anche nella versione italiana
- Approfondimento sull'architettura REST
Nella parte precedente di questo articolo abbiamo mosso i primi passi nella creazione di applicazioni per Facebook, analizzandone a grandi linee la struttura ed introducendo da un lato l'utilizzo dell'API messa a disposizione da Facebook, a cui ci siamo interfacciati sfruttando la libreria PHP Facebook Client Library, e dall'altro la possibilità di appoggiarsi al linguaggio FBML per fornire l'output finale.
Lo scopo dei prossimi paragrafi è approfondire la conoscenza sia della Facebook API, che del linguaggio FBML, con l'obbiettivo di scoprirne le potenzialità che ci porteranno alla creazione di applicazioni che vanno oltre il nostro primo Hello World.
Facebook API
L'interfaccia che Facebook mette a disposizione per consentire alle nostre applicazioni di dialogare con il cuore del sistema si basa su un'architettura di tipo REST, Representational State Transfer, ossia un'architettura software le cui idee rappresentano un approccio abbastanza comune nella costruzione di un Web Service. Questa tecnica prevede un semplice scambio di informazioni tra server e client tramite protocollo HTTP, senza l'utilizzo di tecniche più evolute per lo scambio di messaggi (come ad esempio SOAP) o per tenere traccia della sessione (come ad esempio l'uso di cookie).
Più nel dettaglio, da parte di Facebook viene messo a disposizione un API REST Server, che rimane in ascolto attendendo richieste HTTP di tipo POST e rispondendo con stringhe in formato XML che possono quindi essere interpretate dal client. Da questo punto di vista, le nostre applicazioni svolgono quindi il ruolo di client.
Tutti i metodi a disposizione sono descritti nel Wiki dedicato agli sviluppatori.
PHP Facebook Client Library
Tramite le funzioni della PHP Facebook Client Library, che abbiamo già utilizzato nel precedente articolo, abbiamo accesso alle funzionalità del Web Service senza dover richiamare manualmente i singoli metodi dell'API. In particolare, una volta creato un oggetto di tipo Facebook, al suo interno troveremo una proprietà chiamata api_client, a sua volta di tipo oggetto, che implementa l'accesso ai metodi dell'API.
Vediamo ora una rapida carrellata di alcuni metodi utili di questo oggetto api_client. Ricordiamo che la sintassi per accedere a tali metodi è sempre:
require_once 'facebook.php';
$appapikey = 'tua-api-key';
$appsecret = 'tua-secret';
$facebook = new Facebook($appapikey, $appsecret);
$user_id = $facebook->require_login();
$return_value = $facebook->api_client->metodo( $parametri);
Metodi relativi all'utente
users_getInfo($utenti, $info) implementa users.getInfo
$utenti è un array di ID utente, $info è un array di stringhe, ognuna delle quali rappresenta un'informazione da recuperare. Tutte le informazioni recuperabili sono descritte nel Wiki.
Il metodo restituisce un array di array: ogni elemento contiene le informazioni richieste per ciascun utente.
Esempio:
$get_info = array(
'first_name',
'last_name',
'status',
'pic');
$info = $facebook->api_client->users_ getInfo(array($user_id), $get_info);
echo '<p>Risultato di users_getInfo()</p>';
echo '<pre>'; print_r($info); echo '</pre>';
users_isAppUser($uid) implementa users.isAppUser
Restituisce un valore booleano, true se l'utente $uid ha autorizzato l'applicazione, false altrimenti.
users_setStatus($status, $uid) implementa users.setStatus
Imposta lo stato nel profilo dell'utente $uid, utilizzando $status come stringa. Se $uid viene omesso, si utilizza l'utente della sessione corrente.
Metodi relativi alla lista amici
friends_areFriends($uid1, $uid2) implementa friends.areFriends
Verifica se le coppie di utenti indicate sono amici o meno. $uid1 e $uid2 sono due array, della stessa lunghezza, contenenti ID utente. Restituisce un array di array, contenente un elemento per ogni coppia di utenti, indicando con valori booleani se gli utenti sono amici o meno.
Esempio:
$amico = 12345; $non_amico = 54321; // due ID utente
$uid1 = array($user_id, $user_id); // $user_id è il mio ID utente
$uid2 = array($amico, $non_amico);
$result = $facebook->api_client-> friends_areFriends($uid1, $uid2);
echo '<p>Risultato di friends_areFriends()</p>';
echo '<pre>'; print_r($result); echo '</pre>';
Risultato:
<pre>Array
(
[0] => Array
(
[uid1] => mio-id
[uid2] => id-amico
[are_friends] => 1
)
[1] => Array
(
[uid1] => mio-id
[uid2] => id-non-amico
[are_friends] => 0
)
)
friends_get() implementa friends.get
Restituisce un array contenente la lista degli ID utente dei propri amici.
friends_getAppUsers() implementa friends.getAppUsers
Restituisce un array contenente la lista degli ID utente dei propri amici che sono anche utenti dell'applicazione.
Metodi relativi ai gruppi
groups_get($uid, $gids) implementa groups.get
Restituisce un array con gli ID dei gruppi in base ai parametri specificati: $uid è l'ID dell'utente, $gids è un array di ID. Entrambi i parametri sono facoltativi.
groups_getMembers($gid) implementa groups.getMembers
Restituisce un array associativo, in cui vengono indicati gli utenti che appartengono al gruppo $gid. Il risultato distingue tra members, admins, officers e not_replied.
Metodi relativi agli eventi
events_get($uid, $eids, $start_time, $end_time, $rsvp_status) implementa events.get
Restituisce un array di ID di eventi, in base ai filtri indicati. $uid è l'ID dell'utente per il quale si vuole effettuare la ricerca, $eids è un array di ID di eventi, $start_time e $end_time sono i limiti temporali (inizio e fine) entro cui si vuole cercare, nel formato Unix Timestamp, $rsvp_status è lo stato RSVP (attending, unsure o declined) associato all'utente $uid.
events_getMembers($eid) implementa events.getMembers
Restituisce un array di ID degli utenti associati all'evento $eid, suddivisi in base allo status (attending, unsure, declined o not_replied).
events_rsvp($eid, $rsvp_status) implementa events.rsvp
Imposta lo stato RSVP dell'utente per l'evento $eid. Il parametro $rsvp_status è una stringa che può assumere i seguenti valori: attending, unsure o declined.
events_create($event_info) implementa events.create
Crea un evento, il cui amministratore è l'utente. $event_info è un array contenente le informazioni relative all'evento (descritte nel Wiki).
events_cancel($eid, $cancel_message) implementa events.cancel
Elimina l'evento $eid, se l'utente ne è amministratore. $cancel_message è un parametro opzionale che contiene un messaggio da inviare agli utenti dell'evento.
events_edit($eid, $event_info) implementa events.edit
Modifica l'evento $eid associando le informazioni contenute nell'array $event_info (come per events_create(), vedi Wiki).
Metodi relativi alle foto
photos_get($subj_id, $aid, $pids) implementa photos.get
Restituisce un array contenente gli ID delle foto in base ai filtri specificati: $subj_id è l'ID dell'utente a cui è stato associato un tag, $aid è l'ID di un album in cui cercare, $pids è un array che contiene la lista di foto in cui restringere la ricerca. I tre parametri sono opzionali, ma almeno uno dei tre deve essere specificato.
photos_getAlbums($uid, $aids) implementa photos.getAlbums
Restituisce un array contenente gli ID degli album creati dall'utente $uid, eventualmente restringendo la ricerca tra gli ID indicati nell'array $aids.
photos_getTags($pids) implementa photos.getTags
Restituisce un array di tag cercati all'interno delle foto i cui ID sono elencati nell'array $pids.
Facebook Markup Language
FBML costituisce un insieme di tag che ci consentono di estendere il normale HTML all'interno delle nostre applicazioni. Questi tag vengono convertiti dal motore di Facebook producendo un output HTML coerente con la grafica utilizzata in tutto il sito. Alcuni tag forniscono anche dei controlli condizionali per una maggiore flessibilità.
Analizziamo ora una carrellata di tag utili, ricordando che l'elenco completo dei tag disponibili è descritto nel Wiki.
<fb:name uid="$uid" />
Si trasforma nel nome dell'utente $uid, con un link al suo profilo. Se il parametro firstnameonly è indicato come true, viene mostrato solo il nome di battesimo. Analogamente, lastnameonly consente di mostrare solo il cognome. Il parametro linked impostato a false consente di evitare il link al profilo, indicando solo il nome.
<fb:user uid="$uid"> Informazioni ... </fb:user>
Mostra le informazioni contenute nel tag solo agli utenti che non sono stati bloccati dall'utente $uid. Questo comunque non ha a che fare con la lista di amici.
<fb:profile-pic uid="$uid" />
Mostra l'immagine dell'utente $uid, sotto forma di link al suo profilo. È possibile indicare i parametri width e height come in un normale tag <img />, oppure utilizzare il parametro size che può assumere i valori thumb (larghezza 50px, valore di default), small (100px), normal(200px), oppure square (50x50 px)
<fb:user-status uid="$uid" />
Mostra lo status dell'utente $uid.
<fb:if-can-see uid="$uid" what="search"> Informazioni </fb:if-can-see>
Mostra il contenuto del tag se l'utente loggato ha i diritti necessari per avere accesso ai dati dell'utente $uid. L'attributo what restringe il campo in cui cercare. È possibile specificare al suo interno un contenuto alternativo, tramite il tag <fb:else>.
<fb:18-plus> Visibile se over 18 <fb:else>Visibile agli under 18</fb:else></fb:18-plus>
Mostra il contenuto del tag se l'utente è maggiorenne. L'eventuale contenuto alternativo va specificato nel tag <fb:else>. Esiste un analogo tag <fb:21-plus> che controlla se l'età dell'utente supera i 21 anni.
<fb:date t="$timestamp" format="$format" />
Mostra la data contenuta in $timestamp (Unix Timestamp), formattandola nel formato indicato da $format, in base alle impostazioni della lingua dell'utente. Tutti i parametri che possono essere assunti da $format sono indicati nel Wiki.
<fb:photo pid="$pid" />
Mostra la foto specificata in $pid, eventualmente indicando un parametro size (thumb, small, normal, album, square).
Considerazioni finali
In queste pagine abbiamo notato come le potenzialità della Facebook Platform siano notevoli, andando ben oltre quanto visto nel nostro primo Hello World. Va sottolineato che quanto analizzato nei precedenti paragrafi rappresenta solo una piccola parte delle funzionalità a disposizione. Raccomandiamo la lettura del Wiki (sezione API e sezione FBML) per una visione d'insieme più dettagliata. Il prossimo passo sarà costruire un'applicazione di esempio che ci consenta di mettere in pratica quanto scoperto finora, e che possibilmente rispetti le linee guida indicate da Facebook per quanto riguarda la creazione delle applicazioni, accennate alla fine del precedente articolo.
