內建元件參考資料

本文件說明所有內建 Embed API 元件的選項、方法、屬性和事件。

auth

gapi.analytics.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 Developer 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 選項會取代預設的嵌入 API 範圍或新增這類範圍。指定 false (預設值) 會新增至預設範圍，指定 true 則會以 scopes 選項指定的範圍取代。 預設範圍值為：['https://www.googleapis.com/auth/analytics.readonly']。 注意：您必須存取使用者的基本設定檔，才能透過 Embed API 進行驗證。這些範圍無法覆寫。
serverAuth.access_token	類型：  string 如果您具備有效的存取權杖，可以直接將權杖傳送至授權方法，系統不會提示使用者進行授權。如要進一步瞭解如何擷取存取權杖，請參閱 OAuth 2.0 說明文件。

活動
signIn	引數：無 使用者成功登入時觸發。
signOut	引數：無 使用者成功登出時觸發。
needsAuthorization	引數：無 叫用 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)	資料元件可讓您查詢 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 圖表和資料元件，讓您輕鬆透過查詢建立圖表，而不必自行連接。

選項
query	類型：  Object 請參閱資料元件查詢選項。
chart	類型：  Object 請參閱下列個別圖表選項的詳細資料。
chart.container	類型：  string|HTMLElement 在 DOM 中代管 DataChart 的 HTML 元素 ID。您也可以將參照傳遞至元素本身。
chart.type	類型：  string 圖表類型。可能的選項如下：LINE、COLUMN、BAR、TABLE 和 GEO。
chart.options	類型：  Object 可傳遞至對應 Google Chart 物件的任何選項。

繼承方法
get
set
execute
on
once
off
emit

活動
success	引數：  result 查詢順利完成且圖表完全轉譯時觸發。 result.chart：Google Chart 執行個體。 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 是 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