佈建使用者控制的帳戶 – API 開發人員指南

本文說明使用 Provisioning API 建立新的 Google Analytics (分析) 帳戶的重要概念。

簡介

Provisioning API 可用於建立新的 Google Analytics (分析) 帳戶，以及大規模為客戶啟用 Google Analytics (分析)。適用對象為合格的服務供應商和大型合作夥伴。如需 Provisioning API 的簡介，請參閱 Provisioning API 總覽。

事前準備

所有 Google Analytics (分析) API 的存取方式都很類似。開始使用 Provisioning API 之前，請先完成下列事項：

  • 如需可與 API 搭配使用的程式設計語言特定用戶端程式庫的完整清單，請參閱用戶端程式庫頁面。
  • 請閱讀參考指南，瞭解 API 介面以及如何在沒有用戶端程式庫的情況下存取資料。

每個用戶端程式庫都會提供一個數據分析服務物件，用來存取 Provisioning API。一般來說，您必須完成下列步驟，才能建立服務物件：

  1. 在 Google API 控制台中註冊您的應用程式。
  2. 授權建立新的 Google Analytics (分析) 帳戶。
  3. 建立 Analytics (分析) 服務物件。

如果您尚未完成這些步驟，請停止並參閱 Hello Google Analytics API 教學課程。本教學課程將逐步介紹建立 Google Analytics (分析) API 應用程式的初始步驟。完成後，您會瞭解如何存取 Google Analytics (分析) API 來執行實際工作。

總覽

使用 Provisioning API 建立 Google Analytics (分析) 帳戶時，需要考量以下 2 種流程：

  • 技術流程：透過程式為使用者佈建 Google Analytics (分析) 帳戶的端對端流程。
  • 使用者流程：從使用者的角度考量帳戶建立流程時應考量的實作方式。

本文件針對每項流程提供概略步驟和需求。

技術流程

使用 Provisioning API 建立新帳戶並與 Google Analytics (分析) 整合的概略步驟如下：

  1. 提示使用者使用 OAuth 2.0 對應用程式/服務驗證及授權。
  2. 使用 Provisioning API 建立帳戶票證。
  3. 將使用者重新導向接受《Google Analytics (分析) 服務條款》(TOS) 並處理回應。
  4. (選用) 設定帳戶和 整合商機。

如果以上所有步驟都順利完成，您為使用者建立的 Google Analytics (分析) 帳戶就會取得，而新帳戶也會取得該帳戶的帳戶 ID、資源 ID 和資料檢視 (設定檔) ID。

下方每個步驟都包含完成步驟的「需求條件」、該步驟的「結果」，以及該步驟的「技術流程」說明。

1. 驗證及授權

每個使用者都必須授權您的應用程式，並授權應用程式代為佈建 Google Analytics (分析) 帳戶。建議您執行 OAuth 2.0 網路伺服器應用程式流程。

完成這個步驟的必備條件

這個步驟的結果

OAuth 2.0 流程完成後，使用者就會授權您的應用程式代表他們佈建帳戶，您將擁有使用者的存取憑證。

權杖和範圍注意事項：

  • 如果您想在帳戶建立後針對使用者的帳戶設定或報表資料提出其他要求，也可以在這個步驟中授權其他範圍。例如 readonly 或 edit 範圍。
  • 存取權杖的生命週期有限。如果應用程式需要在單次存取權杖的生命週期後存取 Google Analytics (分析) API，您也可以透過設定 access_type=offline 來要求更新權杖。更新權杖應可讓應用程式取得新的存取權杖，因此應儲存至每位使用者的安全長期儲存空間。詳情請參閱「離線存取」一節。

這個步驟的技術流程

您必須取得使用者的存取權杖。根據 OAuth 2.0 網路伺服器說明的流程，將使用者傳送至 Google 帳戶服務，然後在使用者完成驗證流程後，將使用者重新導回您的服務時處理回應。

設定 OAuth 2.0 網址供使用者造訪

當使用者按一下「開始使用」或「建立帳戶」的按鈕或連結時，連結應指向 OAuth 2.0 流程起始處，以便要求使用者授予佈建權限。例如：

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
處理 Google 帳戶服務的回應

如果使用者決定授予您的應用程式存取權，系統就會將他們重新導向至您透過包含授權碼的查詢參數所建立網址中指定的 redirect_uri。如果使用者核准要求，就可以向 Google Accounts API 發出 POST 要求，藉此使用授權碼回應交換存取權杖的授權碼。

