Quinta y última parte de esta guía introductoria al desarrollo de aplicaciones web sobre la Facebook Platform. Ya conoces el ecosistema de tecnologías de Facebook, sabes cómo crear distintos tipos de aplicaciones, y conoces el SDK JavaScript por completo. Hoy vamos a ver el PHP SDK.

Antes de seguir leyendo, puedes echar un vistazo a la página GitHub donde está alojado el proyecto PHP SDK, y desde donde te lo podrás descargar. Nosotros vamos a hablar sobre la última versión estable, la 3.1.0.

1 Instalación

Ya has dado de alta tus aplicaciones, y ahora quieres saber cómo incorporar el PHP SDK a alguna de ellas. Lo primero, deberás descargarte el SDK de su página en GitHub y descomprimirlo. Verás tres carpetas:

Se incluye:

  • changelog.md – Fichero que registra todos los cambios entre las distintas versiones del SDK.
  • examples – Un ejemplo de uso.
  • readme.md – Fichero ‘léame’ con documentación básica.
  • src – Bibliotecas del SDK. Esta carpeta es la que usaremos en nuestro proyecto.
  • tests -Batería de tests unitarios para comprobar el correcto funcionamiento del SDK.
Vamos a crear una nueva carpeta, donde crearemos un fichero index.php y donde copiaremos la carpeta ‘src’:
Ahora, editaremos el fichero index.php y añadiremos el código de inicialización del PHP SDK:
<?php
    require_once("src/facebook.php");

    $config = array(
        'appId' => 'TU_APP_ID',
        'secret' => 'TU_APP_SECRET',
        'fileUpload' => false, // opcional
    );

    $facebook = new Facebook($config);

Es decir, cargamos el SDK, creamos un nuevo array con la configuración del objeto Facebook, y finalmente lo creamos. ¡Ya está! :) Ya puedes usar el PHP SDK.

2 Métodos básicos

Vamos a ver 6 métodos getter y setter básicos:

Facebook::getAccessToken

Mediante este método podremos obtener el accessToken en uso. Los access token son objetos que definen los permisos que tenemos para interactuar con un determinado usuario. Puedes ver más sobre el objeto access_token en la documentación de los permisos.

Facebook::setAccessToken

Del mismo modo, podremos establecer el accessToken con el que funcionará nuestra aplicación. Se sobreentiende que este AccessToken ha sido obtenido por algún medio ajeno al SDK de PHP (por ejemplo, mediante cURL).

Facebook::getApiSecret

Nos devuelve el APP_SECRET de la aplicación.

Facebook::setApiSecret

Permite establecer a mano el APP_SECRET para nuestra aplicación

Facebook::getAppId

Devuelve el APP_ID de nuestra aplicación

Facebook::setAppId

Nos permite establecer a mano el APP_ID de la aplicación

3 Métodos de autenticación

Lo primero es lo primero. Vamos a ver cómo podremos autenticar a un usuario, y cómo solicitarle permisos. Para ello, vamos a revisar antes cuatro métodos más:

Facebook::getLoginStatusUrl

Este método nos permite especificar URLs según el estado de login del usuario, de manera que en función de este estado, nos redirigirá a un URL u otra. Hay tres estados posibles:

  1. ok_session – El usuario ha iniciado sesión en Facebook.
  2. no_user – El usuario no ha iniciado sesión en Facebook.
  3. no_session – El usuario no está conectado a nuestra aplicación.

El valor devuelto por esta URL es una dirección de Facebook que se encarga de llevar a cabo por nosotros la redirección. Puedes probar aquí para ver en funcionamiento este ejemplo:

    if (isset($_GET['status']) && !empty($_GET['status'])) {
        switch($_GET['status']) {
            case 1: echo 'Te conozco :) '; break;
            case 2: echo 'No est&aacute;s conectado a Facebook.'; break;
            case 3: echo 'Est&aacute;s conectado, pero no te conozco.'; break;
        }
        echo "<br /><a href='http://www.chusete.es/facebook/phpdemo/getLoginStatusUrl.php'>Volver a intentar</a>";
    } else {
        $params = array(
            'ok_session' => 'http://www.chusete.es/facebook/phpdemo/getLoginStatusUrl.php?status=1',
            'no_user' => 'http://www.chusete.es/facebook/phpdemo/getLoginStatusUrl.php?status=2',
            'no_session' => 'http://www.chusete.es/facebook/phpdemo/getLoginStatusUrl.php?status=3',
        );

        header("Location: ".$facebook->getLoginStatusUrl($params));
    }

