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: Renders a Google Analytics sign-in button inside the specified container allowing the user to sign in with their Google account. |
isAuthorized() |
Returns: Returns |
signOut() |
Returns: Signs the current user out. Also triggers the |
getAuthResponse() |
Returns: 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: Gets basic profile information about the currently signed-in user. This includes the user's name, email address, and public profile image (if set). |
Options |
|
---|---|
clientId |
Type: The client ID of your project in the developers console. |
container |
Type: 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: The text to display before a logged in user's email address. Defaults to |
scopes |
Type: 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: Indicates whether the The default scopes value is: Note: authenticating via the Embed API requires access to the user's basic profile. Those scopes cannot be overwritten. |
serverAuth.access_token |
Type: 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 |
error |
Arguments: 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 |
Deprecated events | |
---|---|
success |
Arguments: This event exists for backwards compatibility and may be removed in a future version. Use the |
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: 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 } |
Events |
|
---|---|
success |
Arguments: Fired when the query has successfully completed. |
error |
Arguments: 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 |
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: See the data component query option. |
chart |
Type: See below for individual chart option details. |
chart.container |
Type: 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: The chart type. Possible options are: |
chart.options |
Type: Any options that can be passed to the corresponding Google Chart object. |
Events |
|
---|---|
success |
Arguments: Fired when the query has successfully completed and the chart has fully rendered.
|
error |
Arguments: 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 |
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: The ID of an HTML element in the DOM that will host the ViewSelector. You may also pass a reference to the element itself. |
Instance properties |
|
---|---|
ids |
Type: The unique table ID of the form ga:XXXX, where XXXX is the Analytics view (profile) ID. |
Events |
|
---|---|
change |
Arguments: 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: Sets or updates the component's configuration options (this can also be done at creation time in the constructor). |
get() |
returns: Returns the current configuration options of a component. |
execute() |
returns: Invokes the component's primary action. This is usually rendering something on the page or running a report (or both). |
on(event, handler) |
returns: Registers a function to be invoked when the component emits the specified event. |
once(event, handler) |
returns: 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: 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: 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