API de Facebook con PHP

Esta mañana he tenido que dedicar un buen rato a lidiar con los caprichos de la API de Facebook, API que no había tenido necesidad de utilizar nunca, y cuya documentación, si hemos de ser sinceros, no me ha dejado un buen sabor de boca. Por eso, por si alguno os encontrarais alguna vez con cualquier complicación al intentar publicar una nota en el muro, subir una imagen al álbum o publicar un evento usando PHP, os dejo una pequeña explicación de cómo lo he hecho yo. Procedimiento que no tiene por qué ser el mejor o ser si quiera correcto, ojo: si tenéis cualquier sugerencia, os espero en los comentarios.

Lo primero que necesitaremos, evidentemente, es la API oficial de Facebook, que podemos descargar desde GitHub. Descomprimimos el archivo y lo subimos a nuestro servidor.

También necesitamos crear una aplicación, que será la encargada de llevar a cabo estas operaciones sobre nuestra cuenta de usuario o de marca. Para ello os podéis dirigir al sitio web de desarrolladores de Facebook, donde os pedirán amablemente que validéis vuestra cuenta, bien introduciendo vuestro teléfono móvil, para que os envíen un código de confirmación, o bien introduciendo vuestro número de cuenta. En serio, es escalofriante, pero ya sabemos todos como es Facebook.

Una vez hayáis creado la aplicación, podréis consultar el id de la aplicación y la clave secreta de aplicación en esa misma página. Estos son dos de los datos que vamos a necesitar, así que tenerlos a mano.

Lo siguiente que necesitamos es que nuestro usuario dé permisos a nuestra aplicación para poder interactuar con nuestra cuenta. Esto lo podemos hacer de forma sencilla utilizando una URL especialmente diseñada a tal efecto, que tendrá el siguiente aspecto:

https://graph.facebook.com/oauth/authorize?type=user_agent&
client_id=ID_APLICACION&
redirect_uri=http://www.facebook.com/connect/login_success.html&
scope=offline_access,manage_pages,publish_stream,create_event

donde:

• client_id es el id de la aplicación, que habíamos apuntado en el paso anterior
• redirect_uri es la página a la que redireccionar el navegador una vez hayamos dado los permisos a la aplicación
• y scope es una lista de permisos, cuyos posibles valores podemos consultar en la documentación al respecto. El permiso offline_access es uno de los más importantes: permite que el token que nos va a pasar Facebook para autenticarnos no caduque, incluso cuando el usuario esté desconectado. Si quieres interactuar con las páginas que gestiona tu usuario, en lugar, o además de con tu propia cuenta personal, necesitarás requerir también el permiso manage_pages

Al cargar la URL en tu navegador y pulsar ‘Permitir’, si no ha pasado nada raro, Facebook debería redirigirte a la página que indicaste como valor de redirect_uri, añadiendo a esta un parámetro access_token, que es el que utilizaremos para identificarnos, y otro expires_in, que nos informa de que el token de acceso no va a caducar.

Para comprobar que todo funciona correctamente puedes intentar cargar la siguiente URL:

https://graph.facebook.com/me?access_token=ACCESS_TOKEN

Si el token de acceso es el adecuado, Facebook nos mostrará un objeto JSON con la información de nuestra cuenta de usuario. En caso contrario, mostrará un objeto JSON informando del error.

Ahora bien, si queremos interactuar con las páginas de marca que administremos, en lugar de con nuestra página personal, necesitaremos un access token distinto. Para obtenerlo preguntaremos a Facebook por la información de las distintas páginas y aplicaciones que administramos utilizando la URL:

https://graph.facebook.com/me/accounts?access_token=ACCESS_TOKEN

Listo. Ahora sí, ya estamos preparados para empezar a jugar con la API de Facebook. Para publicar en el muro, crear eventos y subir imágenes en Facebook utilizaremos la clase del mismo nombre, a cuyo constructor le pasamos un array con el identificador de nuestra aplicación y su secreto:

$fb = new Facebook(array(
  'appId'  => 'ID_APP',
  'secret' => 'SECRETO',
  'cookie' => true
));

El método que nos interesa de esta clase es api, que normalmente tendrá como primer parámetro una cadena del tipo "/ID_USUARIO/SERVICIO" o "/ID_PAGINA/SERVICIO". El segundo parámetro es siempre el método a utilizar (POST o GET), y el tercero, un array con los argumentos necesarios para ese servicio.