Facebook::getLoginUrl

Construye por nosotros la URL desde la que accedemos a la página que nos muestra el diálogo OAuth. Acepta dos parámetros:

  1. scope – Como ya sabes, la lista de permisos que queremos solicitar al usuario.
  2. redirect_uri – Dirección a la que se redirigirá tras el diálogo OAuth.
Por ejemplo:
    $params = array(
        'scope' => 'read_stream, friends_interests',
        'redirect_uri' => 'http://chusete.es/post_login_page',
    );

    $loginUrl = $facebook->getLoginUrl($params);

De este modo, en $loginUrl tendremos una URL que nos mostrará el diálogo OAuth que solicita al usuario permisos para consultar su muro y para conocer los intereses de sus amigos. Tras aceptarlo, se le redirigirá a la dirección de redirect_url.

Facebook::getLogoutUrl

Del mismo modo que podemos generar la URL de inicio de sesión en nuestra aplicación, podemos crear otra para salir. Sólo debemos indicar un parámetro (opcional):

  • next – URL a la que se le redirigirá al usuario tras hacer logout.

Facebook::getUser

Este método tan sólo nos devuelve el ID del usuario activo en nuestra aplicación.

4 Autenticación

Ya tienes la aplicación creada, ya has descargado el SDK, ya has instanciado un objeto de la clase Facebook, y ya conoces los métodos necesarios. Es el momento de ver cómo hacer un inicio de sesión en nuestra aplicación :)

Esto es lo que va a realizar nuestro ejemplo: Cuando el usuario acceda a la aplicación, si ha conectado con ella previamente, se le mostrará un mensaje de bienvenida. En caso contrario, le reenviaremos al diálogo OAuth para solicitarle permisos. Si los acepta, volverá a la aplicación, donde le daremos la bienvenida y le daremos la opción de cerrar sesión. En caso contrario, le mostraremos un mensaje lamentando que no haya conectado con nuestra súper app. Puedes ver aquí la demo.

Éste es el código:

    $params = array(
        'scope' => 'read_stream, friends_interests',
        'redirect_uri' => 'http://chusete.es/facebook/phpdemo/',
    );
    $loginUrl = $facebook->getLoginUrl( $params );

    if ( $_GET['error'] ) {
        echo "Parece que no quieres usar la aplicaci&oacute;n :( <br />";
        echo "Si cambias de opini&oacute;n, haz clic <a href='".$loginUrl."'>aqu&iacute;</a>";
    } elseif( $facebook->getUser() ) {
        $logoutUrl = $facebook->getLogoutUrl(array('next' => 'http://www.facebook.com/'));
        echo "Bienvenido! :) <br />";
        echo "Puedes <a href='".$logoutUrl."'>cerrar sesi&oacute;n</a> si lo deseas.";
    } else {
        header( "Location: ".$loginUrl );
    }

Como de costumbre, vamos a revisarlo:

  1. En primer lugar construímos la URL en la que se muestra el diálogo OAuth, generado a partir de unos determinados parámetros:
    1. Solicitamos algunos permisos extra: read_stream y friends_interets.
    2. Definimos la URL actual como la dirección a la que debe retornar el diálogo OAuth tras la autorización (o no) del usuario.
  2. Ahora seguimos la ejecución. Recuerda que, como hemos definido esta misma URL como dirección de retorno, cuando el usuario autorice (o no) nuestra aplicación, volveremos aquí:
    1. Si está presente el parámetro GET ‘error‘, significa que el usuario no autorizó la aplicación. En ese caso mostramos un mensaje con una carita triste, y le damos de nuevo la opción de conectar con la aplicación.
    2. En caso contrario, comprobamos si hay algún usuario reconocido. Si así fuera, mostramos un mensaje de bienvenida y un link de logout.
    3. Y si no hubiera ningún usuario reconocido, redirigiríamos automáticamente mediante la función header() a la URL del diálogo OAuth desde la que podrá conectar con la aplicación.

