Estos días he vivido una pequeña crisis interna. Resulta que las primeras versiones de la API de analytics «La Data Export API» han quedado obsoletas y por lo tanto todos los scripts que solía usar (que estaban basados en esa API) simplemente han dejado de funcionar.

¿Qué hacer? Lo suyo sería haber sido precavido, seguir los blogs de Google con cuidado y haber previsto esta caducidad, pero ahora el daño ya está hecho: tengo que actualizar la forma de sacar los datos de Analytics.

Google nos brinda distintas versiones para sus APIs pero la ultima de ellas ha significado un auténtico cambio en muchos conceptos. Ya no se trata simplemente de crear un script de conexión y sacar los datos, ahora hay que seguir un proceso bastante cerrado (algo que los amantes de la seguridad aplaudirán) para simplemente conectase a esa API.

Lo bueno es que Google en esta nueva versión a estandarizado muchas APIs y ya nos brinda para distintos lenguajes de programación una librería propia de conexión a sus APIs. Esto implica que a la que conseguimos conectarnos a una de sus APIs con sus librerías no solo hemos conseguido esta conexión, sino que el resto de servicios de Google nos van a quedar mucho más cerca para otras integraciones. Lo malo de todo esto es que la librería PHP es de las últimas que han salido y que la documentación actual se centra en conexiones mediante OAuth 2.0, algo que tiene mucho sentido para crear aplicaciones web pero poco para lo que solemos hacer en analítica, que es recoger por servidor los datos sin que medie usuario alguno en este proceso.

Dicho esto, ya veis de que va este post. El trabajo ya está hecho, ya puedo conectarme mediante la API V3 a analytics y por lo tanto solo me queda explicaros el proceso (aun un poco largo) a los que aun no hayáis pasado por este mal trago.

Vamos a conectarnos a analytics con PHP mediante las propias librerías de google…

Primer paso: Google APIs Console

Este nuevo sistema es necesario gestionarlo desde un entorno que Google ha puesto a nuestra disposición para gestionar nuestras conexiones a sus APIs. Se trata de un gran avance pues nos permite ver que estamos usando, nuestros códigos de acceso, bajarnos sus librerías y las cuotas de datos que estamos gastando (recordemos que tras cierto límite Google cobra por el acceso a sus datos, en analytics no será un problema pero en otros servicios si).

• Acceso a Google APIs Console

Configuración en la Google APIs Console

Una vez nos identificamos con nuestra cuenta de Google o la de la empresa pasamos a ver el menú de opciones de la Google APIs Console:

Clickando en el primer elemento podremos editar nuestro proyecto de APIs, un concepto que es algo asi como un contenedor de integraciones con un mismo proposito o de una misma empresa.

Una vez tenemos claro nuestro proyecto, que salvo que usemos un usuario de una agencia pocas veces será más de uno, podemos ir al panel de servicios y activar aquellos que deseemos utilizar. En este caso Google Analytics.

Este paso es importante, sin activar el servicio, no podremos conectarnos a la API V3.

Una vez lo tenemos activo, por fin es el momento de entrar en API Access y configurar nuestro acceso a las APIs (que recordemos que es común).

Aquí encontraremos 2 tipos de acceso: «Authorized» y «Simple». Nosotros vamos a usar el acceso Authorized que es el que usan las librerías de Google. El Simple es implemente una clave que añadir a las peticiones en otras versiones de la API y por lo tanto no nos interesa.

Clickaremos en crear un nuevo «Client ID» y nos dará varias opciones para conectarnos:

• «Web Application» nos permite crear el típico acceso OAuth 2.0 estilo Facebook o Twitter con petición de permisos. Resulta ideal para crear aplicaciones web basadas en Analytics.
• «Service Account» está creado para una conexión mediante servidor sin mediación de los usuarios
• Por último «Installed Applications» está destinado a crear programas de escritorio donde el OAuth no puede ser exactamente igual al web

Por supuesto, la conexión que a nosotros nos interesará para importar datos de google analytics con php es la de «Service Account». Al seleccionarla se creará la nueva conexión pero también (por el funcionamiento de la misma) se nos ofrecerá un fichero llave a descargar. Este fichero es el que almacena nuestra identificación mediante este canal, por lo que es necesario bajárselo y guardarlo en un lugar seguro (donde nadie más tenga acceso y donde no podamos perderlo).

Una vez hecho esto, nuestra conexión esta lista. Ya disponemos de todos los datos para realizar el acceso con PHP mediante la API V3 de Analytics.

Dando acceso a esta nueva conexión a nuestra cuenta de Google Analytics

Sin embargo, no hemos terminado de configurar el acceso. La conexión está habilitada y podemos identificarnos en ella pero esta no va a tener acceso a las cuentas de analytics si no se lo damos.

