使用入门

概览

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

创建简单的信息中心

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

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

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

新建一个客户端 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 参考以尽可能获取完整的内容。