Provisioning API - デベロッパー ガイド

このドキュメントでは、Provisioning API を使用した Google アナリティクスの新しいアカウントの作成に関する重要な概念について説明します。

はじめに

Provisioning API を使って新しい Google アナリティクス アカウントを作成し、幅広い顧客に対して Google アナリティクスを利用可能にすることができます。Provisioning API は、正規サービス プロバイダや大企業のパートナーなどを対象としています。この API の簡単な説明については、Provisioning API の概要をご覧ください。

準備

Google アナリティクス API はすべて、同じ方法でアクセスできます。Provisioning API を使用する前に、次の準備をしてください。

  • API で利用可能なすべてのプログラミング言語ごとのクライアント ライブラリの一覧を、クライアント ライブラリ ページで確認します。
  • API インターフェースと、クライアント ライブラリを使わずにデータにアクセスする方法についてリファレンス ガイドで確認します。

各クライアント ライブラリでは、Provisioning API にアクセスするための 1 つの Analytics サービス オブジェクトを提供します。このサービス オブジェクトを作成 するには、通常、次の手順に従います。

  1. お使いのアプリケーションを Google API コンソールで登録します。
  2. 新しい Google アナリティクス アカウントの作成を承認します。
  3. Analytics サービス オブジェクトを作成します。

上記の手順を完了していない場合は、まず Google アナリティクス API についてのチュートリアルをご覧ください。このチュートリアルでは、Google アナリティクス API アプリケーションを作成する基本的な手順を詳しく説明しています。この手順を完了すると、Google アナリティクス API を実際の作業に活用する方法を理解することができます。

概要

Provisioning API を使って Google アナリティクスのアカウントを作成する場合、次の 2 つのフローを考慮する必要があります。

  • 技術的なフロー: ユーザーの Google アナリティクス アカウントをプログラムによってプロビジョニングするエンド ツー エンドのフロー。
  • ユーザーのフロー: ユーザーの視点から見た、アカウント作成フローに対する実装の考慮事項。

このドキュメントでは、各フローのおおまかな手順と要件について説明します。

技術的なフロー

Provisioning API を使って新しいアカウントを作成し、Google アナリティクスと統合するためのおおまかな手順は次のとおりです。

  1. ユーザーに対し、OAuth 2.0 を使ってアプリケーションまたはサービスを認証、承認するように求めます。
  2. Provisioning API を使ってアカウント チケットを作成します。
  3. Google アナリティクスの利用規約(TOS)への同意に関する画面にユーザーをリダイレクトし、レスポンスを処理します。
  4. (省略可能)アカウントと統合の最適化を設定します。

これらすべての手順を正常に完了すると、ユーザーの Google アナリティクス アカウントが作成され、新しいアカウントのアカウント ID、プロパティ ID、ビュー ID(旧プロファイル ID)が割り当てられます。

次に示す各手順では、手順を完了するための要件、手順の結果、手順の技術的なフローの説明が記載されています。

1. 認証と承認

各ユーザーは、アプリケーションを承認し、自身に代わって Google Analyticsアカウントをプロビジョニングする機能をそのアプリケーションに付与する必要があります。この手順を実行するための OAuth 2.0 ウェブサーバーのアプリケーション フローを紹介します。

この手順を完了するための要件

  • クライアント ID - 使用するプロジェクトの Client IDGoogle Developers Console から入手できます。詳細については、OAuth 2.0 ウェブサーバーのフローをご覧ください。
  • リダイレクト URI - ユーザーのリダイレクト先。ここから OAuth 2.0 レスポンスが送信されます。
    • プロジェクトの Client ID を取得するために、Google Developers Console を使って Redirect URIs を設定します。
    • このパラメータの値は、Google Developers Console で登録されている値の 1 つと完全に一致している必要があります(http や https などのスキーム、大文字と小文字の区別、末尾の「/」などを含む)。
  • Google アナリティクス Provisioning API の承認スコープ

