En la primera parte vimos una introducción a las tecnologías usadas para programar en Facebook. En la segunda, creamos una aplicación, y le añadimos algún Social Plugin y etiquetas Open Graph. En el tercero, nos zambullimos en el SDK JavaScript, y autenticamos al usuario en nuestra aplicación, le solicitamos permisos extra, publicamos en su muro, y mostramos algún diálogo.

Hasta ahora hemos trabajado sobre una aplicación que funcione sobre nuestra página web. Sin embargo, como ya sabes, Facebook nos da más opciones: aplicaciones en móviles, y aplicaciones dentro de Facebook. Hoy vamos a ver cómo crear una aplicación dentro de Facebook. Esto se hace mediante un canvas (iframe) en Facebook en el que se mostrará la página web que deseemos. Por supuesto, en esa página web podremos gestionar JavaScript, CSS y HTML como queramos.

Dar de alta la aplicación Canvas

Vamos a configurar nuestra aplicación. Simplemente accedemos a Aplicaciones, seleccionamos la que deseemos, pulsamos sobre Edit Settings, desplegamos App on Facebook en la parte inferior, y establecemos la URL en la que colgaremos nuestra aplicación canvas (¡Recuerda que a partir del 1 de octubre de 2011 será obligatorio que tus aplicaciones canvas estén disponibles mediante HTTPS!):

¿Te has fijado que bajo las dos URLs hay un tercer campo donde pone Canvas Page? Es la dirección de Facebook desde donde se podrá acceder a tu aplicación canvas. Como ves, para construir la URL han usado el App Namespace que estableciste cuando diste de alta la aplicación en la segunda parte de esta guía.

En las aplicaciones Canvas tenemos disponibles nuevos métodos del SDK JavaScript. Algunos de ellos son:

FB.Canvas.getPageInfo

Un iframe, por seguridad, no puede acceder a los parámetros del documento raíz (window), por lo que, a priori, no hay forma de conocer algunos parámetros como son el tamaño del canvas o las coordenadas del scroll. Este método se salta esa restricción (solicitándoselo por HTTP a Facebook), y nos devuelve toda esa información:

  • clientHeight – Altura en píxels de la zona visible del navegador.
  • clientWidth – Ancho en píxels de la zona visible del navegador.
  • offsetLeft – Distancia entre el borde izquierdo del canvas y el borde izquierdo de la página de Facebook.
  • offsetTop – Distancia entre el borde superior del canvas y el borde superior de la página de Facebook.
  • scrollLeft – Desplazamiento del scroll izquierdo.
  • scrollTop – Desplazamiento del scroll derecho.

Echa un vistazo a este ejemplo para entender mejor cada valor.

FB.Canvas.setDoneLoading

Esta función indica el tiempo de carga de la aplicación (debes colocarlo en un punto en el cual consideres que la aplicación está lista para funcionar). Al invocarla, se enviará el resultado a Facebook Insights (las métricas de las aplicaciones y Facebook Pages) para que puedas hacerte una idea de cuánto tiempo lleva a tus usuarios cargar tu aplicación.

FB.Canvas.startTimer

Para usar junto con FB.Canvas.setDoneLoading. Indica el comienzo de un rango de tiempo que no se incluirá dentro del tiempo total de carga de la página.

FB.Canvas.stopTimer

Junto con FB.Canvas.startTimer, indica el final del rango de tiempo que no se debe tener en cuenta para el cálculo total de tiempo.

FB.Canvas.setUrlHandler

Alrededor de una aplicación hay diversos enlaces (a teletipos, marcadores, peticiones en el desplegable de marcadores, peticiones en el panel de notificaciones). Este método permite que, cuando un usuario haga clic en uno de esos enlaces, una función callback capture esa petición y realice alguna otra operación. Por ejemplo, si en un juego el usuario hace clic en un teletipo sobre un logro de un jugador, se podría capturar la petición y en lugar de redireccionar, mostrar el logro dentro de la aplicación.

Tamaño de la aplicación

