Descripción general
Este documento te guiará a través de un ejemplo completo de cómo usar la API de Embed. Cuando termines, tendrás una aplicación similar a esta.
Crea un panel simple
Para ejecutar la aplicación de muestra en tu servidor, sigue estos 2 pasos sencillos:
- Crear un nuevo ID de cliente
- Copia y pega el código
Después de tener esta aplicación en funcionamiento, en la siguiente sección, se explicará en detalle cómo encajan todas las piezas.
Cómo crear un ID de cliente nuevo
La API de Embed controla casi todo el proceso de autorización por ti, ya que proporciona un componente de acceso con un clic que usa el flujo de OAuth 2.0 conocido. Para que este botón funcione en tu página, necesitarás un ID de cliente.
Si nunca creaste un ID de cliente, sigue estas instrucciones para hacerlo.
A medida que sigas las instrucciones, es importante que no pases por alto estos dos pasos fundamentales:
- Habilita la API de Analytics
- Establece los orígenes correctos
Los orígenes controlan qué dominios pueden usar este código para autorizar a los usuarios. Esto evita que otras personas copien tu código y lo ejecuten en su sitio.
Por ejemplo, si tu sitio web está alojado en el dominio example.com, asegúrate de configurar el siguiente origen para tu ID de cliente http://example.com. Si deseas probar tu código de forma local, también deberás agregar el origen de tu servidor local, por ejemplo: http://localhost:8080.
Copia y pega el código
Una vez que tengas tu ID de cliente con los orígenes adecuados, podrás crear la demostración. Simplemente copia y pega el siguiente código en un archivo HTML en el complemento de tu servidor; añade tu ID de cliente donde dice: "Inserta tu ID de cliente aquí".
<!DOCTYPE html>
<html>
<head>
<title>Embed API Demo</title>
</head>
<body>
<!-- Step 1: Create the containing elements. -->
<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>
<!-- Step 2: Load the library. -->
<script>
(function(w,d,s,g,js,fjs){
g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
js.src='https://apis.google.com/js/platform.js';
fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>
<script>
gapi.analytics.ready(function() {
// Step 3: Authorize the user.
var CLIENT_ID = 'Insert your client ID here';
gapi.analytics.auth.authorize({
container: 'auth-button',
clientid: CLIENT_ID,
});
// Step 4: Create the view selector.
var viewSelector = new gapi.analytics.ViewSelector({
container: 'view-selector'
});
// Step 5: Create the timeline chart.
var timeline = new gapi.analytics.googleCharts.DataChart({
reportType: 'ga',
query: {
'dimensions': 'ga:date',
'metrics': 'ga:sessions',
'start-date': '30daysAgo',
'end-date': 'yesterday',
},
chart: {
type: 'LINE',
container: 'timeline'
}
});
// Step 6: Hook up the components to work together.
gapi.analytics.auth.on('success', function(response) {
viewSelector.execute();
});
viewSelector.on('change', function(ids) {
var newIds = {
query: {
ids: ids
}
}
timeline.set(newIds).execute();
});
});
</script>
</body>
</html>
Explicación del código
En esta sección, se explica, paso a paso, exactamente lo que sucede en el código proporcionado para la aplicación de muestra. Una vez que comprendas cómo funciona, deberías poder crear el tuyo propio.
Paso 1: Crea los contenedores de componentes
La mayoría de los componentes de la API de Embed renderizarán algo visualmente en tu página. La forma de controlar dónde van esos componentes es creando contenedores para ellos. En la aplicación de ejemplo, tenemos un botón de autenticación, un selector de vistas y un gráfico. Cada uno de estos componentes se renderiza dentro de los siguientes elementos HTML:
<section id="auth-button"></section> <section id="view-selector"></section> <section id="timeline"></section>
Cuando creas un componente, le indicas qué contenedor usar mediante su atributo de ID, como verás en los ejemplos posteriores.
Paso 2: Carga la biblioteca
La API de Embed se puede cargar con el siguiente fragmento.
<script>
(function(w,d,s,g,js,fjs){
g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
js.src='https://apis.google.com/js/platform.js';
fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>
Cuando la biblioteca esté completamente cargada, se invocarán las devoluciones de llamada que se pasen a gapi.analytics.ready.
<script>
gapi.analytics.ready(function() {
// Put your application code here...
});
</script>
Paso 3: Autoriza al usuario
La API de Embed controla casi todo el proceso de autorización por ti, ya que proporciona un componente de acceso con un clic que usa el flujo conocido de OAuth 2.0. Para que este botón funcione en tu página, debes pasar una referencia del contenedor y tu ID de cliente.
gapi.analytics.auth.authorize({
container: 'auth-button',
clientid: CLIENT_ID,
});
Esto generará un botón dentro del elemento con el ID "auth-button" que se encarga del flujo de autorización por ti.
Paso 4: Crea el selector de vistas
El componente del selector de vistas se puede utilizar para obtener los IDs de una vista en particular, de modo que puedas ejecutar un informe para ella.
Para crear un selector de vistas, todo lo que necesitas es la referencia del contenedor que creaste en el paso 1.
var viewSelector = new gapi.analytics.ViewSelector({
container: 'view-selector'
});
Esto crea el componente del selector de vistas, pero aún no lo renderiza en la página. Para ello, debes llamar a execute(), que se procesa en el paso 6.
Paso 5: Crea el gráfico de cronograma
La API de Embed te proporciona un componente de gráfico que es un gráfico de Google y un objeto de informe en uno. Esto simplifica mucho el proceso de mostrar datos, ya que el objeto de gráfico ejecutará tus informes en segundo plano y se actualizará automáticamente con los resultados.
Para crear un componente de gráfico, deberás especificar los parámetros de consulta de la API y las opciones del gráfico. Dentro de las opciones del gráfico, hay una referencia al ID del contenedor que creaste en el paso 1.
var timeline = new gapi.analytics.googleCharts.DataChart({
reportType: 'ga',
query: {
'dimensions': 'ga:date',
'metrics': 'ga:sessions',
'start-date': '30daysAgo',
'end-date': 'yesterday',
},
chart: {
type: 'LINE',
container: 'timeline'
}
});
Al igual que con el selector de vistas, se crea el componente del gráfico, pero para renderizarlo en la página, debes llamar a execute(), que se explicará en el siguiente paso.
Paso 6: Conecta los componentes para que funcionen juntos
Los componentes de la API de Embed emiten eventos cuando ocurren varias situaciones, como una autorización exitosa, la selección de una vista nueva o un gráfico que se renderiza por completo.
La aplicación de ejemplo de esta guía espera procesar el selector de vistas hasta que se haya autorizado y actualiza el gráfico de cronograma cada vez que se selecciona una vista nueva en el selector de vistas.
gapi.analytics.auth.on('success', function(response) {
viewSelector.execute();
});
viewSelector.on('change', function(ids) {
var newIds = {
query: {
ids: ids
}
}
timeline.set(newIds).execute();
});
Para obtener una lista completa de todos los eventos que emiten los distintos componentes, consulta la referencia de la API.
Próximos pasos
En esta guía, se explicó cómo crear una visualización básica con la API de Embed. Si quieres obtener más información, consulta la referencia de la API para tener una idea completa de lo que puedes hacer.