5 Resto de métodos

Lo creas o no, hemos visto prácticamente todos los métodos del PHP SDK. Vamos a revisar los cuatro que nos quedan:

Facebook::api

Método polimórfico que nos permite realizar llamadas al Graph API (incluso con FQL, el Facebook Query Language). Puede lanzar excepciones de tipo FacebookApiException. Para poder realizar consultas que no sean públicas, debemos asegurarnos previamente de que tenemos permisos suficientes de ese usuario. Puedes probar esta demo, de la que tienes a continuación el código:

<?php
    require_once("src/facebook.php");

    $config = array(
        'appId' => '256797284360192',
        'secret' => '1e4791731181402f02399fbe174cdb0d',
        'fileUpload' => false, // opcional
    );

    $facebook = new Facebook($config);

    $loginUrl = $facebook->getLoginUrl();

    $user = $facebook->getUser();
?>
<html>
    <head>
        <meta charset="UTF-8" />
    </head>
    <body>
    <?php
        if($user) {
            try {
                $_SESSION['user_id'] = $user;
                $user_profile = $facebook->api('/me','GET');
                echo "Nombre: " . $user_profile['name'];
            } catch(FacebookApiException $e) {
                echo "Error. Posiblemente ha expirado la sesión. ";
                echo "<a href='".$loginUrl."'>Volver a iniciar sesión</a><br />";
                $result = $e->getResult();
                var_dump($result);
            }
        } else {
            echo "Haz clic <a href='".$loginUrl."'>aqu&iacute;</a> para iniciar sesi&oacute;n";
        }

    ?>
    </body>
</html>

FacebookApiException

Cuando realizamos una consulta al API de Facebook mediante Facebook::api, podrán lanzarse excepciones, por lo que cada llamada a Facebook::api deberá ir dentro de su bloque try-catch correspondiente. Las excepciones tendrán estos dos métodos:

  1. getResult – Devuelve un objeto array con el mensaje de error que devuelve el servidor.
  2. getType – Devuelve el tipo de excepción, como por ejemplo OAuthExcepcion.

Facebook::getSignedRequest

En la cuarta parte de esta guía vimos qué es el objeto signedRequest. Como dijimos, se trata de un objeto que sirve para compartir información entre Facebook y nuestra aplicación. Desde JavaScript no era seguro su uso, ya que, al no deber hacer público el APP_SECRET de una aplicación, no podríamos tener la certeza de que el contenido del objeto signedRequest estuviera realmente firmado por Facebook.

Sin embargo, desde PHP sí podremos, y este método realiza todo el trabajo sucio por nosotros: decodifica, comprueba la firma, y devuelve el objeto en forma de array PHP. De esta forma, con el objeto devuelto por este método podríamos comprobar en una aplicación de tipo Page Tab si el usuario es o no fan (sin necesidad de solicitar ningún permiso).

Consulta la documentación de signedRequest para más información.

Facebook::setFileUploadSupport

Habilita o deshabilita el soporte para subida de ficheros. Éstas se realizarán mediante llamadas al Graph API con el método Facebook::api utilizando el método de envío POST. Podemos ver el ejemplo de la documentación de Facebook:

$facebook->setFileUploadSupport(true);

$img = '/tmp/mifoto.png';

$photo = $facebook->api(
    '/me/photos',
    'POST',
    array(
        'source' => '@' . $img,
        'message' => 'Foto subida mediante el SDK de PHP!'
    )
);

Facebook::useFileUploadSupport

Indica si está o no habilitado el soporte para subir ficheros.

6 Y ahora qué

Si te has quedado con ganas de más, estás de enhorabuena, porque han quedado muchos conceptos en el tintero.

