Built-in Components Reference

This document describes the options, methods, properties, and events for all built-in Embed API components.

auth

gapi.analytics.auth

The auth component is a singleton that can be used to authorize a user.

Methods

authorize(options:Object)

Returns:  gapi.analytics.auth

Renders a Google Analytics sign-in button inside the specified container allowing the user to sign in with their Google account.

isAuthorized()

Returns:  boolean

Returns true if the user has successfully authorized, false otherwise.

signOut()

Returns:  gapi.analytics.auth

Signs the current user out. Also triggers the signOut event.

getAuthResponse()

Returns:  Object

Gets authentication data returned by the original authorization request. The returned object includes the access token, which can be usually to manually make authenticated requests.

getUserProfile()

Returns:  Object

Gets basic profile information about the currently signed-in user. This includes the user's name, email address, and public profile image (if set).

Inherited methods

on
once
off

Options

clientId

Type:  string

The client ID of your project in the developers console.

container

Type:  string|HTMLElement

The ID of an HTML element in the DOM that will host the sign-in button. You may also pass a reference to the element itself.

userInfoLabel

Type:  string

The text to display before a logged in user's email address. Defaults to 'You are logged in as: '.

scopes

Type:  Array

A list of Google API auth scopes that your application is requesting. To see all available scopes, visit the OAuth 2.0 Playground. For Google Analytics API auth scopes see the developer guides for Configuration and Reporting resources.

overwriteDefaultScopes

Type:  boolean

Indicates whether the scopes option replaces the default Embed API scopes or adds to them. Specifying false (the default) will add to the default scopes, and specifying true will replace them with the ones specified by the scopes option.

The default scopes value is:['https://www.googleapis.com/auth/analytics.readonly'].

Note: authenticating via the Embed API requires access to the user's basic profile. Those scopes cannot be overwritten.

serverAuth.access_token

Type:  string

If you already have a valid access token, you can pass it to the authorize method directly and the user will not be prompted to authorize. For details on how to retrieve an access token, see the OAuth 2.0 documentation.

Events

signIn

Arguments:  None

Fired when the user has successfully signed in.

signOut

Arguments:  None

Fired when the user has successfully signed out.

needsAuthorization

Arguments:  None

When invoking the gapi.analytics.auth.authorize method, an initial check is made to see if the user is currently signed in. If the user is not signed in, this event is fired to indicate that further authorization is required.

error

Arguments:  response

Fired when an error occurs during the authentication process. If you want to get the error message from the response object it will be at response.error.message.

Deprecated events
success

Arguments:  response

This event exists for backwards compatibility and may be removed in a future version. Use the signIn event instead.

Example

// 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'
  }
});

Data

gapi.analytics.report.Data
Constructor
Data(options:Object) The Data component allows you to query the Google Analytics Core Reporting API and get back the results.

Options

query

Type:  Object

An object containing query parameters from the Core Reporting API. The following default values are used in addition to the regular defaults provided by the API:

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

Inherited methods

get
set
execute
on
once
off
emit

Events

success

Arguments:  response

Fired when the query has successfully completed.

error

Arguments:  response

Fired when an error occurs during the query process. If you want to get the error message from the response object it will be at response.error.message.

Example

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
Constructor
DataChart(options:Object) DataChart wraps a standard Google chart and a Data component so you can easily create a visualization from a query without having to wire it together yourself.

Options

query

Type:  Object

See the data component query option.

chart

Type:  Object

See below for individual chart option details.

chart.container

Type:  string|HTMLElement

The ID of an HTML element in the DOM that will host the DataChart. You may also pass a reference to the element itself.

chart.type

Type:  string

The chart type. Possible options are: LINE, COLUMN, BAR, TABLE, and GEO.

chart.options

Type:  Object

Any options that can be passed to the corresponding Google Chart object.

Inherited methods

get
set
execute
on
once
off
emit

Events

success

Arguments:  result

Fired when the query has successfully completed and the chart has fully rendered.

  • result.chart – the Google Chart instance.
  • result.data – the report response in data parameter format.
  • result.dataTable – the DataTable instance created from the result.data object.
  • result.response – the raw API response object.
error

Arguments:  response

Fired when an error occurs during the query or rendering process. If you want to get the error message from the response object it will be at response.error.message.

Example

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
Constructor
ViewSelector(options:Object) The ViewSelector component allows you to choose your account, property, and view via dropdown menus.

Options

container

Type:  string|HTMLElement

The ID of an HTML element in the DOM that will host the ViewSelector. You may also pass a reference to the element itself.

Inherited methods

get
set
execute
on
once
off
emit

Instance properties

ids

Type:  string

The unique table ID of the form ga:XXXX, where XXXX is the Analytics view (profile) ID.

Events

change

Arguments:  ids

Fired any time the user selects a new view from the dropdown menus. It is also fired when the ViewSelector instance is first rendered and the default view is displayed.

Example

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

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

viewSelector.execute();

Shared Component Methods

Methods
set(options)

returns: this

Sets or updates the component's configuration options (this can also be done at creation time in the constructor).

get()

returns: Object

Returns the current configuration options of a component.

execute()

returns: this

Invokes the component's primary action. This is usually rendering something on the page or running a report (or both).

on(event, handler)

returns: this

Registers a function to be invoked when the component emits the specified event.

once(event, handler)

returns: this

Registers a function to be invoked at only the next occurrence of the specified event. After the handler runs once it automatically unregisters itself.

off(opt_event, opt_handler)

returns: undefined

Removes an event handler from a component. If no handler is passed, it removes all handlers for the passed event. If no event is passed, it removes all handlers for all events.

emit(event, ...opt_args)

returns: undefined

Emits an event. You may optionally specify the arguments to be passed to any registered handlers.

set

Sets or updates the component's configuration options (this can also be done at creation time in the constructor).

Usage

component.set(options);

Parameters

Name Type Description
options Object The configuration options for this component. Passed options will be merged with existing options.

Returns

this – The component instance.


get

Returns the current configuration options of a component.

Returns

Object – The component's current configuration options.


execute()

Invokes the component's primary action. This is usually rendering something on the page or running a report (or both).

Returns

this – The component instance.


on(event, handler)

Registers a function to be invoked when the component emits the specified event.

Parameters

Name Type Description
event string The name of the event.
handler Function The function to be invoked when the event occurs. (See individual event references for parameter details.)

Returns

this – The component instance.


once(event, handler)

Registers a function to be invoked at only the next occurrence of the specified event. After the handler runs once it automatically unregisters itself.

Parameters

Name Type Description
event string The name of the event.
handler Function The function to be invoked when the event occurs. (See individual event references for parameter details.)

Returns

this – The component instance.


off(opt_event, opt_handler)

Removes an event handler from a component. If no handler is passed, it removes all handlers for the passed event. If no event is passed, it removes all handlers for all events.

Parameters

Name Type Description
opt_event string The name of the event. If no event is specified, all handlers for all events are removed. Optional.
opt_handler Function A reference to the function handler to be removed. If no function is passed, all handlers are removed. Optional.

Returns

undefined


emit(event, ...opt_args)

Emits an event. You may optionally specify the arguments to be passed to any registered handlers.

Parameters

Name Type Description
event string The name of the event.
...opt_args * Optional arguments to be passed to any registered event handlers.

Returns

undefined