Para ello, si miráis en la imagen superior veréis que la conexión nos ha creado un Email de identificación. Este email es el que va a realizar el acceso y por lo tanto tenemos que darle acceso a Analytics.

Para ello nada tan fácil como acceder a nuestra cuenta de Google Analytics, entrar en la administración y crear un nuevo usuario (normal, no es necesario que sea administrador) con ese Email.

Ahora sí, ya estamos listos para crear nuestro código.

Descargando la librería PHP

El código a utilizar lo encontraremos bien organizadito en el repositorio de Google Code:

• Acceder a Google Api PHP Client

Este nos brida la descarga de las librerías PHP para conectarnos a la API de Analytics (y a tantas otras) al tiempo que nos brinda una documentación bastante decente sobre como usarla.

El problema de todo esto es que tanto la descarga ofrecida como la documentación que ahí encontramos están centradas en la conexión mediante OAuth 2.0. Eso significa que no encontraremos soporte para la conexión con un «Service Account» y mediante archivo llave.

Peor aún: a día de hoy (26 de Julio de 2012) la descarga ofrecida en esta página no contiene las funciones necesarias para usar el archivo llave que nos hemos descargado. Es decir, hasta que no lo actualicen esta descarga no nos sirve pues no contiene las funciones que necesitamos.

Por lo tanto tenemos que decargarnos el proyecto mediante SVN (subversion), un protocolo que sirve para llevar un control de cambios en trabajos colaborativos y que necesita de herramientas especiales (como por ejemplo Tortoise SVN o Eclipse ) para realizar la descarga. Esto para un programador de PHP curtido no debería suponer ninguna complicación pero si puede ser problemático para programadores noveles o perfiles no tan técnicos que se asoman solo de vez en cuando a la programación.

La dirección del SVN para realizar la descarga es la siguiente:

http://google-api-php-client.googlecode.com/svn/trunk/

Realizamos el Checkout (descarga) del proyecto y ya disponemos de un código con soporte para ficheros clave y con las mismas funcionalidades que el resto del código de google (simplemente una versión un poco más actualizada).

¿Como comprobar si tu versión de google php api client es la buena?

Tenemos que abrir el archivo «auth/apiP12Signer.php»

Y encontrar en la clase la siguiente línea:

if (!openssl_sign($data, $signature, $this->privateKey, "sha256")) {
 

Conectándonos por PHP

Ya tenemos la consola configurada, nuestra conexión creada, el email de la conexión como usuario de analytics y la librería con soporte para ficheros llave. Ya solo nos queda conectarnos…

• Nos ubicaremos en la carpeta que deseemos de nuestro servidor y copiaremos la carpeta de «google-api» dentro de esta.
• Dentro de la carpeta «google-api» o donde deseemos (lo suyo sería un lugar no accesible desde internet) copairemos nuestro fichero llave. El que descargamos anteriormente de la consola
• Ahora crearemos un fichero php con el código necesario para realizar la conexión…

Para ello simplemente os dejo una muestra del código a usar comentado que creo que será suficiente para la mayor parte de vosotros:

// Los includes de la librería google-api son relativos, por lo que si no programamos
// en la misma carpeta de la libería no funcionarían.
// Solución: Cambiarmos la carpeta a partir de la que se hacen los includes en php con chdir()
chdir('/var/www/mi-ruta-absoluta-hasta-la-carpeta-de-la-clase/class/google-api');

// incluimos la libería base y el módulo de Analytics
include('apiClient.php');
include('contrib/apiAnalyticsService.php');

// Declaramos nuestra configuración 
$googleApi = array(
	'id' => '803005xxxxxxxxxxxxxxxxx.apps.googleusercontent.com', // Id que nos ha dado la APIs Console
	'email' => '[email protected]', // email que nos ha dado la APIs Console
	'keyFile' => 'e6a8753xxxxxxxxxxxxxxxxxxx-privatekey.p12', // nombre del fichero llave
	'gaAccount' => 123456 // id de la cuenta de analytics a la que nos conectamos
); 

// Creamos el cliente de conexión
$client = new apiClient();
$client->setApplicationName('blog.ikhuerta.com-analytics-sample');
$client->setAssertionCredentials(
	new apiAssertionCredentials(
		$googleApi['email'],
		array('https://www.googleapis.com/auth/analytics.readonly'),
		file_get_contents($googleApi['keyFile'])
	)
);
$client->setClientId($googleApi['id']);
$client->setAccessType('offline_access');

// y con este cliente creamos el objeto para lanzar consultas a la API
$service = new apiAnalyticsService($client);

// ahora ya podemos realizar consultas de la forma acostumbrada
$results = $service->data_ga->get($googleApi['gaAccount'], '2012-01-01', '2012-02-01', 'ga:visits');

// imprimimos el resultado para verlo
var_dump($results);

Posibles problemas

Es posible que encuentres algunos errores en tu camino para conseguir esta conexión. Voy a enumerar los que cuentro más comunes:

• Los includes internos de la librería no se realizan correctamente: esto es porque son relativos. Google espera que añadamos la carpeta de su librería a nuestros PATH en el «php.ini». Esto resolverá el problema sin duda, pero lo veo excesivo si no vamos a dedicar un servidor completo a este tipo de conexiones. Otra solución es la comentada en este propio código. Usar chdir() para cambiar la ruta desde la que se hacen los includes. Sin emabrgo esto puede dar también problemas si hacemos nuestros propios includes relativos
• La llamada a a «openssl_sing» falla al autentificar el fichero llave: Este error lo podemos encontrar con un Warning con el texto «openssl_sign() expects parameter 4 to be long, string given». Este es un problema de la versión de PHP. Versiones por debajo de PHP5.3 no pueden trabajar la función openssl_sing() con «sha256» y por lo tanto fallan. Por desgracia Google Api no nos da solución ni hack para esto. Lo unico que podemos hacer para remediarlo es actualizar nuestro php a una versión php5.3 o superior.
• Permiso denegado: Un error que podemos identificar al ver el siguiente mensaje en pantalla: «Error refreshing the OAuth2 token, message: ‘{ «error» : «invalid_grant» }’». Este error viene a decir lo que parece: que no tenemos acceso. No es un problema del código o de PHP sino de los permisos que estamos usando: revisemos que los ids indicados son correctos, que se corresponden con el archivo llave y que el email que estamos dando sea un usuario de la cuenta de analytics a la que intentamos acceder

Funcionamiento de la llamada get() en el objeto de analytics

La librería es bastante sencilla pero no existe mucha documentación sobre la misma… la verdad es que viendo el código fuente de «contrib/apiAnalyticsService.php» se ven las posibilidades de la mayor parte de funciones y el escalado de clases para la administración pero la función get no explica demasiado sobre que hay que lanzar.

Sencillo, disponemos de 4 variables obligatorias a completar con un posible array con más datos.

1) $ids: los ids de cuentas de analytics que consultamos (con «ga:» al principio).
2 y 3) $start_date y $end_date: rango de fechas de la cosnulta.
4) $metrics: metricas que queremos consultar.

