内置组件参考

本文档介绍 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 作用域还是附加于默认的 Embed API 作用域。指定 false（默认值）会添加到默认范围，而指定 true 则会将其替换为 scopes 选项指定的范围。 默认范围值为：['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'
  }
});

注意：使用 serverAuth.access_token 时，授权会立即执行，因此无需注册事件处理脚本。

重要提示：使用 serverAuth.access_token 时，您应确保令牌有效且未过期。如需详细了解如何刷新过期的访问令牌，请参阅 OAuth 2.0 文档。

数据

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 图表类型。可选的类型包括：LINE、COLUMN、BAR、TABLE 和 GEO。
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