Nuestra aplicación, lógicamente, tendrá un ancho y un alto. ¿Y si excede el ancho máximo que Facebook nos permite? ¿Y si su alto crece dinámicamente? Para lidiar con esto, vamos a ir a la configuración avanzada de nuestra aplicación, donde veremos esto:

Nos dan la opción de elegir cómo se comportará el ancho y el alto del canvas.

Ancho (Canvas Width)

Tenemos dos opciones:

  1. Fixed (760px). Es decir, el ancho será de tamaño fijo, establecido en 760 píxels.
  2. Fluid. El canvas (junto con toda la web de Facebook) se ajusta al ancho máximo que permita la ventana.

Alto (Canvas Height)

De nuevo, tenemos dos opciones:

  1. Ajustable (800px). En este caso, se establece un tamaño fijo (por defecto 800px).
  2. Fluid. El canvas ocupará el 100% del alto permitido. En caso de que exceda el alto asignado a la página, se mostrarán barras de desplazamiento en el canvas.

Junto con el modo de alto ‘Ajustable (800px)‘, tenemos 3 métodos más del SDK JavaScript (y los últimos):

FB.Canvas.setSize

Este método nos permite modificar en tiempo de ejecución la altura del canvas. Si en la configuración del ancho se estableció ‘Fixed (760px)‘, no se podrá exceder ese valor. Si no le pasamos ningún parámetro, tratará de determinar automáticamente el tamaño del canvas.

FB.Canvas.setAutoResize

Sirve para que el alto se autoajuste dinámicamente (por defecto, cada 100 milisegundos realiza un reajuste). En resumen, inicia un timer que invoca a FB.Canvas.setSize sin ningún parámetro.

Si la aplicación decrece de tamaño, el canvas no decrecerá.

FB.Canvas.scrollTo

Mueve la posición de la página (las barras de desplazamiento) a las coordenadas (x,y) deseadas.

Ejemplos

Vamos a ver algunos ejemplos para comprobar cómo manejar los métodos del SDK JavaScript para el tamaño del Canvas. Usaremos como valor de ancho ‘Fixed (760px)‘, y de alto ‘Ajustable (800px)‘.

  1. En el primer ejemplo vamos a ver una aplicación con 1500px de alto. Verás que no se visualiza el final de la aplicación. Ver ejemplo.
  2. En el segundo ejemplo llamaremos a FB.Canvas.setSize, sin ningún parámetro, para que determine él solo el tamaño de la aplicación, y lo defina en el canvas. Ver ejemplo.
  3. En el tercer ejemplo, tendremos un div que se expande y se contrae. El canvas no se ajustará a su tamaño pese a que llamemos a FB.Canvas.setSize al comenzar su ejecución. Ver ejemplo.
  4. Por último, en el cuarto ejemplo, tenemos de nuevo un div que se expande y se contrae. Sin embargo, en este caso el canvas sí se ajusta a su tamaño. Invocamos a FB.Canvas.setSize cada vez que se modifica el tamaño (esto no siempre será una opción válida, por lo que quizás convenga llamar a FB.Canvas.setAutoResize). Ver ejemplo.

Si quieres ver un how-to de cómo realizar aplicaciones fluidas (ancho y alto), revisa este post del blog de desarrolladores de Facebook.

Autenticación y permisos

Si quisiéramos que los usuarios se autenticaran en nuestra aplicación canvas, y además poder solicitarles permisos, lo haríamos de un modo muy similar a como lo hicimos en la aplicación web. En este ejemplo, la principal diferencia es que en lugar de recurrir al SDK JavaScript para añadir el social plugin “Entrar” (y de ese modo, mostrar el diálogo OAuth que solicita permisos), redirigiremos al usuario a una URL que únicamente muestra diálogo OAuth para solicitar los permisos.

Vamos a ver el código:

<html>
<head>
<meta charset="UTF-8" />
</head>
<body style="background-color: yellow; margin:0 auto; padding:20px;">
    <div style="height: 500px; background:#EEEEFF; padding: 10px;">
        <h1>Canvas app</h1>
        <p id="step1" style="display: none;">Estás desconectado de esta aplicación. Pulsa <a href="#" onclick="connect()">aquí</a> para conectar y acceder al contenido privado.</p>
        <p id="step2" style="display: none;">Estás en el contenido privado de esta aplicación :) 
        <br /><br />Si ya habías concedido permisos a esta aplicación, puedes borrarlos en los <a href="http://www.facebook.com/settings/?tab=applications" target="_blank">ajustes de aplicaciones</a> para ver el diálogo OAuth.</p>
    </div>
    <div id="fb-root"></div>
    <script type="text/javascript" src="http://connect.facebook.net/es_ES/all.js"></script>
    <script type="text/javascript">
        FB.init({
            appId  : '256797284360192',
            status : true, // comprobar estado de login
            cookie : true, // habilitar cookies para permitir al servidor acceder a la sesión
            xfbml  : true, // ejecutar código XFBML
            channelURL : 'http://chusete.es/facebook/channel.html', // fichero channel.html
            oauth  : true // habilita OAuth 2.0
        });

        FB.getLoginStatus(function(response) {
            if (response.authResponse) {
                document.getElementById('step2').style.display = 'block';
            } else {
                document.getElementById('step1').style.display = 'block';
            }
        });

        function connect() {
            top.location.href = 'https://www.facebook.com/dialog/oauth?client_id=256797284360192&redirect_uri=http://apps.facebook.com/chusetedemo/&scope=publish_stream'
        }
    </script>
</body>
</html>

Como ves, se trata de un documento HTML básico, que muestra un div con dos párrafos (los dos ocultos por defecto). El resto, es código JavaScript.

Vamos a analizar este código:

  1. En primer lugar, cargamos el SDK JavaScript.
  2. Después, realizamos una llamada a FB.getLoginStatus, que, como ya sabemos, nos sirve para determinar si el usuario ha conectado o no con nuestra aplicación. En caso afirmativo, mostramos el párrafo cuyo id es ‘step2′. En caso negativo, mostramos el párrafo con id ‘step1′.
  3. El párrafo ‘step1′ tiene un link para que los usuarios conecten con la aplicación. Cuando lo pulsan, se ejecuta la función ‘connect()’, cuyo único cometido es redirigir a la URL del diálogo OAuth. La estructura de esta URL es la siguiente:
    https://www.facebok.com/dialog/oauth?client_id=APP_ID&redirect_uri=APP_URL&scope=PERMISOS

    Por supuesto, existen más parámetros GET que los que hemos usado. Puedes consultarlos todos en la documentación del diálogo OAuth.

Diálogo OAuth que se muestra al redirigir a su URL

Una vez que el usuario está autenticado, y nos ha concedido permisos, podríamos hacer como en el ejemplo de la tercera parte, y publicar una historia en su muro.

Acerca de top.location.href

Si te fijas, para enlazar a la URL del diálogo OAuth, hemos usado top.location.href. Si hubiéramos enlazado de forma directa, la redirección se habría realizado dentro del canvas, y no en la ventana principal (top).

Del mismo modo, también podríamos haber hecho esto sin JavaScript, poniendo la URL de destino en el atributo href del elemento <A>, y añadiendo el atributo target con el valor ‘_top’:

<a href="https://www.facebook.com/dialog/oauth?client_id=APP_ID&redirect_uri=APP_URL&scope=PERMISOS" target="_top">

Social Channels

¿Pensabas que ya conocías todos los conceptos de Facebook? ¡Todavía no! Te presento los Social Channels. Se trata de un concepto que englobal todas las herramientas que Facebook pone a disposición de los desarrolladores para ayudar a que los usuarios compartan las aplicaciones con sus amigos. En resumen, herramienta para ayudar a que tus usuario promocionen y no dejen de usar tu aplicación.

