[EDIT]
Facebook abandonne le langage FBML. Dorénavant, toutes les applications devront être écrites selon les standards du web (HTML/CSS/JavaScript) et être intégrées à Facebook grâce aux iFrames. Ce tutoriel est donc devenu en grande partie obsolète.
[/EDIT]
Je vous propose un tutoriel pour créer votre première application Facebook. Il existe deux APIs standards, l’une en PHP, l’autre en Java. Nous allons étudier la seconde. Notre application s’appellera yafba (Yet Another Facebook Application).
Nota : Certaines lignes de code sont trop longues et ne s’affichent pas entièrement. Dans ce cas, faites un copier-coller dans un éditeur de texte.
Prérequis
Vous devez posséder un compte sur Facebook et ajouter l’application developers. Cette application va vous permettre d’obtenir une clé d’API pour votre application et vous permettre d’accéder à la documentation en ligne.
Vous devez également avoir un hébergement Java. En effet, bien que les utilisateurs accédent à votre application par l’intermédiaire de Facebook, vous hébergez vous-même l’application et les données que vous recueillez. Ce qui est important, c’est que le serveur qui héberge votre application doit être accessible publiquement par une URL. Il n’est pas nécessaire d’acquérir un nom de domaine, vous pouvez utiliser l’URL fournie par votre hébergeur.
L’environnement de développement
Vous devez télécharger l’API Facebook. Celle-ci est disponible via l’application developers :
L’archive contient le code source de la librairie à partir duquel vous pourrez générer la javadoc. Vous trouverez également la librairie compilée sous la forme d’une archive facebook.jar que vous devez importer dans votre projet.
Notez qu’il n’est pas possible de tester une application Facebook en localhost. Pour être testée, l’application doit être déployée sur le serveur que vous avez déclaré dans l’adresse de callback. Il existe néanmoins un émulateur accessible en ligne qui permet de tester son code FBML ou de tester l’API Facebook.
L’architecture
Nous n’aborderons pas la structure d’une application Facebook en détail, celle-ci est constituée de plusieurs composants dont la plupart sont générés automatiquement par les serveurs de Facebook. Nous nous intéresserons uniquement à la génération de la page d’accueil.
Pour faire fonctionner notre application, nous utiliserons un simple conteneur de Servlet, par exemple Tomcat. L’application reposera sur les Servlets et les JSPs. Les Servlets auront la responsabilité d’extraire les informations de l’API Facebook, et les JSPs serviront à générer la couche présentation au format FBML (FaceBook Markup Langage). Nous utiliserons accessoirement la librairie JSTL.
Référencement de l’application sur Facebook
Avant de développer notre application, nous allons commencer par la référencer sur Facebook. Pour cela, vous devez demander une clé d’API par le biais de l’application developers.
Les informations importantes à fournir sont le nom de votre application et l’URL de callback. Cette dernière doit correspondre à l’URL de votre serveur suivi du répertoire dans lequel vous avez l’intention de placer votre application. Elle est de la forme http://serveur.com/yafba/.
Vous pouvez également définir une URL pour le canvas qui correspond au cadre de votre application. Celle-ci est de la forme http://apps.facebook.com/yafba/. Ainsi, lorsque votre serveur contient un fichier http://serveur.com/yafba/index.jsp, celui-ci est accessible à travers Facebook par l’url http://apps.facebook.com/yafba/index.jsp.
Demandez enfin à ce que votre application puisse être intégrée à Facebook, cela permettra aux utilisateurs de l’ajouter à leur profil sous la forme d’un widget. Vous verrez alors apparaître des options supplémentaires. Parmi celles-ci, l’URL Post-Add correspond à l’URL « frontale » vers laquelle sont dirigés les utilisateurs qui cliquent sur le lien de votre application.
Toutes ces opérations se font à partir de l’application developers.
Connexion
Maintenant que notre application est référencée sur Facebook et que notre environnement de développement est correctement configuré, nous allons commencer à coder.
Nous allons écrire une Servlet « test » qui traitera les requêtes en provenance de Facebook :
<servlet>
<servlet-name>test</servlet-name>
<servlet-class>fr.hadf.yafba.servlets.Test</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>test</servlet-name>
<url-pattern>/test</url-pattern>
</servlet-mapping>
La classe centrale de l’API est FacebookRestClient. Il s’agit d’une classe abstraite qui est héritée par deux sous-classes qu’on choisi selon le protocole qu’on veut utiliser, XML ou Jason. Nous allons utiliser le protocole XML.
La première chose que nous faisons est d’extraire le champ « fb_sig_session_key » de la requête entrante. Si ce champ est vide, nous redirigeons l’utilisateur vers la page de login dont l’URL est construite avec la clé d’API. Lorsque l’utilisateur aura été authentifié, il sera à nouveau redirigé vers notre Servlet, mais cette fois avec un champ « fb_sig_session_key » renseigné :
private void connection(HttpServletRequest req, HttpServletResponse res)
throws ServletException, IOException, FacebookException {
String sessionKey = req.getParameter("fb_sig_session_key");
if(sessionKey == null) {//on redirige l'utilisateur vers la page de login
String url = "http://www.facebook.com/login.php?api_key="+api_key+"&v=1.0&canvas&next=test";
res.getWriter().println("<fb:redirect url='"+url+"' />");
return;
}
else {//l'utilisateur est maintenant authentifié
FacebookXmlRestClient client = new FacebookXmlRestClient(api_key, secret, sessionKey);
loginSuccessfull(client, req, res);
}
}
Utilisation de l’API Facebook
Nous allons maintenant utiliser l’API Facebook pour extraire la liste des amis de l’utilisateur courant :
protected void loginSuccessfull(FacebookRestClient client, HttpServletRequest req, HttpServletResponse res)
throws IOException, FacebookException, ServletException {
Document root = (Document)client.friends_get();
NodeList list = root.getElementsByTagName("uid");
ArrayList friends = new ArrayList();
for(int i=0; i<list.getLength(); ++i) {
String uid = list.item(i).getTextContent();
friends.add(uid);
}
req.setAttribute("friends", friends);
getServletContext().getRequestDispatcher("/test.jsp").forward(req, res);
}
Nous utilisons simplement la fonction FacebookRestClient.friends_get(). Cette méthode retourne un objet diffèrent selon qu’on utilise le protocole XML ou Jason. Dans notre cas, nous récupérons un objet de type org.w3c.dom.Document. Pour connaître le format de la réponse, il suffit d’interroger la console de test disponible sur Facebook :
<?xml version="1.0" encoding="UTF-8"?>
<friends_get_response xmlns="http://api.facebook.com/1.0/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd"
list="true">
<uid>1</uid>
<uid>2</uid>
<uid>3</uid>
</friends_get_response>
Nous extrayons alors le champ uid et utilisons l’objet request pour passer la liste des valeurs à la JSP.
Nous n’utilisons pas cette fonction, mais sachez que l’API permet également d’interroger la base d’utilisateur de Facebook grâce au langage FQL :
Document root = (Document)client.fql_query("SELECT name FROM user WHERE uid=" + uid;
Couche présentation
Nous commençons par écrire une page index.jsp qui nous servira d’URL « frontale », celle déclarée en URL Post-Add. Elle sollicite l’utilisateur pour envoyer une série d’invitations à ses amis afin d’ajouter notre application à leur profil :
<%@ page language="java" pageEncoding="UTF-8"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<fb:fbml>
<fb:request-form type="yafba"
action="test"
content="Je vous invite à ajouter l'application yafba">
<fb:multi-friend-selector actiontext="Selectionnez les amis auxquels vous voulez adresser une invitation"/>
</fb:request-form>
</fb:fbml>
Notre application est ensuite très simple, elle se contente d’afficher une liste d’amis (test.jsp). Rappelons que cette liste a été extraite à partir de la Servlet « test » qui est appelée après validation du formulaire d’invitation. Nous utilisons la librairie JSTL pour garder propre la couche présentation :
<%@ page language="java" contentType="text/html; charset=UTF-8"
pageEncoding="UTF-8"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<fb:fbml>
<c:forEach items="${requestScope['friends']}" var="uid">
<fb:name uid="${uid}"/><br>
</c:forEach>
</fb:fbml>
Conclusion
Vous venez d’écrire votre première application Facebook. Elle est accessible à partir du cadre « My Application » dans l’application developers.
Il ne s’agit que d’une présentation très modeste de ce qu’il est possible de faire. Ce tutoriel vous a surtout permis de comprendre l’architecture d’une application Facebook. A vous maintenant d’explorer la documentation si vous voulez aller plus loin.
Bonne continuation 😉
Remerciements
Je remercie Michael Bagur pour son aide précieuse, en particulier pour la phase de connexion à l’API, et pour sa relecture.
Web.java 