内置组件参考

本文档介绍 Embed API 所有内置组件的选项、方法、属性和事件。

auth

gapi.analytics.auth

Auth 组件是用于向用户提供授权的单例组件。

方法

authorize(options:Object)

返回值gapi.analytics.auth

在指定的容器内显示 Google Analytics(分析)登录按钮,允许用户使用 Google 帐号登录。

isAuthorized()

返回值boolean

如果用户授权成功,系统会返回 true,否则将返回 false

signOut()

返回值gapi.analytics.auth

使当前用户退出帐号。同时触发 signOut 事件。

getAuthResponse()

返回值Object

获取原始授权请求返回的身份验证数据。返回的对象包括访问令牌(通常可用于手动发出经身份验证的请求)。

getUserProfile()

返回值Object

获取有关当前已登录用户的基本个人资料信息。这些信息包括用户的姓名、电子邮件地址和公开个人资料图片(如果已设置)。

继承的方法

on
once
off

选项

clientId

类型string

您的项目在 Google Developers Console 中的客户 ID。

container

类型string|HTMLElement

DOM 中托管“登录”按钮的 HTML 元素 ID。您也可以传递对该元素本身的引用。

userInfoLabel

类型string

在用户登录电子邮件地址前面显示的文字。默认设置为 'You are logged in as: '

scopes

类型Array

应用请求的 Google API 授权范围列表。要查看所有可用的范围,请访问 OAuth 2.0 Playground。要了解 Google Analytics(分析)API 的身份验证范围,请参阅针对配置报告资源的开发者指南。

overwriteDefaultScopes

类型boolean

指明 scopes 选项是替换默认的 Embed API 范围还是附加至默认范围。false(默认值)表示 scopes 选项指定的范围会附加至默认范围,true 表示指定范围会替换默认范围。

默认范围值为:['https://www.googleapis.com/auth/analytics.readonly']

注意:通过 Embed API 进行身份验证需要访问用户的基本个人资料。这些范围无法被覆盖。

serverAuth.access_token

类型string

如果您已经拥有有效的访问令牌,则可将其直接传递给授权方法,系统将不会提示用户进行授权。要详细了解如何获取访问令牌,请参阅 OAuth 2.0 文档

事件

signIn

参数:None

用户成功登录时触发。

signOut

参数:None

用户成功退出时触发。

needsAuthorization

参数:None

调用 gapi.analytics.auth.authorize 方法时,将进行初次检查,确认用户当前是否已登录。如果用户登录,将触发该事件,指明需要进一步的授权。

error

参数response

身份验证流程出错时触发。请查看 response.error.message,获取响应对象的错误消息。

弃用的事件
success

参数response

此事件旨在实现向后兼容,可能会在以后的版本中删除,而改用 signIn 事件。

示例

// 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
构造器
Data(options:Object) 通过 Data 组件,您可以查询 Google Analytics(分析)Core Reporting API 并获取结果。

选项

query

类型Object

包含 Core Reporting API查询参数的对象。除了采用由 API 提供的常规默认值,系统还采用以下默认值:

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

继承的方法

get
set
execute
on
once
off
emit

事件

success

参数response

查询成功完成时触发。

error

参数response

查询流程出错时触发。请查看 response.error.message,获取响应对象的错误消息。

示例

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
构造器
DataChart(options:Object) DataChart 会对标准的 Google 图表和 Data 组件进行封装,因此您可以轻松创建可视化的查询结果,而无需自行绑定。

选项

query

类型Object

请查看 Data 组件的 query 选项

chart

类型Object

有关各个图表选项的详细信息,请参阅下文。

chart.container

类型string|HTMLElement

DOM 中托管 DataChart 的 HTML 元素 ID。您也可以传递对该元素本身的引用。

chart.type

类型string

图表类型。可选的类型包括:LINECOLUMNBARTABLEGEO

chart.options

类型Object

可传递到相应的 Google 图表对象的任何选项。

