Referência de componentes incorporados

Este documento descreve opções, métodos, propriedades e eventos de todos os componentes da API de incorporação.

auth

gapi.analytics.auth

O componente "auth" é um singleton que pode ser utilizado para autorizar um usuário.

Métodos
authorize(options:Object)

Retorna:  gapi.analytics.auth

Renderiza um botão de login do Google Analytics no contêiner especificado, permitindo que o usuário faça login com a Conta do Google dele.
isAuthorized()

Retorna:  boolean

Retorna true se o usuário autorizou. Caso contrário, retorna false.
signOut()

Retorna:  gapi.analytics.auth

Desconecta o usuário atual. Também aciona o evento signOut.
getAuthResponse()

Retorna:  Object

Recebe os dados de autenticação retornados pela solicitação de autorização original. O objeto retornado inclui o token de acesso, que geralmente é usado para fazer solicitações autenticadas manualmente.
getUserProfile()

Retorna:  Object

Exibe informações básicas do perfil do usuário atualmente conectado. Isso inclui o nome, endereço de e-mail e a imagem de perfil pública (se definida) do usuário.

Métodos herdados
on
once
off

Opções
clientId

Tipo:  string

O ID de cliente do seu projeto no Developers Console.
container

Tipo:  string|HTMLElement

O ID de um elemento HTML no DOM que hospedará o botão de login. Você também pode passar uma referência ao próprio elemento.
userInfoLabel

Tipo:  string

O texto a ser exibido antes do endereço de e-mail de um usuário conectado. O valor padrão é 'You are logged in as: '.
scopes

Tipo:  Array

Uma lista de escopos do componente "auth" da API do Google que seu aplicativo está solicitando. Para ver todos os escopos disponíveis, acesse o OAuth 2.0 Playground. Para os escopos do tipo "auth" da API Google Analytics, consulte os guias do desenvolvedor sobre recursos de configuração e relatórios.
overwriteDefaultScopes

Tipo:  boolean

Indica se a opção scopes substitui os escopos padrão da API de incorporação ou os adiciona a eles. Especificar false (o padrão) complementa os escopos padrão e true os substitui pelos especificados pela opção scopes.

O valor de escopos padrão é:['https://www.googleapis.com/auth/analytics.readonly'].

Observação: a autenticação pela API de incorporação exige acesso ao perfil básico do usuário. Não é possível substituir esses escopos.
serverAuth.access_token

Tipo:  string

Se você já tem um token de acesso válido, pode passá-lo diretamente para o método de autorização, e usuário não recebe uma solicitação de autorização. Para detalhes sobre como recuperar um token de acesso, consulte a Documentação do OAuth 2.0.

Eventos
signIn

Argumentos:  nenhum

Disparado quando o usuário faz login na conta.
signOut

Argumentos:  nenhum

Disparado quando o usuário sai da conta.
needsAuthorization

Argumentos:  nenhum

Ao invocar o método gapi.analytics.auth.authorize, uma verificação inicial é feita para ver se o usuário está conectado no momento. Se o usuário não estiver conectado, esse evento é disparado para indicar que mais autorizações são necessárias.
error

Argumentos:  response

Disparado quando ocorre um erro durante o processo de autenticação. Se você quiser receber a mensagem de erro do objeto de resposta, ela estará em response.error.message.
Eventos suspensos
success

Argumentos:  response

Esse evento existe para compatibilidade retroativa e poderá ser removido em uma versão futura. Use o evento signIn.

Exemplo

// Standard client-side authorization.

gapi.analytics.auth.authorize({
  clientId: 'XXXXXX',
  container: 'auth-button'
});

gapi.analytics.auth.on('signIn', function() {
  console.log(gapi.analytics.auth.getUserProfile());
});

// Authorization using an access token obtained server-side.
// You do not need to register an event handler because
// authorization happens immediately.

gapi.analytics.auth.authorize({
  serverAuth: {
    access_token: 'XXXXXX'
  }
});

Dados

gapi.analytics.report.Data
Construtor
Data(options:Object) Com o componente de dados, é possível consultar a API de relatórios principais do Google Analytics e receber os resultados.

Opções
query

Tipo:  Object

Um objeto que contém parâmetros de consulta da API de relatórios principais. Os valores padrão a seguir são usados além dos padrões normais fornecidos pela API:

{
  'start-date': '7daysAgo',
  'end-date': 'yesterday
}

Métodos herdados
get
set
execute
on
once
off
emit

Eventos
success

Argumentos:  response

Disparado quando a consulta é concluída.
error

Argumentos:  response

Disparado quando ocorre um erro durante o processo de consulta. Se você quiser receber a mensagem de erro do objeto de resposta, ela estará em response.error.message.

Exemplo

var report = new gapi.analytics.report.Data({
  query: {
    ids: 'ga:XXXX',
    metrics: 'ga:sessions',
    dimensions: 'ga:city'
  }
});

report.on('success', function(response) {
  console.log(response);
});

report.execute();

DataChart

gapi.analytics.googleCharts.DataChart
Construtor
DataChart(options:Object) A função DataChart envolve um gráfico padrão do Google e um componente de dados para que você crie facilmente uma visualização a partir de uma consulta sem precisar fazer a ligação por conta própria.

Opções
query

Tipo:  Object

Veja a opção de consulta de componente de dados.
chart

Tipo:  Object

Veja abaixo os detalhes das opções de gráficos individuais.
chart.container

Tipo:  string|HTMLElement

O ID de um elemento HTML no DOM que hospedará o "DataChart". Você também pode passar uma referência ao próprio elemento.
chart.type

Tipo:  string

O tipo de gráfico. As opções possíveis são: LINE, COLUMN, BAR, TABLE e GEO.
chart.options