この手順の結果

OAuth 2.0 のフローが完了した時点で、ユーザーはアプリケーションが自身に代わってアカウントをプロビジョニングすることを許可したことになります。またユーザーのアクセス トークンが割り当てられます。

トークンとスコープに関する注意事項

  • アカウントの作成後に、ユーザーのアカウント設定かレポートデータのリクエストを追加で行う場合、この手順でスコープをさらに承認することができます。たとえば、承認できるスコープには readonlyedit があります。
  • アクセス トークンには有効期間があります。アクセス トークンの有効期間が終了した後に、アプリケーションが Google アナリティクス API へのアクセスを必要とする場合、access_type=offline を設定してリフレッシュ トークンをリクエストすることもできます。リフレッシュ トークンを使用すると、アプリケーションが新しいアクセス トークンを取得できるようになるため、リフレッシュ トークンはユーザーごとに安全な場所で長期間保管する必要があります。詳細については、オフライン アクセスをご覧ください。

この手順の技術的なフロー

ユーザーのアクセス トークンを取得する必要があります。OAuth 2.0 ウェブサーバーで説明したフローに基づいて、Google アカウントのサービスにユーザーを誘導します。その後、ユーザーが承認フローを完了してサービスにリダイレクトされた時点でレスポンスを処理します。

ユーザーがアクセスする OAuth 2.0 URL を作成する

ユーザーが「今すぐ開始」や「アカウントを作成」といったリンクかボタンをクリックすると、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 アカウントのサービスからのレスポンスを処理する

ユーザーがアプリケーションにアクセスを許可すると、そのユーザーは、承認コードを含むクエリ パラメータを使用して作成された URL によって指定される redirect_uri にリダイレクトされます。ユーザーがリクエストを承認したら、Google アカウント API に対して POST リクエストを実行することにより、承認コードのレスポンスを使って承認コードをアクセス トークンと交換することができます。

リフレッシュ トークンを保存する(該当する場合)

アクセス トークンは次の手順で使用されるため、一時的に格納しておきます。また、ユーザーのリフレッシュ トークンもリクエストした場合は、リフレッシュ トークンをより長期的な使用のために安全な場所に保管する必要があります。リフレッシュ トークンは有効期間が長いため、新しいアクセス トークンの発行に使用できます。

2. Provisioning API を使ってアカウント チケットを作成する

承認済みユーザーのアクセス トークンを取得したら、これを使って、Provisioning API にリクエストを実行し、ユーザーのアカウント チケットを作成することができます。アカウント チケットは、ユーザーのアカウントを作成するための最初の手順です。

この手順を完了するための要件

認証と承認で説明した承認済みユーザーのアクセス トークンと、以下のプロビジョニングの詳細情報が必要となります。

  • リダイレクト URI
    • ユーザーが Google アナリティクス利用規約(TOS)ページの後にリダイレクトされる場所を定義します。その場所は、OAuth 2.0 の承認フローで指定したリダイレクト URI とは異なる場合があります。
    • リダイレクト URI パラメータの値は、Google Developers Console で登録された値の 1 つと完全に一致しなければなりません(http や https などのスキーム、大文字と小文字の区別、末尾の「/」などを含む)。
  • アカウント フィールド
    • name プロパティはアカウントの必須プロパティです。
  • ウェブ プロパティ フィールド
    • name プロパティはウェブ プロパティの必須プロパティです。
    • websiteUrl必須です。
  • プロファイル フィールド
    • name プロパティはプロファイルの必須プロパティです。
    • timezone は省略可能ですが、指定することもできます。デフォルトは America/Los_Angeles です。

アカウント チケットを作成する場合、設定できるのは、上記に示した基本フィールドのみです。アカウントが作成されたら、Management API を使ってプロパティまたはビュー(旧プロファイル)への設定変更を追加で行うことができます。

これらのフィールドの詳細については、アカウントプロパティビュー(旧プロファイル)の API リファレンスをご覧ください。