儲存更新權杖 (如適用)

下一個步驟會用到存取權杖，以便您暫時儲存。如果您也為使用者要求更新權杖，建議您妥善保存這個憑證，以便長期使用。更新憑證是長期存在，可用於核發新的存取權杖。

2. 使用 Provisioning API 建立帳戶票證

取得授權使用者的存取權杖後，您就能使用這個權杖向 Provisioning API 發出要求，為使用者建立帳戶票證。帳戶票證是為使用者建立帳戶的第一步。

完成這個步驟的必備條件

授權使用者的存取權杖，如「驗證和授權」中所述，以及下列佈建詳細資料：

  • 重新導向 URI
    • 定義 Google Analytics (分析) 服務條款 (TOS) 頁面以後，將使用者重新導向至何處。可以與 OAuth 2.0 授權流程中指定的重新導向 URI 不同。
    • 重新導向 URI 參數的值必須與您在 Google Developers Console 中註冊的其中一個值完全相符 (包括 http 或 https 配置、大小寫，以及結尾為「/」)。
  • 帳戶欄位
    • 帳戶的 name 是必要屬性。
  • 網站資源欄位
    • 對該屬性而言，name 是必要屬性。
    • websiteUrl 為必要項目。
  • 個人資料欄位
    • 對設定檔而言，name 為必要屬性。
    • 您可以視需要提供 timezone。預設值為 America/Los_Angeles。

建立帳戶支援單時，只能設定上述基本欄位。建立帳戶後，您可以使用 Management API，對資源或資料檢視 (設定檔) 進行任何其他設定變更。

如要進一步瞭解這些欄位，請參閱「帳戶」、「資源」和「資料檢視 (設定檔)」的 API 參考資料。

這個步驟的結果

成功向 Provisioning API 發出要求後，您就會擁有使用者的短期帳戶票證。在最後一個步驟中，系統會使用帳戶支援單 ID，提示使用者接受《服務條款》(TOS) 並啟用帳戶。你必須接受服務條款，才能使用帳戶。

這個步驟的技術流程

使用驗證與授權期間所取得使用者的存取權杖，向 Provisioning API 發出 HTTP POST 要求。

Provisioning API 要求來建立帳戶票證

請參閱 Provisioning API 參考資料中的 createAccountTicket 方法，進一步瞭解如何提出要求。

Provisioning API 的回應

成功的要求會傳回 200 回應。回應主體包含一個短期的帳戶支援單。帳戶支援單包含新帳戶樹狀結構的 ID 和詳細資料。

如要進一步瞭解回應，請參閱 Provisioning API 參考資料中的 Account Ticket resource。

錯誤回應也必須由應用程式處理。

3. 使用者接受 Google Analytics (分析) 服務條款 (TOS)

取得使用者的帳戶票證 ID 後，您就可以在 TOS 要求中使用這組 ID，提示使用者接受《Google Analytics (分析) 服務條款》。

完成這個步驟的必備條件

授權使用者的帳戶支援單 ID。

這個步驟的結果

使用帳戶支援單 ID 成功完成《服務條款》流程後，系統就會建立帳戶、資源和資料檢視 (設定檔)。現在使用者將會擁有使用中的帳戶。TOS 頁面的回應將包含帳戶 ID、資源 ID 和資料檢視 (設定檔) ID。

這個步驟的技術流程

使用帳戶票證 ID，將使用者重新導向至 Google Analytics (分析) 服務條款頁面，並在該頁面接受服務條款，接著您需處理來自 API 的回應。

表單供使用者造訪

將使用者重新導向至 TOS 頁面，並在網址中加入帳戶支援單 ID：

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
處理服務條款回覆

使用者在服務條款頁面上執行特定操作後，系統會將他們重新導向回建立帳戶支援單時指定的 redirectUri。TOS 頁面的回應將納入查詢字串中。

成功的回應將傳回新建帳戶結構以及原始 accountTicketId 的相關資料：

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

舉例來說，如果應用程式的 TOS 處理常式位於 http://www.your-app.com/gaTOS，則在建立帳戶票證時，應將其設為 redirectUri。在帳戶票證有效且使用者已接受服務條款的情況下，應用程式的 TOS 處理常式應預期並妥善處理包含 accountId、webPropertyId、profileId 和 accountTicketId 查詢參數的 HTTP GET 要求。

