使用入门

概览

本文档通过一个完整示例来指导您学习如何使用 Embed API 。您最终完成的应用将如下所示。

本指南所用示例的屏幕截图
本指南所用示例的屏幕截图。

创建简单的信息中心

按照以下两个简单步骤执行操作即可在您的服务器上运行示例应用:

  1. 新建一个客户端 ID
  2. 复制并粘贴代码

安装和运行此应用之后,下文将详细介绍各部分之间如何协同运作。

新建一个客户端 ID

通过提供采用熟悉的 OAuth 2.0 流程的一键式登录组件,Embed API 可为您处理几乎所有授权流程。要使此按钮在您的网页上正常运行,您需要创建一个客户端 ID。

如果您尚未创建过客户端 ID,请按照这些说明执行操作。

阅览本说明时,请务必重视以下两个关键步骤:

  • 启用 Google Analytics(分析)API
  • 设置正确的源

源可以控制哪些域能够使用此代码授权用户,从而阻止了其他人复制并在其网站上运行您的代码。

例如,如果您的网站托管在域 example.com 上,则请确保为您的客户端 ID 设置以下源 http://example.com。如需在本地测试代码,您还需要将此源添加到本地服务器,例如:http://localhost:8080

复制并粘贴代码

为您的客户端 ID 设置了正确的源后,您就可以着手创建演示了。只需执行以下操作即可:将以下代码复制并粘贴到您服务器上的 HTML 文件中,并在标有“请插入您的客户端 ID”的位置插入您的客户端 ID。

<!DOCTYPE html>
<html>
<head>
  <title>Embed API Demo</title>
</head>
<body>

<!-- Step 1: Create the containing elements. -->

<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>

<!-- Step 2: Load the library. -->

<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>

<script>
gapi.analytics.ready(function() {

  // Step 3: Authorize the user.

  var CLIENT_ID = 'Insert your client ID here';

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

  // Step 4: Create the view selector.

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

  // Step 5: Create the timeline chart.

  var timeline = new gapi.analytics.googleCharts.DataChart({
    reportType: 'ga',
    query: {
      'dimensions': 'ga:date',
      'metrics': 'ga:sessions',
      'start-date': '30daysAgo',
      'end-date': 'yesterday',
    },
    chart: {
      type: 'LINE',
      container: 'timeline'
    }
  });

  // Step 6: Hook up the components to work together.

  gapi.analytics.auth.on('success', function(response) {
    viewSelector.execute();
  });

  viewSelector.on('change', function(ids) {
    var newIds = {
      query: {
        ids: ids
      }
    }
    timeline.set(newIds).execute();
  });
});
</script>
</body>
</html>

代码演示

本部分将分步向您详细介绍为示例应用提供的代码的具体工作原理。掌握代码的工作原理之后,您就可以创建自己的代码了。

第 1 步:创建组件容器

大多数 Embed API 组件会在网页上直观地展示某些内容。通过为这些组件创建容器即可控制它们的动向。示例应用中包含授权按钮、视图选择器和图表。上述各个组件均可在以下 HTML 元素内呈现:

<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>

创建组件时,请通过组件 ID 属性来指定它使用哪种容器,如后续示例所示。

第 2 步:加载库

您可以利用以下代码段加载 Embed API。

<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>

库完全加载后,系统会调用传递给 gapi.analytics.ready 的任何回调。

<script>
gapi.analytics.ready(function() {
  // Put your application code here...
});
</script>

第 3 步:授权用户

通过提供采用熟悉的 OAuth 2.0 流程的一键式登录组件,Embed API 可为您处理几乎所有授权流程。要使此按钮在您的网页上正常运行,您需要传入容器引用客户端 ID

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

此操作会利用“授权按钮”ID 在元素内部生成一个按钮,该 ID 会为您处理授权流程。

第 4 步:创建视图选择器

视图选择器组件可用于获取某个视图的 ID,因此您可以为视图生成报告。

仅需第 1 步中创建的容器引用即可创建视图选择器。

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

此操作会创建视图选择器组件,但不会在网页中呈现该组件。要使其呈现,您需要调用 execute(),详见第 6 步

第 5 步:创建时间轴图表

Embed API 为您提供了一个集 Google 图表和报告对象于一体的图表组件。此功能极大简化了数据的展示流程,因为图表对象将在后台运行报告并自动更新结果。

要创建图表组件,您需要指定 API 查询参数和图表选项。图表选项包含您在第 1 步中创建的容器 ID 引用。

var timeline = new gapi.analytics.googleCharts.DataChart({
  reportType: 'ga',
  query: {
    'dimensions': 'ga:date',
    'metrics': 'ga:sessions',
    'start-date': '30daysAgo',
    'end-date': 'yesterday',
  },
  chart: {
    type: 'LINE',
    container: 'timeline'
  }
});

正如视图选择器一样,此操作可创建图表组件,但要在网页中呈现此组建,您需要调用 execute(),详见下一步。

第 6 步:连接组件以使组件协同运作

当发生以下各类情形时,例如成功授权、选择新视图或图表已完全呈现,Embed API 组件就会发出相应的事件。

只有经过授权后,本指南中的示例应用才会呈现视图选择器,并且只要用户从视图选择器中选择新视图,示例应用就会更新时间轴图表。

gapi.analytics.auth.on('success', function(response) {
  viewSelector.execute();
});

viewSelector.on('change', function(ids) {
  var newIds = {
    query: {
      ids: ids
    }
  }
  timeline.set(newIds).execute();
});

要获取各个组件发出的所有事件的完整列表,请查看 API 参考

后续步骤

本指南为您详细介绍了如何利用 Embed API 创建基本的可视化内容。如需了解更多信息,请查看 API 参考以尽可能获取完整的内容。