この手順の結果

Provisioning API へのリクエストが成功すると、有効期間の短いアカウント チケットがユーザーに割り当てられます。アカウント チケット ID は、ユーザーに利用規約(TOS)への同意とアカウントの有効化を求める最後の手順で使用されます。TOS に同意するまで、アカウントを使用することはできません。

この手順の技術的なフロー

認証と承認で取得したユーザーのアクセス トークンを使って、Provisioning API に HTTP POST リクエストを実行します。

アカウント チケットを作成するための Provisioning API リクエスト

リクエストの実行方法の詳細については、Provisioning API リファレンスで createAccountTicket メソッドをご確認ください。

Provisioning API からのレスポンス

リクエストが成功すると、ステータス コード 200 のレスポンスが返されます。レスポンスの本文には、有効期間の短いアカウント チケットが含まれています。アカウント チケットは、ID と新しいアカウント ツリーの詳細情報からなります。

レスポンスの詳細については、Provisioning API リファレンスで Account Ticket resource をご覧ください。

エラー レスポンスもアプリケーションで処理します。

3. ユーザーが Google アナリティクス利用規約(TOS)に同意する

ユーザーのアカウント チケット ID を取得したら、TOS のリクエストでこれを使用して、ユーザーに Google アナリティクス利用規約への同意を求めることができます。

この手順を完了するための要件

承認済みユーザーのアカウント チケット ID

この手順の結果

アカウント チケット ID を使って TOS のフローを正常に終了すると、アカウント、プロパティ、ビュー(旧プロファイル)が作成されます。これでユーザーに有効なアカウントが用意されました。TOS ページからのレスポンスには、アカウント ID、プロパティ ID、ビュー ID が含まれています。

この手順の技術的なフロー

アカウント チケット ID を使用すると、ユーザーは Google アナリティクス TOS ページにリダイレクトされます。このページでは、ユーザーが TOS に同意することができ、その後 API からのレスポンスを処理します。

ユーザーがアクセスする TOS URL を作成する

ユーザーを TOS ページにリダイレクトし、URL の一部としてアカウント チケット ID を含めます。

https://www.google.com/analytics/web/?provisioningSignup=false#management/TermsOfService//?
  api.accountTicketId={account_ticket_id}
TOS のレスポンスを処理する

ユーザーは、TOS ページでなんらかのアクションを起こすと、アカウント チケットの作成中に指定した 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 ハンドラは、アカウント チケットが有効であり、ユーザーが TOS に同意した場合に accountIdwebPropertyIdprofileIdaccountTicketId という 4 つのクエリ パラメータを含む HTTP GET リクエストを予測し、正しく処理する必要があります。

失敗したレスポンスには、次のようなエラー レスポンスが含まれます。

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

TOS ハンドラは、問題を示す error クエリ パラメータを含む HTTP GET リクエストも正しく処理する必要があります。このクエリ パラメータの値を使って、さらに対応するか、ユーザーに次のようなメッセージを表示することができます。

  • error=user_cancel - ユーザーが利用規約に同意しませんでした。
  • error=max_accounts_reached - ユーザーの Google アナリティクス アカウントが制限数に達しました。
  • error=backend_error - 一般的なエラー。サーバーから上記のカテゴリにないエラーが返されました。

4.(オプション)統合の最適化

上記の技術的なフローに従った場合、ユーザーのアカウントが作成され、アカウント ID、プロパティ ID、ビュー ID が割り当てられます。さらに追加の権限もリクエストした場合は、ユーザーのリフレッシュ トークンも割り当てられます。このデータを使用すると、次のことを実行できます。

ユーザーのフロー

このセクションでは、ユーザーの視点から、アカウント作成フローの手順に関連する実装の考慮事項について説明します。