Unsuccessful 回應會包含以下錯誤回應：

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

您的 TOS 處理常式也應正確處理包含 error 查詢參數的 HTTP GET 要求，指出發生錯誤。查詢參數的值可用來進一步採取行動，或向使用者顯示訊息：

  • error=user_cancel - 使用者未接受服務條款。
  • error=max_accounts_reached - 使用者已達 Google Analytics (分析) 帳戶上限。
  • error=backend_error：一般錯誤。伺服器傳回上述類別以外的錯誤。

4. (選用) 整合商機

按照上述技術流程操作後，您將會為使用者建立帳戶，且擁有帳戶 ID、資源 ID 和資料檢視 (設定檔) ID。如果您也要求其他權限，也可以為使用者取得更新權杖。加入這些資料後，您就可以：

使用者流程

本節說明以使用者的角度說明帳戶建立流程步驟的相關實作注意事項。

流程一開始為使用者提供以下 2 個選項啟用資源分析的選項：

  1. 建立 Google Analytics (分析) 帳戶
  2. 使用現有的 Google Analytics (分析) 帳戶。(注意：此流程不在本文件的涵蓋範圍內。如要進一步瞭解如何存取使用者的 Google Analytics (分析) 設定資料，請參閱 Management API。

建立新的 Google Analytics (分析) 帳戶時，對於佈建要求，您必須提供某些資訊，例如帳戶名稱、資源名稱等。視您的使用者相關資訊和您希望向他們顯示的偏好流程而定，有 3 個主要選項可讓您在使用者按下「建立帳戶」後啟動使用者流程：

授權後要求提供帳戶詳細資料

在此情況下，系統會在程序中要求使用者提供帳戶詳細資料。流程大致如下：

  1. 將使用者重新導向至 Google 帳戶服務，以便開始使用 OAuth 2.0 流程。如果使用者沒有 Google 帳戶或未登入，系統會要求他們建立或登入。
  2. 系統會提示使用者授權應用程式「建立 Google Analytics (分析) 帳戶」。
  3. 使用者接受應用程式的權限要求。
  4. 將使用者重新導向至服務供應商。請注意，如果使用者拒絕授權，仍然會重新導向回服務供應商。
  5. 系統會向使用者顯示表單，以便收集要建立帳戶的詳細資料，例如帳戶名稱、資源名稱、設定檔名稱、時區、網站網址等。
  6. 使用者填寫並提交表單，然後重新導向至 Google/顯示《Google Analytics (分析) 服務條款》(TOS)。
  7. 使用者接受服務條款。
  8. 系統會將使用者重新導向至服務供應商，並顯示成功訊息，指出使用者已成功建立 Google Analytics (分析) 帳戶，內有帳戶的詳細資料及存取方式。請注意，如果使用者不接受 TOS，仍會重新導向回服務供應商。

請在授權前要求提供帳戶詳細資料

在這種情況下，系統會先要求使用者為即將建立的帳戶設定詳細資料。流程大致如下：

  1. 在服務供應商網站上，系統會向使用者顯示一份表單，以便收集要建立帳戶的詳細資料，例如帳戶名稱、資源名稱、個人資料名稱、時區和網站網址。
  2. 使用者填寫表單、點選「提交」，並重新導向至 OAuth 2.0 流程的 Google 帳戶服務。如果使用者沒有 Google 帳戶或未登入，系統會要求他們建立或登入。
  3. 系統會提示使用者授權應用程式「建立 Google Analytics (分析) 帳戶」。
  4. 使用者接受應用程式要求的權限。
  5. 將使用者重新導向至服務供應商。
  6. 使用者重新導向至 Google/顯示《Google Analytics (分析) 服務條款》(TOS)。
  7. 使用者接受服務條款。
  8. 系統會將使用者重新導向至服務供應商，並顯示成功訊息，指出使用者已成功建立 Google Analytics (分析) 帳戶，內有帳戶的詳細資料及存取方式。

預先填入帳戶詳細資料或略過表單

如果已提供使用者帳戶的相關資訊 (例如網站網址、網站名稱、時區等)，可以透過以下方式進一步簡化上述兩個選項：

  • 預先填入表單，並允許使用者視需要進行編輯
  • 完全略過表單步驟，自動使用現有資訊建立帳戶。