El resto de parametros a pasar por array son las posibles variables que se nos informan en la propia documentación de la API de Google Analytics:

• Ver lista de parámetros de las llamadas a la API V3 de Analytics

Así pues, cualquiera de estos parametros puede pasarse en el array opcional de valores. Un ejemplo: vamos a sacar las visitas y rebotes de las keywords y landings de nuestro site, pero solo contemplando el tráfico SEO:

// se supone que ya hemos creado el objeto $service de la forma anteriormente mencionada

$service->data_ga->get(
  $googleApi['gaAccount'], 
  '2012-01-01', 
  '2012-02-01', 
  'ga:visits,ga:bounces',
  array(
    'filter' => 'ga:medium==organic',
    'dimensions' => 'ga:keyword,ga:landingPagePath'
  )
);

Y como siempre, podemos sacar el listado de posibles métricas y dimensiones también de la documentación de la API de analytics:

• Acceso a las métricas y dimensiones de la API de analytics

El formato de los datos

El formato de vuelto no es el mismo que en pasadas versiones de la API. La verdad es que puede rompernos un poco los esquemas al hacer la migración pero la realidad es que el nuevo formato resulta mucho más útil y «trabajable» que el antiguo pues se centra en darte toda la información directamente como una tabla y añadirte campos con información sobre la misma. El paso de estas tablas a cualquier utilidad que quieras darle será más rápido que con el antiguo formato… por desgracia eso no se aplica tus viejos scripts que tendrán que reformularse para tratar los datos con el nuevo formato.

Conclusión

Como puedes ver, el proceso es mucho más largo y complejo que con las anteriores APIs pero creo que merece la pena el cambio (una vez lo has hecho). Tras todo este proceso tenemos ciertas ventajas que no hay que dejar de lado:

• Estaremos mucho más cerca de trabajar con el resto de apis de Google
• Disfrutaremos de un código mantenido y actualizado por Google
• Estaremos muchísimo más lejos de versiones caducadas de la API
• Disfrutaremos de un formato de los datos más manipulable
• Podremos identificarnos en el código sin dar acceso a nuestra cuenta real de analytics (usuario y password)
• Podremos revocar desde la consola cualquier acceso simplemente eliminando o cambiando su fichero clave
• Podremos ver nuestras estadísticas de uso en la consola
• Y seremos, una vez más, tiernos corderitos que hacemos las cosas solo como a Google le gusta

¿Qué? ¿os animáis?