ユーザーのフローでは、まず次の 2 つのいずれかを実行し、プロパティに対してアナリティクスを有効にします。

  1. Google アナリティクス アカウントを作成します。
  2. 既存の Google アナリティクス アカウントを使用します(: このフローについては、このドキュメントでは説明しません。ユーザーの Google アナリティクス設定データにアクセスする方法の詳細については、Management API をご覧ください)。

新しい Google アナリティクス アカウントを作成する場合、アカウント名やプロパティ名など、プロビジョニングのリクエストと一緒に送信する必要のある情報があります。ユーザーに関する既知の情報と、ユーザーに提示する推奨フローに応じて、ユーザーが [アカウントを作成する] をクリックした後にユーザーのフローを開始するための主な選択肢は、次の 3 つです。

承認後にアカウントの詳細情報を要求する

この場合、ユーザーは、プロセスの途中でアカウントの詳細情報を要求されます。フローは次のようになります。

  1. ユーザーが OAuth 2.0 フローを実行するための Google アカウント サービスにリダイレクトされます。ユーザーが Google アカウントを持っていない場合や Google アカウントにログインしていない場合は、Google アカウントの作成またはログインが求められます。
  2. ユーザーは、「Google アナリティクス アカウントの作成」をアプリケーションに承認するように求められます。
  3. ユーザーがアプリケーションに対してリクエストされた権限を許可します。
  4. ユーザーはサービス プロバイダにリダイレクトされます。承認を拒否した場合でも、ユーザーはサービス プロバイダにリダイレクトされます。
  5. 作成するアカウントに関する詳細情報(アカウント名、プロパティ名、プロファイル名、タイムゾーン、ウェブサイト URL など)を収集するためのフォームがユーザーに表示されます。
  6. フォームに必要事項を入力して送信すると、ユーザーは Google にリダイレクトされ、Google アナリティクス利用規約(TOS)が表示されます。
  7. ユーザーが TOS に同意します。
  8. ユーザーはサービス プロバイダにリダイレクトされ、Google アナリティクス アカウントの作成が正常に完了したことを示すいくつかのメッセージとともに、アカウントとそのアカウントへのアクセス方法が表示されます。TOS に同意しない場合でも、ユーザーはサービス プロバイダにリダイレクトされます。

承認前にアカウントの詳細情報を要求する

この場合、作成しようとしているアカウントの設定の詳細情報が事前に要求されます。フローは次のようになります。

  1. サービス プロバイダ サイトで、作成するアカウントに関する詳細情報(アカウント名、プロパティ名、プロファイル名、タイムゾーン、ウェブサイト URL)を収集するためのフォームがユーザーに表示されます。
  2. ユーザーがフォームに必要事項を入力して [送信] をクリックすると、OAuth 2.0 フローを実行するための Google アカウント サービスにリダイレクトされます。ユーザーが Google アカウントを持っていない場合や Google アカウントにサインインしていない場合は、Google アカウントの作成またはログインが求められます。
  3. ユーザーは、「Google アナリティクス アカウントの作成」をアプリケーションに承認するように求められます。
  4. ユーザーがアプリケーションに対してリクエストされた権限を許可します。
  5. ユーザーはサービス プロバイダにリダイレクトされます。
  6. ユーザーは Google にリダイレクトされ、Google アナリティクス利用規約(TOS)が表示されます。
  7. ユーザーが TOS に同意します。
  8. ユーザーはサービス プロバイダにリダイレクトされ、Google アナリティクス アカウントの作成が正常に完了したことを示すいくつかのメッセージとともに、アカウントとそのアカウントへのアクセス方法が表示されます。

アカウントの詳細情報を事前に入力するか、フォームをスキップする

ユーザー アカウントに関する情報(ウェブサイト URL、ウェブサイト名、タイムゾーンなど)が既にわかっている場合、上記の 2 つのオプションは次の方法でさらに簡略化できます。

  • フォームの必要事項を事前に入力し、ユーザーが必要に応じて編集できるようにします。
  • フォームの入力手順をすべてスキップし、既存の情報を使ってアカウントを自動的に作成します。