Visão geral
Este documento o guiará por um exemplo completo de como usar a API Embed. Quando terminar, você terá um aplicativo parecido com este.
Criação de um painel simples
Você pode executar o aplicativo de exemplo no seu servidor seguindo estas duas etapas fáceis:
- Criar um novo ID de cliente
- Copiar e colar o código
Depois de executar esse aplicativo, você verá explicações detalhadas sobre como cada parte funciona em conjunto na próxima seção.
Criar um novo ID de cliente
A API de incorporação realiza quase todo o processo de autorização para você fornecendo um componente de inscrição com um clique que usa o familiar fluxo OAuth 2.0. Para fazer com que esse botão funcione na sua página, você precisa de um ID de cliente.
Caso nunca tenha criado um ID de cliente, siga estas instruções para criar um.
Ao seguir as instruções, é importante que você fique atento a estas duas etapas fundamentais
- Ative a Google Analytics API
- Defina as origens certas
As origens controlam quais domínios tem permissão para usar o código para autorizar usuários. Isso impede que outras pessoas copiem seu código e executem-no no seu site.
Por exemplo, se o site estiver hospedado no domínio example.com, defina a seguinte origem para o ID do cliente http://example.com. Caso queira testar seu código localmente, você
também vai precisar adicionar a origem do seu servidor local, por exemplo:
http://localhost:8080.
Copiar e colar o código
Depois de obter seu ID de cliente com o conjunto de origens apropriadas, estará pronto para criar a demonstração. Basta copiar e colar o código a seguir em um arquivo HTML do plug-in do servidor no seu ID de cliente, no lugar com a mensagem: "Insira seu ID de cliente aqui".
<!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>
Instruções sobre o código
Esta seção contém instruções passo a passo sobre o que acontece no código fornecido para o aplicativo de exemplo. Quando entender como ele funciona, você conseguirá criar seu próprio código.
Etapa 1: criar os contêineres de componente
A maioria dos componentes da API de incorporação renderiza algo visualmente na sua página. Crie contêineres para controlar onde esses componentes serão colocados. No aplicativo de exemplo, temos um botão Auth, um seletor de vista da propriedade e um gráfico. Cada um desses componentes é renderizado dentro dos seguintes elementos HTML:
<section id="auth-button"></section> <section id="view-selector"></section> <section id="timeline"></section>
Ao criar um componente, você informa qual contêiner usar pelo seu atributo de ID, como verá nos exemplos posteriores.
Etapa 2: carregar a biblioteca
A API de incorporação podem ser carregadas com o snippet a seguir.
<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>
Quando a biblioteca estiver totalmente carregada, todos os callbacks transmitidos para
gapi.analytics.ready serão invocados.
<script>
gapi.analytics.ready(function() {
// Put your application code here...
});
</script>
Etapa 3: autorizar o usuário
A API de incorporação comanda quase todo o processo de autorização para você fornecendo um componente de login com um clique que usa o fluxo familiar de OAuth 2.0. Para que esse botão funcione na sua página, você precisará passar uma referência de contêiner e seu ID de cliente.
gapi.analytics.auth.authorize({
container: 'auth-button',
clientid: CLIENT_ID,
});
Isso gerará um botão dentro do elemento com o ID "auth-button" que lidará com o fluxo de autorização para você.
Etapa 4: criar o seletor de vista da propriedade
O componente do seletor de vista da propriedade pode ser usado para obter os IDs de uma determinada vista da propriedade. Dessa forma, você pode gerar um relatório para ela.
Para criar um seletor de vista da propriedade, você só precisa da referência de contêiner que criou na Etapa 1.
var viewSelector = new gapi.analytics.ViewSelector({
container: 'view-selector'
});
Isso cria o componente do seletor de vista da propriedade, mas não ainda não o renderiza na página. Para fazer isso, chame execute(), como descrito na etapa 6.
Etapa 5: criar o gráfico de linha do tempo
A API de incorporação fornece a você um componente gráfico que é tanto um gráfico do Google quanto um objeto de relatório ao mesmo tempo. Isso simplifica muito o processo de exibir dados, pois o objeto de gráfico executa seus relatórios nos bastidores e se atualiza automaticamente com os resultados.
Para criar um componente de gráfico, você precisa especificar os parâmetros de consulta da API, bem como as opções de gráfico. Dentre as opções de gráfico está uma referência ao ID do contêiner que você criou na Etapa 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'
}
});
Assim como o seletor de vista da propriedade, isso cria o componente de gráfico, mas para renderizá-lo na página que você precisa chamar execute(), o que será explicado na próxima etapa.
Etapa 6: combinar os componentes para funcionar juntos
A API de incorporação emite eventos quando acontecem várias ações, como autorização, seleção de uma nova vista da propriedade ou a renderização de uma gráfico.
O aplicativo de exemplo presente neste guia espera para renderizar o seletor de vista da propriedade até depois de a autorização acontecer, além de atualizar o gráfico de linha do tempo sempre que uma nova vista da propriedade é selecionado pelo seletor.
gapi.analytics.auth.on('success', function(response) {
viewSelector.execute();
});
viewSelector.on('change', function(ids) {
var newIds = {
query: {
ids: ids
}
}
timeline.set(newIds).execute();
});
Para uma lista completa de todos os eventos que os vários componentes emitem, configura a Referência da API.
Próximas etapas
Este guia mostrou como criar uma visualização básica com a API de incorporação. Se quiser saber mais, confira a Referência da API para ter uma noção completa do que é possível.