Para publicar algo en el muro, por ejemplo, utilizaríamos como primer parámetro una cadena "/ID_USUARIO/feed" y como tercer parámetro, un array con claves message (el mensaje a publicar) y access_token, siendo este último el valor que obtuvimos anteriormente para identificar a nuestro usuario o alguna de las páginas de marca que administramos (OJO: el token de acceso del usuario no sirve para identificar a la página, evidentemente, y viceversa).

$fb = new Facebook(array(
  'appId'  => 'ID APLICACION',
  'secret' => 'SECRETO',
  'cookie' => true
));

$params = array(
    'access_token' => 'TOKEN ACCESO',
    'message' => 'Hola mundo'
);
$res = $fb->api('/ID_USUARIO/feed', 'POST', $params);
if(!$res)
    echo 'Ha ocurrido un error indeterminado';
elseif($res->error)
    echo "Ha ocurrido un error: {$res->error}";
else
    echo "OK";

Para terminar, os dejo una pequeña clase con la que podréis publicar en el muro, subir una imagen o crear un evento fácilmente:

<?php
require_once 'facebook.php';


/**
 * Clase para facilitar el trabajo con Facebook. Proporciona métodos para
 * publicar imágenes en un álbum, notas en el muro, y eventos
 *
 * Ejemplos de uso:
 * $fb = new Fb();
 * $fb->publicarNota('Prueba');
 * $fb->publicarImagen('/home/zootropo/html/imagenes/mi-imagen.jpg');
 * $fb-gt;publicarEvento('Prueba de evento', 'Descripción del evento', '2011-03-08');
 */
class Fb {
    const ID_APP = 'ID APLICACION';
    const SECRETO = 'SECRETO APLICACION';
    const ACCESS_TOKEN = 'TOKEN ACCESO';
    const ID_ALBUM = 'ID ALBUM';
    const ID_PAGINA = 'ID PAGINA';
    private $fb;

    /**
     * Constructor de la clase. Crea el objeto Facebook que utilizaremos
     * en los métodos que interactúan con la red social
     */
    function __construct() {
        $this->fb = new Facebook(array(
          'appId'  => self::ID_APP,
          'secret' => self::SECRETO,
          'cookie' => true
        ));
    }


    /**
     * Publica un evento
     * @param string $titulo Título del evento
     * @param string $descripcion Descripción del evento
     * @param string $inicio Fecha o fecha y hora de inicio del evento, en formato ISO-8601 o timestamp UNIX
     * @return bool Indica si la acción se llevó a cabo con éxito
     */
    function publicarEvento($titulo, $descripcion, $inicio) {
        $params = array(
            'access_token' => self::ACCESS_TOKEN,
            'name' => $titulo,
            'description' => $descripcion,
            'start_time' => $inicio,
        );
        $res = $this->fb->api('/'.self::ID_PAGINA.'/events', 'POST', $params);
        if(!$res or $res->error)
            return false;

        return true;
    }


    /**
     * Publica una nota en el muro de la página
     * @param string $mensaje
     * @return bool Indica si la acción se llevó a cabo con éxito
     */
    function publicarNota($mensaje) {
        $params = array(
            'access_token' => self::ACCESS_TOKEN,
            'message' => $mensaje
        );
        $res = $this->fb->api('/'.self::ID_PAGINA.'/feed', 'POST', $params);
        if(!$res or $res->error)
            return false;

        return true;
    }

    /**
     * Publica una imagen en el álbum de la página
     * @param string $ruta Ruta absoluta a la imagen en nuestro servidor
     * @param string $mensaje Mensaje a mostrar en el muro, si queremos avisar
     * de la subida de la imagen
     * @return bool Indica si la acción se llevó a cabo con éxito
     */
    function publicarImagen($ruta, $mensaje='') {
        $this->fb->setFileUploadSupport(true);

        $params = array(
            'access_token' => self::ACCESS_TOKEN,
            'source' => "@$ruta"
        );
        if($mensaje) $params['message'] = $mensaje;

        $res = $this->fb->api('/'.self::ID_ALBUM.'/photos', 'POST', $params);
        if(!$res or $res->error)
            return false;

        return true;
    }
}