继承的方法

get
set
execute
on
once
off
emit

事件

success

参数result

查询成功完成且图表完全呈现时触发。

  • result.chart - Google 图表实例。
  • result.data - 报告响应(采用数据参数格式)。
  • result.dataTable – 在 result.data 对象中创建的 DataTable 实例。
  • result.response - 原始 API 响应对象。
error

参数response

查询或呈现流程出错时触发。请查看 response.error.message,获取响应对象的错误消息。

示例

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
构造器
ViewSelector(options:Object) 借助 ViewSelector 组件,您可以通过下拉菜单选择自己的帐号、媒体资源和数据视图。

选项

container

类型string|HTMLElement

DOM 中托管 ViewSelector 的 HTML 元素 ID。您也可以传递对该元素本身的引用。

继承的方法

get
set
execute
on
once
off
emit

实例属性

ids

类型string

ga:XXXX 表单的唯一表格 ID,其中 XXXX 是 Google Analytics(分析)数据视图(配置文件)ID。

事件

change

参数ids

每次用户通过下拉菜单选择新数据视图时就会触发。首次呈现 ViewSelector 实例以及显示默认数据视图时也会触发。

示例

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

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

viewSelector.execute();

共享的组件方法

方法
set(options)

返回值this

设置或更新组件的配置选项(使用构造函数创建组件时也可完成此操作)。

get()

返回值Object

返回组件的当前配置选项。

execute()

返回值this

调用组件的主操作。通常会在页面上呈现数据或生成报告(或同时执行这两项操作)。

on(event, handler)

返回值this

注册事件处理函数,当组件发出指定事件时调用该函数。

once(event, handler)

返回值this

注册事件处理函数,仅当指定事件再次发生时调用该函数。处理程序运行一次之后会自动取消注册。

off(opt_event, opt_handler)

返回值undefined

删除组件中的事件处理程序。如果未传递处理程序,系统会删除已传递事件的所有处理程序。如果未传递事件,系统会删除所有事件的所有处理程序。

emit(event, ...opt_args)

返回值undefined

发出事件。您可以选择指定要传递到任何已注册处理程序的参数。

set

设置或更新组件的配置选项(使用构造函数创建组件时也可完成此操作)。

用法

component.set(options);

参数

名称 类型 说明
options Object 此组件的配置选项。传递的选项将与现有选项合并。

返回值

this – 组件实例。


get

返回组件的当前配置选项。

返回值

Object – 组件的当前配置选项。


execute()

调用组件的主操作。通常会在页面上呈现数据或生成报告(或同时执行这两项操作)。

返回值

this – 组件实例。


on(event, handler)

注册事件处理函数,当组件发出指定事件时调用该函数。

参数

名称 类型 说明
event string 事件名称。
handler Function 事件发生时要调用的函数。(要了解参数的详细信息,请参阅各个事件参考。)

返回值

this – 组件实例。


once(event, handler)

注册事件处理函数,仅当指定事件再次发生时调用该函数。处理程序运行一次之后会自动取消注册。

参数

名称 类型 说明
event string 事件名称。
handler Function 事件发生时要调用的函数。(要了解参数的详细信息,请参阅各个事件参考。)

返回值

this – 组件实例。


off(opt_event, opt_handler)

删除组件中的事件处理程序。如果未传递处理程序,系统会删除已传递事件的所有处理程序。如果未传递事件,系统会删除所有事件的所有处理程序。

参数

名称 类型 说明
opt_event string 事件名称。如果未指定事件,系统会删除所有事件的所有处理程序。可选。
opt_handler Function 对要删除的函数处理程序的引用。如果未传递函数,系统会删除所有处理程序。可选。

返回值

undefined


emit(event, ...opt_args)

发出事件。您可以选择指定要传递到任何已注册处理程序的参数。

参数

名称 类型 说明
event string 事件名称。
...opt_args * 传递到任何已注册处理程序的可选参数。

返回值

undefined