Éstas son los canales de las que dispones:

  • Muro – Ya conoces el muro. Es el principal lugar donde compartes publicaciones de cualquier tipo con tus amigos. Como programador, puedes solicitar permisos al usuario para publicar historias en su nombre (como ya sabes, con el permiso publish_stream), o puedes mostrarle un diálogo Feed para que lo haga él. Por otra parte, el botón ‘Me gusta’ también permite que se comparta un contenido en el muro.
  • Peticiones – Permite que los usuarios envíen invitaciones a sus amigos para que utilicen tu aplicación. Al igual que con el muro, puedes solicitar permisos al usuario para enviar peticiones en su nombre (con el permiso apprequest), o bien dejar que lo realice él con el diálogo de peticiones.
  • Juegos – Si estás desarrollando un juego, dentro del Graph API tienes opciones para administrar los logros o las puntuaciones de tus usuarios, para de esta forma hacer al juego más competitivo. Puedes revisar este post del blog de desarrolladores de Facebook para conocer más sobre cómo publicar logros y puntuaciones de usuarios.
  • Marcadores – Es el enlace a las aplicaciones que se muestra en la columna izquierda de la página principal de Facebook.
  • Paneles – Hay dos paneles de aplicaciones. El panel de aplicaciones propiamente dicho y el panel de juegos. Desde estos paneles, se muestran recomendaciones, invitaciones, y catálogos de aplicaciones.
  • Página de perfil de aplicaciones – Tal como vimos en la segunda parte, cada vez que damos de alta una nueva aplicación, automáticamente se crea su página de perfil. Desde aquí, podrás escribir novedades y actualizaciones que recibirán tus usuarios.

Pestañas de páginas

Hay un segundo tipo de aplicaciones canvas que puedes utilizar: las Page Tabs. Son aquellas aplicaciones que se muestran como una pestaña dentro de una Facebook Page. Por ejemplo, accede a la Facebook Page de Coca-Cola, y verás que dentro de la página de Coca-Cola hay una aplicación.

Ahora vamos a revisar los principales puntos de las Page Tabs.

Diseño

En la siguiente imagen puedes ver dónde va ubicada una aplicación de tipo page tab:

Abre la imagen y fíjate en estas cosas:

  • El hueco central está disponible para tu aplicación. Pero en este caso, a diferencia de una aplicación canvas normal, dispondrás de un ancho máximo de 520px.
  • El título de la página ahora es
    “NOMBRE_PAGINA ᐅ NOMBRE_PAGE_TAB”.
    Al configurar la Page Tab podrás definir con qué nombre aparecerá.
  • En la columna izquierda aparece el enlace para la Page Tab, con el nombre que, como veremos a continuación, hayamos establecido en su configuración.

Configuración

Para configurarla, debemos acceder al apartado Aplicaciones, seleccionamos la que deseemos y pulsamos sobre Edit Settings. Esta vez, en el panel inferior desplegaremos Page Tab:

Vemos cuatro campos:

  1. Page Tab Name – Corresponde al nombre de la aplicación. Será el nombre con el que se cree el enlace dentro de las Facebook Pages, y el que aparecerá en el título.
  2. Page Tab URL – Dirección URL donde se podrá localizar la aplicación.
  3. Secure Page Tab URL – Dirección URL mediante HTTPS donde se podrá localizar la aplicación. A partir del 1 de octubre de 2011, será obligatoria.
  4. Page Tab Edit URL – Dirección URL accesible para los administradores de las Facebook Pages desde donde se les podrá ofrecer un panel de control para personalizar la aplicación.

Añadir a una página

Una vez tengamos la aplicación creada, querremos que se muestre en alguna de nuestras Facebook Pages. Esto, que pudiera parecer algo trivial, no lo es tanto, pues se encuentra un poco escondido. Deberemos acceder a la página de perfil de nuestra aplicación, en la columna izquierda localizamos el link donde pone “Añadir a mi página”, y seleccionamos aquélla en la que lo queramos añadir.

Página de perfil de una aplicación

