開始使用

總覽

本文件將透過完整範例，逐步說明如何使用 Embed API。完成後，應用程式看起來會像這樣。

本指南所涵蓋範例的螢幕截圖
本指南中所涵蓋範例的螢幕截圖。

建立簡易資訊主頁

您可以按照下列 2 個簡單步驟，在伺服器上執行範例應用程式：

  1. 建立新的用戶端編號
  2. 複製並貼上代碼

這個應用程式啟動完畢之後，下一節會詳細說明如何將所有部分整合在一起。

建立新的用戶端 ID

Embed API 提供一鍵登入元件，可採用您熟悉的 OAuth 2.0 流程，可為您處理幾乎所有的授權程序。若要讓這個按鈕在您的網頁上運作，您需要有用戶端 ID。

如果您從未建立用戶端 ID，可以按照 這些操作說明操作。

在按照指示進行操作時，請務必避免忽略這兩個重要步驟：

  • 啟用 Analytics API
  • 設定正確的來源

來源可控管哪些網域可使用此程式碼授權使用者。這樣可以防止他人複製您的程式碼，並在他們的網站中執行。

舉例來說，如果您的網站由 example.com 網域代管，請務必為用戶端 ID http://example.com 設定下列來源。如要在本機測試程式碼，您還需要新增本機伺服器的來源，例如：http://localhost:8080。

複製及貼上程式碼

設定包含正確來源設定的用戶端 ID 後，您就可以開始建立示範。只需將下列程式碼複製並貼入伺服器外掛程式的 HTML 檔案中 (例如「在這裡插入用戶端 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：授權使用者

Embed API 提供一鍵登入元件，可採用熟悉的 OAuth 2.0 流程，可為您處理幾乎所有的授權程序。若要在您的網頁上試用此按鈕，您需要傳入容器參照和您的用戶端 ID。

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

這項操作會在元素中產生一個包含「auth-button」 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 參考資料。