Tipo:  Object

Qualquer opção que pode ser passados para o objeto de gráfico do Google correspondente.

Métodos herdados
get
set
execute
on
once
off
emit

Eventos
success

Argumentos:  result

Disparado quando a consulta é concluída e o gráfico é totalmente processado.

  • result.chart: a instância de gráfico do Google.
  • result.data: a resposta do relatório no formato de parâmetro de dados.
  • result.dataTable: a instância DataTable criada a partir do objeto result.data.
  • result.response: o objeto de resposta bruto da API.
error

Argumentos:  response

Disparado quando ocorre um erro durante o andamento de uma consulta ou um processamento. Se você quiser receber a mensagem de erro do objeto de resposta, ela estará em response.error.message.

Exemplo

var chart = new gapi.analytics.googleCharts.DataChart({
  query: {
    ids: 'ga:XXXX',
    metrics: 'ga:sessions',
    dimensions: 'ga:date'
  },
  chart: {
    type: 'LINE',
    container: 'line-chart',
    options: {
      title: 'Sessions over the past week.',
      fontSize: 12
    }
  }
});
chart.on('success', function(response) {
  // response.chart : the Google Chart instance.
  // response.data : the Google Chart data object.
});

chart.execute();

ViewSelector

gapi.analytics.ViewSelector
Construtor
ViewSelector(options:Object) Com o componente ViewSelector, é possível escolher sua conta, propriedade e vista usando menus suspensos.

Opções
container

Tipo:  string|HTMLElement

O ID de um elemento HTML no DOM que hospedará o "ViewSelector". Você também pode passar uma referência ao próprio elemento.

Métodos herdados
get
set
execute
on
once
off
emit

Propriedades da instância
ids

Tipo:  string

O ID único da tabela no formato ga:XXXX, em que XXXX é o ID da vista da propriedade (perfil) do Google Analytics.

Eventos
change

Argumentos:  ids

Disparado todas as vezes que o usuário seleciona uma nova vista da propriedade nos menus suspensos. Também é acionado quando a instância "ViewSelector" é processada pela primeira vez e a vista da propriedade padrão é exibida.

Exemplo

var viewSelector = new gapi.analytics.ViewSelector({
  container: 'view-selector'
});

viewSelector.on('change', function(ids) {
  console.log(ids);
});

viewSelector.execute();

Métodos de componentes compartilhados

Métodos
set(options)

Retorna: this

Define ou atualiza as opções de configuração do componente. Isso também pode ser feito no momento da criação, no construtor.

get()

Retorna: Object

Retorna as opções de configuração atuais de um componente.

execute()

Retorna: this

Invoca a ação principal do componente, que geralmente é o processamento de algo na página ou a geração de um relatório (ou ambos).

on(event, handler)

Retorna: this

Registra uma função que será invocada quando o componente emitir o evento especificado.

once(event, handler)

Retorna: this

Registra uma função que será invocada apenas na próxima ocorrência do evento especificado. Depois que o manipulador é executado uma vez, ele cancela o próprio registro automaticamente.

off(opt_event, opt_handler)

Retorna: undefined

Remove um manipulador de eventos de um componente. Se nenhum manipulador é passado, esse método remove todos os manipuladores do evento passado. Se nenhum evento é passado, ele remove todos os manipuladores de todos os eventos.

emit(event, ...opt_args)

Retorna: undefined

Emite um evento. Como alternativa, você pode especificar os argumentos que serão passados para quaisquer manipuladores registrados.

set

Define ou atualiza as opções de configuração do componente. Isso também pode ser feito no momento da criação, no construtor.

Uso

component.set(options);

Parâmetros

Nome Tipo Descrição
options Object As opções de configuração desse componente. As opções passadas serão mescladas com as existentes.

Retorna

this: a instância do componente.

get

Retorna as opções de configuração atuais de um componente.

Retorna

Object: as opções de configuração atuais do componente.

execute()

Invoca a ação principal do componente, que geralmente é o processamento de algo na página ou a geração de um relatório (ou ambos).

Retorna

this: a instância do componente.

on(event, handler)

Registra uma função que será invocada quando o componente emitir o evento especificado.

Parâmetros

Nome Tipo Descrição
event string O nome do evento.
handler Function A função a ser invocada quando o evento ocorrer. Veja referências de eventos individuais para detalhes de parâmetros.

Retorna

this: a instância do componente.

once(event, handler)

Registra uma função que será invocada apenas na próxima ocorrência do evento especificado. Depois que o manipulador é executado uma vez, esse método cancela seu registro automaticamente.

Parâmetros

Nome Tipo Descrição
event string O nome do evento.
handler Function A função a ser invocada quando o evento ocorrer. Veja referências de eventos individuais para detalhes de parâmetros.

Retorna

this: a instância do componente.

off(opt_event, opt_handler)

Remove um manipulador de eventos de um componente. Se nenhum manipulador é passado, esse método remove todos os manipuladores do evento passado. Se nenhum evento é passado, ele remove todos os manipuladores de todos os eventos.

Parâmetros

Nome Tipo Descrição
opt_event string O nome do evento. Se nenhum evento é especificado, todos os manipuladores de todos os eventos são removidos. Opcional.
opt_handler Function Uma referência para o manipulador de função a ser removido. Se nenhuma função é passada, todos os manipuladores são removidos. Opcional.

Retorna

undefined

emit(event, ...opt_args)

Emite um evento. Como alternativa, você pode especificar os argumentos que serão passados para quaisquer manipuladores registrados.

Parâmetros

Nome Tipo Descrição
event string O nome do evento.
...opt_args * Argumentos opcionais a serem passados para quaisquer manipuladores de eventos registrados.

Retorna

undefined