Google Analytics API::JavaScript開発者向けデータ出力API
※かなり荒い翻訳なので、参考程度にご覧ください。
このドキュメントは、JavaScriptのクライアントライブラリを使った基本的なデータAPIインタラクションの例を掲載します。 より詳細なフィード・クエリーの構造やレスポンスを知りたいのであれば、フィード・リファレンスやGoogle Analyticsのアカウント・フィードやデータ・フィードに相当するものをご覧ください。
本ドキュメントの対象となる方
このドキュメントは、Google Analyticsと連動したJavaScriptのクライアントアプリケーションを作成したいプログラマー向けに書かれています。 このドキュメントは、あなたが以下の概念にこなれたひとであると仮定しています：
- Google Data APIs protocolの一般的なアイデア。
- Google Analyticsからくるアカウント情報やデータ・フィードのリクエストと連携するしくみ。詳しくはアカウント・フィードやデータ・フィードを参考にしてみてください。
- Getting
Startedに書かれてあるData Export APIの利用の流れ。 - JavaScriptプログラミングの知識。
- JavaScriptクライアント・ライブラリーの基本的な使い方。
クライアント・ライブラリーが提供するクラスやメソッドについてのリファレンスはJavaScriptクライアント・ライブラリーAPIリファレンスを参照してください。
JavaScriptライブラリーの利用
JavaScriptクライアント・ライブラリーによって、Google Analyticsサーバーとの全ての通信を制御します。 JavaScriptクライアント・ライブラリーによってクライアント側はブラウザーのセキュリティーモデルの規則に従っている間、あらゆるドメインからGoogleのData
Export APIのリクエストを送信できます。
ライブラリーを取得する
あなたのアプリケーションにJavaScriptクライアント・ライブラリーを付加するには基本的に２つのステップが必要となります：
あなたのアプリケーションのHTMLドキュメント中にサーバーからクライアント・ライブラリーを埋め込むコードを記述します。これをHTMLドキュメントの<head>タグ内に<script>タグを使って埋め込みます
<script type="text/javascript" src="http://www.google.com/jsapi"></script>
google.load()メソッドを使って、あなたのJavaScriptコードのセットアップ部分でGoogle Analyticsクライアント・ライブラリーをロードします。このメソッドは<head>セクション内か、<head>セクション内の<script>タグによるJavaScriptファイル参照の中で呼び出さなければいけません。
google.load('gdata', '1.x', {packages: ['analytics']});
google.load()に渡す2番目のパラメーターは、要望するJavaScriptクライアント・ライブラリーのバージョンです。 手に入るバージョン番号とその意味について：これはGdata JavaScriptバージョンに関係したものなのか、あるいはクライアントのGA Data APIのバージョンなのか、はっきりしていません
- 1 — メジャーなバージョン１の２つめから最新のリビジョンを含む（全部入り）
- 1.x — メジャーなバージョン１の最新版のみ利用
- 1.s — メジャーなバージョン１の最新「安定」版を利用。Google Analyticsでは時々あるクライアント・ライブラリーのバージョンを、デベロッパーからのフィードバックを受け取った「安定版」として宣言します。しかし、機能的に最新版というわけではありません。
- 1.0, 1.1 … — 特定のメジャーバージョンやマイナーバージョンを選んで組み合わせて利用します。
JavaScriptライブラリーを利用するためにgoogle.load()メソッドを呼んだあとは、あなたのアプリケーションコードが実行される前にHTMLドキュメントがロードを終了するまで待つべきです。 多くの場面では、これを<body>要素のonload()ハンドラで呼び出すよりもloadハンドラ関数で行うのがベストでしょう。
認証
ユーザーがGoogle AnalyticsのWEBサイトでアクセスレポートを見る前に、まずGoogleアカウントを使ってログインしないといけません。 同じように、あなたのアプリケーションもAnalyticsのフィード・データを取得するために認証しなければいけません。 あなたはユーザー認証用のディレクトリーをアプリケーション内に組み込むか、あなたのJavaScriptアプリケーションからユーザーがAnalyticsアクセスを取得するためのユーザーログインを提供できます。 JavaScriptを使って、以下のアプローチのいずれかの方法で認証が可能です：
一般的なGoogle Data APIの認証についての詳しい情報は、authentication
documentationを参照ください。
一度あなたのアプリケーションが認証を完了すると、Googleアカウントに必要な証明が提供されたと実証され、それらの証明情報はAnalyticsのユーザーアカウントにリンクされます。 もし認証が失敗したら、サーバーがエラーを返します。 アカウントアクセスや、証明と認証の違いについての詳しい情報についてはリファレンス・ガイドを参照してください。
AuthSubプロキシー認証
AuthSubプロキシー認証はGoogleアカウントをユーザーに認証する必要があるWEBアプリケーションで使われます。 AuthSubでは、WEBサイトのオペレーターやクライアントのコード上でユーザーのユーザー名やパスワードが見えることはありません。 その代わりに、クライアントは特別なAuthSubトークンを取得します。 このトークン情報をユーザー情報に代わるものとして利用します。 詳しくはAuthentication
for Web Applicationsを参照してください。
以下に、WEBベースのJavaScriptクライアント用の認証の簡単な概要を示します：
- クライアントアプリケーションはクライアント・ライブラリーが提供する「google.accounts.user.login()」メソッドを呼び出すことで、どのGoogleサービスを使うか、スコープ値を得ます。
- クライアント・ライブラリーはブラウザーに対してGoogleアカウントのログインページを送り、そこでユーザーはサービスにログインするための認証情報を入力します。
- ユーザーがログインに成功すると、AuthSubシステムはブラウザーに対してWEBクライアント用のURLを返し、認証用トークンを得ます。
- JavaScriptクライアント・ライブラリーはCookieの中にトークン情報を保存し、「google.accounts.user.login()」という、クライアントアプリケーション用のコントロールを返します。
- クライアントアプリケーションがその後、Analyticsと連携するためのクライアント・ライブラリー・メソッドを呼び出す際、クライアント・ライブラリーは自動的に全てのサーバーリクエストに対してトークン情報を付加します。
注意：WEBブラウザー上で認証されたAnalyticsリクエストを作成するJavaScriptクライアント・ライブラリー用にそのページに（ページと同じ）ドメイン上にある画像を含めなければいけません。 1ピクセルの透明GIF画像でもどんな画像でも良いですが、ページ上の画像でなければいけません。 もし、その画像をページ上に表示させたくなければ、<img>タグのstyle属性にレンダリングエリア外に位置させるようにします。 例えば、「style="position:absolute;
top:-1000px;"」といった感じです。
以下のサンプルコードはどういうふうに認証が制御されるかを示しています：
function logMeIn() {
scope = "https://www.google.com/analytics/feeds";
google.accounts.user.login(scope);
}
function setupMyService() {
var myService =
new google.gdata.analytics.AnalyticsService('exampleCo-exampleApp-1');
logMeIn();
return myService;
}
「user.login()」メソッドは、クライアント・ライブラリーが制御する認証トークン情報を生成し、「google.accounts.user.logout()」メソッドが呼ばれて取り消されるまでそのトークン情報は有効になります：
function logMeOut() {
google.accounts.user.logout();
}
もしlogout()メソッドが呼ばれなければ、トークン情報が保存されたCookieはユーザーによって削除されないかぎり2年間残ります。Cookieはブラウザー・セッションをまたいで保持されますので、ユーザーはブラウザーを閉じたり、再度開いたりしてクライアントとして戻ってきてもまだログインした状態が保たれます。
しかし、トークン情報がセッション中に無効になることがあります。 もしAnalyticsがトークン情報を拒否した場合は、クライアント側で現在のトークン情報がCookieに残らないようにlogout()メソッドを呼んで削除するようにエラーの状況を制御すべきです。
さまざまなコンテキスト中で役に立つ情報を見つけるAuthSubメソッドがあと２つあります：
- 「google.accounts.user.checkLogin(scope)」メソッドはブラウザーが現在（パラメーターで与えられた）スコープの認証トークン情報を持っているかどうかを示します。
- 「google.accounts.user.getInfo()」メソッドはデバッグ用で、現在のトークン情報について詳細な情報を提供します。
トークン情報の管理やcheckLogin()、getInfo()メソッドの情報を含め、AuthSubと連携するJavaScriptの使用法の詳細についてはJavaScriptクライアント・ライブラリーで「AuthSub」認証の使い方ドキュメントを参照ください。
Tip：ユーザーのログイン・プロセスはマニュアル操作で行えるようにログインボタンやその他のユーザー入力のしくみを提供するようにしてください。 もし、ユーザーへのログイン・プロンプトなしにアプリケーションで「google.accounts.user.login()」を呼び出してしまうと、ユーザーは最初からあなたのの作成したページではなくGoogleアカウントのログインページが見える状態になってしまうでしょう。 そこでユーザーがログインしないことに決めても、Googleはあなたのページにリダイレクトで戻すことができません。 このようなシナリオだとユーザーはあなたのページを閲覧しようとしますが、その代わりにGoogleアカウントのログインページにリダイレクトされてしまい、ユーザーは混乱して不満に思ってしまいます。
OAuth認証
OAuthは署名を必要とし、その署名はJavaScriptの環境ではセキュアな状態が保てませんので、JavaScriptではOAuthをネイティブサポートしていません。 しかし、ShindigにおいてはOAuthプロキシー用のJavaScriptサポートは入手可能です。 Shindigサーバーではガジェットに代わってOAuthリクエストを作成することができます。 OAuthプロキシーは現在iGoogleでサポートされています。 Googleデータ・クライアントとOAuthプロキシーを利用してガジェットを作成する方法について、詳しくはGoogleデータ・がジェットの作成を参照ください。
アカウントデータの取得
Data Export APIのJavaScriptライブラリーを使ってアカウントデータを取得するには、４つの基本的なしくみを利用すべきです：
- AnalyticsServiceオブジェクト
- アカウントフィードを取得するためのgetAccountFeed()メソッド
- フィードデータ内の要素をパースして表示するためのフィード・ハンドラ
- フィード・リクエストが失敗したときのためのエラー・ハンドラ
Data Export API用に、基本アカウント取得用のスクリプトのための完全動作するサンプル・ソースコードはJavaScript
examplesセクションにあります。 サンプルが見られるのに加え、WEBページにあなただけのAnalyticsアカウントデータを取得するためのインタラクティブなサンプルが利用できます。
AnalyticsServiceオブジェクト
AnalyticsServiceオブジェクトはAnalyticsからフィードデータを取得するために使う全てのメソッドへのアクセスを提供します。 詳しくはAnalyticsService
reference docを参照ください。 いろんなGoogleデータフィードへアクセスするために、あなたのアプリケーションでAnalyticsServiceクラスのオブジェクトを文字列で指定して新規生成する必要があります。 その文字列は必須で半角英数字で指定することができます。 お勧めとしてはあなたのアプリケーション名や企業名をつけるとよいでしょう。
var myService = new google.gdata.analytics.AnalyticsService('acmeSuperStatsApp1a');
getAccountFeedメソッド
The getAccountFeed method requests the account feed from the AnalyticsService
object. The account feed provides the list of profiles and accounts to which
a user has access.
getAccountFeedメソッドはAnalyticsServiceオブジェクトからアカウントフィードを要求します。 アカウントフィードでは、プロファイルのリストやユーザーがアクセス可能はアカウント情報が提供されます。
myService.getAccountFeed(myFeedUri, continuation, handleError);
あなたのアプリケーションで３つのパラメーターを指定します：
myFeedUri–Google Analyticsアカウントフィード・クエリーです。 アカウントフィード・クエリーについてはアカウントフィード・ドキュメントのAccount
Feed Requestを参照ください。
var myFeedUri = 'https://www.google.com/analytics/feeds/accounts/default';
continuation–リクエストが成功した場合に実効するJavaScript命令。
function continuation(myResultsFeedRoot) { . . .
handleError–エラーが発生した場合に実行するJavaScript命令。このパラメーターは任意です。
function handleError(e) {
リクエスト制御
もし、アカウントフィードのリクエストが成功したら、渡したパラメーターで指定された命令が実行され、JavaScriptクライアント・ライブラリーはアカウントフィードオブジェクトを帰します。（詳しくはAccount
Feedクラスリファレンスを参照ください） ここで、あなたが書いた命令はアカウントフィードオブジェクトからのフィードデータを取得し、フィードデータから結果を取得・表示するためのgetEntriesメソッドを使用します。 getEntriesメソッドはGoogle
Data atomフィード・オブジェクトから継承されています。 以下の例は、認証したユーザーのためにアカウント名、プロファイル名、プロファイルIDを表示しています。
function continuation(feedRoot) {
var entries = feedRoot.feed.getEntries();
if (entries.length == 0) return;
for (var i=0; i<entries.length; i++) {
var entry = entries[i];
document.write(
entry.getPropertyValue('ga:AccountName') +' '+
entry.getTitle().getText() +' '+
entry.getPropertyValue('ga:ProfileId'));
}
}
エラー・ハンドリング
もし、getAccountFeed()メソッドが失敗すると、errorHandlerで指定したパラメーターの命令が実行され、JavaScriptクライアント・ライブラリーはこの命令にたいしてエラーオブジェクトを渡します。 以下のシンプルなエラー・ハンドラー命令はウィンドウにエラーメッセージを表示します。
function errorHandler(error) {
alert("There was an error!n" + ((e.cause) ? e.cause.statusText : e.message));
}
2009-07-13