Como vimos en la segunda parte de esta guía, cada vez que damos de alta una aplicación, se crea junto con ella una página de perfil. Para acceder a ella lo más fácil es ir a la configuración de la aplicación, y desde la columna izquierda hacemos clic sobre View App Profile Page. En el caso de mi aplicación de pruebas, su URL será
http://www.facebook.com/apps/application.php?id=256797284360192.

Diferencias

El desarrollo de aplicaciones en Page Tabs es exactamente igual que el de las aplicaciones canvas normales; es decir, podremos añadir el código HTML, CSS y JavaScript que deseemos. Igualmente, podemos hacer uso del SDK JavaScript para autenticar al usuario, solicitar permisos, realizar consultas al Graph API, mostrar diálogos, etc.

Pero tenemos algunos nuevos parámetros disponibles. En el objeto signedRequest, se añadirá un nuevo parámetro ‘page’ que contiene lo siguiente:

  • id – ID de la página actual.
  • admin – Indicando si el usuario es o no administrador de la página.
  • liked – Indica si al usuario le gusta o no la página (sin necesidad de permisos).

Además, para personalizar el contenido de la aplicación, podríamos añadir el parámetro GET app_data a la URL principal de Facebook a la que se accede. El valor de este parámetro se traspasará también al objeto signedRequest.

signedRequest

Hasta ahora no hemos hablado de este objeto. Como puedes ver en la documentación oficial, sirve para, en determinados escenarios, compartir información entre Facebook y nuestra aplicación. De entre la información disponible está:

  • user – Datos básicos del usuario.
  • algorithm – Algoritmo con el que se ha firmado.
  • issued_at – Fecha en la que se ha firmado.
  • user_id – Identificador del usuario actual.
  • oauth_token – cadena de texto que se puede usar para realizar peticiones al Graph API.
  • expires – Fecha en que expira el objeto.
  • app_data – Contenido del parámetro GET app_data.
  • page – Información disponible para las Page Tabs.
  • profile_id – En caso de que la aplicación esté dentro de una página, y se haya creado con FBML, contendrá el ID de la página.

Este objeto JSON viene codificado en base64, y firmado con HMAC y SHA-256 usando el App Secret (el código secreto que se generó al dar de alta la aplicación). Gracias a esto sabremos que la petición está firmada por Facebook, y no por terceras partes. Si hiciéramos público el App Secret, o si no comprobáramos la firma, no tendríamos esa certeza. Por esa razón, está completamente desaconsejado acceder a los parámetros de signedRequest desde JavaScript. Cuando veamos el SDK PHP veremos cómo revisar estos campos.

En cualquier caso, si quisieras acceder a la cadena de texto codificada de signedRequest en JavaScript, podrás hacerlo mediante el objeto response que devuelve el método FB.getLoginStatus. Puedes imprimirlo en el log de la consola JavaScript (console.log) para ver el contenido completo de este objeto.

Resumen

Ya habíamos visto los principales conceptos de Facebook, cómo crear una aplicación, cómo usar plugins sociales, y cómo utilizar Open Graph. También revisamos prácticamente todo el SDK JavaScript, viendo cómo iniciar sesión, solicitar permisos, y realizar acciones mediante el Graph API.

Esta vez, hemos visto cómo crear otro tipo de aplicaciones; las aplicaciones canvas que se muestran dentro de Facebook, y que también se pueden incorporar como pestaña de una Facebook Page. Hemos terminado de ver el resto de métodos del SDK JavaScript, que nos permiten gestionar asuntos relacionados con Canvas. Del mismo modo, hemos realizado una autenticación y solicitud de permisos equivalente a la de una aplicación web, pero esta vez dentro de canvas. Tambien conocemos ahora un nuevo objeto, signedRequest, que permite que Facebook comparta información con nuestra aplicación. Y, además, hemos revisado las herramientas que Facebook pone a nuestra disposición para promocionar nuestras aplicaciones: los Social Channels.

Si has llegado hasta aquí, ya tendrás bastante soltura desarrollando aplicaciones para Facebook. En la siguiente, y última parte, veremos cómo usar el SDK de PHP. ¡Hasta pronto!