Otros SDK. Si tienes pensado desarrollar para Android, puedes echar un vistazo al Android SDK. Puedes hacer también lo propio con el iOS SDK si tu intención es crear una aplicación para iPhone o iPad.

Consultas más eficaces. Otro asunto interesante por explorar es el lenguaje FQL para realizar consultas a-la-SQL a Facebook. Mediante este método puedes llevar a cabo comportamientos que con el Graph API no podrías, como ejecutar consultas por lotes.

¡Internacionalizate! Es otra de las opciones que proporciona Facebook: habilita tu aplicación para que sea traducida, preparándola según las directrices de internacionalización de Facebook.

Todavía más APIs… Tienes a tu alcance Ads API, que te permitirá crear y monitorizar mediante código ambiciosas campañas publicitarias. O Credits API, con la que podrás permitir a tus usuarios comprar créditos de Facebook con los que adquirir nuevas funcionalidades o ítems en tu aplicación. Y Chat API, con la que podrás incorporar a tu página web, o aplicación nativa, un chat compatible XMPP compatible con Facebook.

Más sobre Graph API. Si te interesa conocer más acerca de las consultas por lotes, tienes un apartado íntegro dedicado a ellas. Tienes también una API de actualizaciones en tiempo real.

Juegos. Lo mencionamos de pasada, pero existe toda una API para que los desarrolladores de videojuegos puedan añadir logros y puntuaciones.

Social Design, es como llaman en Facebook a la forma de pensar cómo crear productos sociales, utilizando tres conceptos clave, comunidad, conversación e identidad. Ver más sobre Social Design.

Opciones, muchas más opciones de configuración:

  • Configuración avanzada:
    • Deauthorize Callback – Definir una URL a la que se hará un ping cada vez que un usuario se desvincule de tu aplicación (con información en el signedRequest).
    • Migraciones – Facebook está en constante cambio. Puedes elegir qué tecnologías usar: las que están en uso o las obsoletas.
    • Seguridad – Autorizar determinadas IPs para realizar peticiones en nombre de tu aplicación o para cambiar su configuración. Alertas por email.
    • Publicidad – Puedes indicar las direcciones de correo de las cuentas de usuario utilizadas para la publicidad de la página.
    • Datos de contacto – Enlaces a las URLs de privacidad, condiciones de uso, de soporte, etc.
  • Roles – Desde donde podrás añadir otros usuarios a diferentes perfiles: Desarrollador, tester, usuarios de pruebas (usuarios falsos creados al vuelo), etc.
  • Credits – Donde personalizas los parámetros de configuración necesarios para poder operar con créditos Facebook.

Nueva versión de Open Graph: Hasta ahora podía establecerse un vínculo entre un usuario y otro objeto con el verbo “me gusta”. Por ejemplo, “A Pedro le gusta Coca-Cola“. Tenemos un sujeto (Pedro), una acción (gustar), y un objeto (Coca-Cola). Hasta ahora el verbo era siempre “gustar”. Sin embargo, con esta nueva versión, podrá ser cualquier cualquier cosa: “María ha tomado un Big Mac“. Puedes seguir este tutorial paso a paso.

7 Resumen

Con suerte, habrás llegado hasta aquí. Eso significa que ya ha finalizado tu toma de contacto con el desarrollo de aplicaciones en Facebook. Dominas tecnologías básicas como los social plugins, open graph, o los diálogos. Sabes crear distintos tipos de aplicaciones, ya sea en una web externa, en un Canvas, o en un Page Tab. Conoces a fondo el JavaScript SDK y el PHP SDK. Has tenido una toma de contacto con el Graph API. Sabes autenticar y solicitar permisos a tus usuarios en cualquier escenario. Eres consciente del resto de tecnologías de Facebook que tienes a tu alcance. Sabes qué son los Social Channels, y cómo aprovecharlos para dar mayor visibilidad a tus aplicaciones. No está nada mal, ¿no?

Espero que hayas disfrutado de estos artículos tanto como yo, y ojalá puedan serte de utilidad.

¡Muchas gracias por haber seguido esta guía!.