Google Analytics Tracking for Adobe Flash 関連ドキュメントの日本語訳

寺井周平

2008/11/26 14:03

GoogleAnalytics を利用して Flash コンテンツ上でのユーザ操作やアクセス解析をする方法は以前からありましたが、それをもっと簡単に使えるように Googleさんと Adobe さんが協力して整備して提供してくれることになりましたね。
それが先日発表された「Google Analytics Tracking for Adobe Flash」というコンポーネントです。

現状での参考資料は

の3ページっぽいのですが、試しに使ってみるついでにざっと訳してみました。一部途中だったりしますが共有させていただきます。僕はまだ一部機能のテストしかできていません（キャンペーンのトラック機能とか初めて知りました）ので、まだまだ訳の精度は低いかと思いますので、上記リンクの原文の参考程度に使っていただければと思います。注目点・使用感は別エントリにて。

（以下訳してみたドキュメント）

http://code.google.com/intl/ja/apis/analytics/docs/flashTrackingIntro.html ページの日本語訳

Google Analytics Tracking for Adobe Flash

「Google Analytics Tracking for Adobe Flash コンポーネント」を使えば Flash コンテンツ内に簡単に Google Analytics を埋め込むことができます。このコンポーネントには Javascript 版の Google Analytics と同様の機能が全て備わっており、最新の ga.js のトラッキングコードとの互換性も100%です。この Flash トラッキングコンポーネントは ActionScript 3 用にネイティブ化されているコンパイル済みのトラッキングオブジェクトであり、Flash や Flex 開発環境での解析・実行ができるのです。

The software for this component is developed under an open source initiative with Adobe Systems, Inc.
このプロジェクトへの参加貢献に興味がある開発者は、プロジェクトのホームページをご覧ください。

http://code.google.com/p/gaforflash/

Flash トラッキングを使う理由
開発環境のサポート
コンポーネントの仕組み
バージョン判定

Flash トラッキングを使う理由

この Google Analytics Tracking for Adobe Flash コンポーネントがなければ、Google Analytics を使って Adobe Flash コンテンツをトラッキングする際にいくつかの技術的なハードルにひっかかるかと思います。第一に、trackPageview() や trackEvent() といった ga.js で使われている解析用のメソッドを Flash 上で実行するために ga.js 用のカスタムインターフェースを用意する手間が必要になります。 In addition, you must also anticipate whether your Flash content will have access to the browser Document Object Model (DOM), since tracking fails for those objects where access to the DOM is denied (typically when your content resides on 3rd party sites). This involves understanding how to use the ExternalInfterface call in ActionScript 3 to access the browser DOM and to degrade when access is denied.

Google Analytics Tracking for Adobe Flash コンポーネントは Flash コンテンツのアクセス解析と DOM 操作を劇的に簡単にしてくれます。以下に挙げるようないろんな解析アプローチを Flash でも使えるようになるので便利です：

HTML ページ内に埋め込まれた Flash ウィジェット
スタンドアローンの Flex アプリケーション(?)や HTML ページ上のフルフラッシュサイト
開発者側ではユーザがそれ（swfファイル）がどこに置かれるかをコントロールできないような、配布形式による Flex/Flash ゲームやプログラム

Flash の解析はウェブサイトページの種類によっていくつか構造的なバリエーションがあることを覚えておいてください。解析の仕組みを知るためには、このプラグインがどのように動作するかを理解しておくことが重要です。更なる詳細情報はこのプロジェクトのデザインドキュメントをご覧いただくこともできます。

開発環境のサポート

Adobe Flash, Adobe Flex 両環境で Analytics Tracking for Flash を使った開発が可能です。環境ごとに異なるコンポーネントが必要で、http://code.google.com/p/gaforflash/　からダウンロードすることができます。これらのコンポーネントは ActionScript 3 で記述されており、使用に際しては各環境ごとに２つのアプローチから１つの方法を選んでいただけます：

Adobe Flash を使う場合

シンプルなコンポーネントをステージ上にドラッグ＆ドロップして追加配置し、コンポーネントインスペクタ上で設定する方法。
Flash Tracking libraries をライブラリに直接インポートし、コーディングする方法。

Adobe Flex を使う場合

MXML ファイル内で MXML コンポーネントを設定し使う方法。
Flash Tracking libraries をスクリプトタグあるいはAS3ファイルにインポートする方法。

トップに戻らない

コンポーネントの仕組み

Flash トラッキングコンポーネントを利用するには、Flash 内のビジュアルツール（IDE）を使ってもできますし、コードで直接オブジェクトを作ってトラッキングの設定をすることもできます。ビジュアルツールからでもコードからでも、どちらのアプローチでコンポーネントを設定する場合でも、以下の設定値は必要です：

web property ID—トラッキングコードを示す UA number とも呼ばれている値で、UA-xxxxx-yy のような値です。xとyは数値となります。あなたのアカウントとプロファイル情報を同一にしましょう。詳細は Web Property をご覧ください。
トラッキングモードの設定—ブリッジモードか AS3 モードのどちらかを選びます。このモードで解析用サーバとどうやって通信するかを決めます。詳細は以下をご覧ください。
デバッグモードの設定—使用環境やトラッキングモードに関わらず、デバッグモードにして正常にトラッキングできているかをテスト・検証できます。

トラッキングモード

あなたがどのように Flash コンテンツを提供するかにも関係してきますが Analytics for Flash component は、既存の解析方法を使って Flash コンテンツと通信する方法、あるいは直接 Analytics サーバと通信する方法、２つのやり方のどちらかで Analytics サーバと通信をおこないます。この２つのモードをそれぞれ「ブリッジモード」と「AS3 モード」といいます。機能的には両モードとも同様の解析をしてくれますし、あなたが Flash アプリケーションを作っている途中でモードをもう一方のモードに変更することも簡単です。さらには、ただ単にアクセス解析の通信を行うだけでなく、開発・検証用のデバッグモードも選んで利用することができるようになっています。

両モードとも、キャンペーンのトラッキングを正常に動作させるには allowscriptaccess 設定を always にしておくことが必須となります。このパラメーターで Flash トラッキングコードからウェブページ URL およびリファラー情報にアクセスできるようにしておくというわけです。allowscriptaccess 設定をしないと、アクセス解析コードは完全には機能しません。とはいえ、それでもほとんどのユーザーの行動データは取得できるのですが、Google Analytics campaign attribution model をうまく取得することはできないでしょう。

ブリッジモード

HTML ページと Flash コンテンツの両方を管理したい場合はこちらのモードを利用します。すでにウェブサイト上で Google Analytics (ga.js) を使って解析をしていて、そこにさらに Flash コンテンツ解析を追加したい時にはこのモードを選ぶとよいでしょう。このブリッジモードは ActionScript 3 インターフェースから ga.js コードを呼び出す仕組みを提供することで、Flash と JavaScript 間との通信を簡単に行えるモードなのです。つまり ActionScript 3 を呼び出すと、そこから解析用の JavaScript に通信し、トラッキングができるという仕組みです。

Google Analytics トラッキングコードへのコネクションは、web property ID パラメータを利用して、以下のどちらかの方法で確立されます：

Most common method. あなたのページ上に「pageTracker」という名前で既に独自の名前を持った Google Analytics Tracking Code オブジェクトが存在しているケースがあると思います。そのような場合はそのトラッキングオブジェクトまでの DOM の参照を設定してやれば大丈夫です。例えば、「pageTracker」という名前のオブジェクトがあるならば、「window.pageTracker」というコードを記述することによって、そのオブジェクトを参照してやればよいことになります。例えば、下のコードは ActionScript 3 & Adobe Flex 環境での使い方の記述例です：
```
tracker = new GATracker( this, "window.pageTracker", "Bridge", false );
```
これとは別の方法として、ページ上でページ解析用オブジェクトを生成していない場合、ご自分の web property ID をそのまま渡せば、JavaScript トラッキングコード用オブジェクトが自動的に生成されます。この方法を使う場合でも、あなたの HTML ページ上に存在している、ベースとなる ga.js の javascript ソースファイルへの参照は必要ですのでご注意ください。下のコードは ActionScript 3 & Adobe Flex 環境での使い方の記述例です：
```
tracker = new GATracker( this, "UA-12345-22", "Bridge", false );
```

ブリッジモードを正しく機能させるためには、ActionScript 3 内で ExternalInterface.avaliable の値を true に設定しておく必要があります。これは同時に、Flash を埋め込む HTML ページの allowScriptAccess 設定の値を always にしておく必要があるということです。ブリッジモードを動かすための HTML コードの記述例は以下のようになります：

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
     id="flex_component" width="800" height="600"
     codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
     <param name="movie" value="flex_component.swf" />

     <param name="quality" value="high" />
     <param name="bgcolor" value="#869ca7" />
     <param name="allowScriptAccess" value="always" />
     <embed src="flex_component.swf" quality="high" bgcolor="#869ca7"
         width="800" height="600" name="flex_component" align="middle"
         play="true"
         loop="false"
         quality="high"
         allowScriptAccess="always"
         type="application/x-shockwave-flash"
         pluginspage="http://www.adobe.com/go/getflashplayer">
      </embed>
</object>

トップに戻らない

AS3 モード

Adobe Flash ActionScript 3 コードで制御し、かつ、作った Adobe Flash アプリケーションを動かすホスト環境の制御をしない時はこちらのモードをお使いください。例えば、いろんなサイトにまたがって配布されるような Flash　コンテンツを開発する場合は、この AS3 モードを使うとよいでしょう。AS3 モードは ga.js トラッキングコードからは完全に独立しており、アクセス解析に必要な全機能が（AS3 モード内に）備え付けられています。このモードの場合は別個に ga.js を用意しなくてもよいということです。さらに、AS3 モードは訪問者のセッション情報の追跡を Flash storage mechanism を使っておこないます。

「language」等のいくつかの DOM パラメータに対して、AS3 コンポーネントはブラウザから値を取得しようとします。その値が存在しない場合は、If the values are not present, the component either uses the Flash equivalent value or defaults to no.

開発時の動作確認・検証

Google Analytics Tracking for Adobe Flash component では、簡単に動作確認・検証ができるように「デバッグモード」が用意されています。この機能をオンにしておけば、トラッキングの全データが、Analytics サーバにではなく、画面上のテキストボックスに直接表示されるようになります。このモードでは、通常であればサーバに集計されてしまうデータを、リアルタイムに確認することができるのです。この機能はThis feature also helps keep test data outside of your production data. この検証のための機能は、コンポーネントインスペクタ上で visualDebug オプションを true に設定することで利用できます。

サンプル

開発環境ごとによるトラッキングの実装例の詳細については以下のリンクを参照ください：

Flash

Flex

バージョン判定

http://code.google.com/p/gaforflash/downloads/list にて最新バージョンのトラッキング用コンポーネントを ZIP 形式にて入手できるようになっています。全種コンポーネントと関連ドキュメントが含まれています。なお、中身のコードのバージョン番号はダウンロードファイル名にも明記されています。

また、以下のコードを記述すれば現在お使いのコンポーネントのバージョン番号を出力パネルで確認することができます。

import com.google.analytics.API; 
trace(API.version);

トップに戻らない

http://code.google.com/intl/ja/apis/analytics/docs/flashTrackingSetupFlash.html ページの日本語訳

Adobe Flash でのセットアップ

このドキュメントでは Adobe Flash 開発環境で Google Analytics Tracking for Adobe Flash を使うための設定方法を解説します。

コンポーネントファイルを取得する
Analytics コンポーネントを使う
AnalyticsLibrary コンポーネントを使う

コンポーネントファイルを取得する

Flash トラッキング用のコンポーネントは zip ファイルに圧縮されて配布されていますので http://code.google.com/p/gaforflash/downloads/list よりダウンロードしてください。

同梱されている readme.txt ファイルに従い、Flash コンポーネントを所定の位置に設置します。

Flash CS3 が起動している場合は、アプリケーションを終了させておいてください。
以下の場所に「Google」ディレクトリを作成してください：
- Windows の場合:C:\Program Files\Adobe\ Adobe Flash CS3\language\Configuration\Components
- Mac OS X の場合:Macintosh HD/Applications/Adobe Flash CS3/Configuration/Components
コンポーネントの ZIP ファイルを解凍し、さきほどステップ2で作成したディレクトリに以下の2ファイルをコピーしてください：
- lib/analytics_flash.swc — Analytics Component
- lib/analytics.swc — Analytics Library Component

両コンポーネントとも同様の働きをするのですが、開発スタイルに応じて使い分けられるような仕組みになっています。

Analytics component。ActionScript 3 に慣れていない Flash コンテンツ製作者はこちらのコンポーネントを使いましょう。The Analytics component はトラッキング用のパッケージです。このコンポーネントをステージ上に直接ドラッグ＆ドロップし、コンポーネントインスペクタにちょっと設定するだけで、and you're ready to tag your controls with Analytics tracking.

AnalyticsLibrary component。ActionScript 3 に慣れている人はこちらの AnalyticLibrary component を使うといいでしょう。このコンポーネントを Flash のライブラリウィンドウにドラッグし、トラッキング用のクラスを import して ActionScript のコードに組み込みます。

Using The Analytics Component

Analytics component を使って解析を行う場合は analytics_flash.swc を利用することになります。コンポーネントを適切なコンポーネントフォルダに設置しておけば、以降はコンポーネントパネル（ウィンドウ - コンポーネント）上に表示されます。

コンポーネントをステージ上にドラッグ＆ドロップし、プロパティパネル上でインスタンス名を設定します。
コンポーネントインスペクタパネル（ウィンドウ - コンポーネントインスペクタ）上でコンポーネントの設定をします：
- Analytics web property ID を設定
- ブリッジモードか AS3 モードかを選択
- デバッグ用画面の表示・非表示を選択
In your ActionScript code, add the standard GA tracking calls to the instance of the component you just created.

Flash 上でビジュアルコンポーネントを動かすアプローチになりますので、その場合の通例に従えば、Flash コンテンツの第２フレーム以降から解析をし始めるのが一般的です。もし、第１フレームから解析をしたいのであれば、解析の命令の呼び出しをイベントハンドラ内で行い、コンポーネントを完全に初期化完了させておくようにしてください。

A Simple Analytics Flash Component Example

以下のコードは Flash 内に置かれたボタンをユーザがクリックしたことをトラッキングするための記述例です。このサンプルでは「playGame」というのがボタンのインスタンス名です。ボタンがクリックされた onButtonClick イベントが呼び出され、その中で trackPageview() メソッドが実行されます。これによって「/myGame1」という架空（実際にHTMLページとしては存在しない）のページのページビューが加算される仕組みになっています。

playGame.addEventListener( MouseEvent.CLICK, onButtonClick ); 
function onButtonClick( event:Event ):void 
{     
  tracker.trackPageview( "/myGame1"); 
}

トップに戻らない

AnalyticsLibrary コンポーネントを使う場合

AnalyticsLibrary component を使って解析を行う場合は analytics.swc ファイルを利用することになります。このコンポーネントを使って、AS3 で直接トラッキング用オブジェクトのインスタンスを作成します。AnalyticsLibrary component を適切な位置に設置しておけば、以降はコンポーネントパネルに表示されるようになります。あとはそのコンポーネントをコンポーネントパネルからライブラリウィンドウドラッグ＆ドロップし、ActionScript 上で import して使うことになります。

トラッキングオブジェクトの初期化

Adobe Flash 環境をお使いの場合、以下のパラメータを設定してトラッキング用のオブジェクトを初期化してください：

カレントディスプレイオブジェクトへの参照。下の例での this はディスプレイオブジェクトを指しています。
web property ID. web property ID はユニークな文字列です。Flash コンテンツ上でのトラッキングを有効化し、あなたの Analytics アカウント内で正しく集計するために使われます。
トラッキングモード：Bridge か AS3 というパラメータのみ有効です。
デバッグモード. 最終仕上げ時には false に設定、開発途中・チェック検証の際は true に設定してください。

AnalyticsLibrary の簡単な使用例

次の例では、「playGame」というムービークリップがステージ上にあるとします。「tracker」という名前のトラッキング用オブジェクトを新規作成し、マウスクリックを監視させるイベントハンドラを用意します。ボタンが押されたタイミングでonButtonClick 関数が呼び出されます。クリックの度に trackPageview() メソッドが「/myGame1」という架空（実際にHTMLページとしては存在しない）のページのページビューを加算するようになっています。

import com.google.analytics.AnalyticsTracker; 
import com.google.analytics.GATracker; 
var tracker:AnalyticsTracker = new GATracker( this, "UA-111-222", "AS3", true ); 
playGame.addEventListener( MouseEvent.CLICK, onButtonClick ); 
function onButtonClick ( event:Event ):void 
{
   tracker.trackPageview("/myGame1"); 
}

トップに戻らない

http://code.google.com/intl/ja/apis/analytics/docs/flashTrackingSetupFlex.html ページの日本語訳

Adobe Flex でのセットアップ

このドキュメントでは Adobe Flex 開発環境で Google Analytics Tracking for Adobe Flash を利用するために必要な設定方法を解説します。

トラッキング用ライブラリの取得
プロジェクトにコードを記述していく
A Flex MXML Component 使用例
A Flex ActionScript 3 使用例

トラッキング用ライブラリの取得

http://code.google.com/p/gaforflash/downloads/list から ZIP 形式にてダウンロードしてください。readme.txt ファイルの説明に従い、Flex コンポーネントにインストールしてください。 Flash 開発環境用の Analytics Flash components とは異なり、ダウンロードファイルの中には /lib/analytics_flex.swc というライブラリファイルが1つだけ入っています。

プロジェクトにコードを記述していく

プロジェクトでトラッキング用コードを使う前に、ダウンロードした SWC ファイルをプロジェクトのリソースとしてリンクしておく必要があります。

Project->Properties を選択。 A Properties dialog box appears for your project.
Click on Flex Build Path and select the Library Path tab.
Click Add SWC... within the Library Path pane. An Add SWC dialog box appears.
Navigate to the location where you unzipped the Google Analytics API and select the lib/analytics.swc file and click OK.
Or, just drop the analytics.swc file into your Flex project /libs directory.

Flex - MXML コンポーネント使用例

以下の例は MXML ファイル中のボタンに対してトラッキングを仕込んだ場合のサンプルです。MXML コンポーネントを初期化するには、次のようにしてください：

XML 名前空間（ネームスペース）パラメータの設定. XML 名前空間のパラメータを設定してください：namespace parameter of your tracking object as follows: xmlns:analytics="com.google.analytics.components.*"
オブジェクト名を設定。下の例では id パラメータをtracker と命名しています。
account パラメータに web property ID を設定します。web property ID とは、Flash コンテンツ解析を行い、その解析データをあなたの適切な Analytics アカウントで集計するために必要なユニークな文字列です。
mode パラメータ でトラッキングモードを指定します。. パラメータを Bridge にすれば、MXML 上でシンプル（簡単）にトラッキングを実装できます。ActionScript3 と連携させるようなコーディングがしたい場合はパラメーターを AS3 にしてご利用ください。 AS3 モードを使えば、GA トラッキングクラスが全て import され利用できますので、独自にトラッキング用オブジェクトを生成・設定することができます。
visualDebug パラメータにはデバッグモードを指定します。. Use true プログラム上でデバッグと検証を行う場合は true に、逆に、最終ビルド時（完成時）には false にしましょう。

このサンプルでは mybutton というボタンをステージに追加しています。Flex tracking component 部分は、tracker という名前でインスタンスを作り、諸々のパラメータを設定しています。最後に、mybutton に onButtonClick クリックイベントを設定しています。ボタンがクリックされると、/hello world という架空のページビューが1加算されるようになっています。

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
    xmlns:mx="http://www.adobe.com/2006/mxml"
    layout="absolute" width="800" height="600"
    >

    <mx:Script>
            public function onButtonClick():void
            {
                tracker.trackPageview( "/hello world" );
            }
    </mx:Script>

    <analytics:FlexTracker
        xmlns:analytics="com.google.analytics.components.*"
        id="tracker"
        account="UA-111-222"
        mode="AS3"
        visualDebug="false"
     />

    <mx:Button id="mybutton" label="hello world" click="onButtonClick()" />

</mx:Application>

トップには戻らない

Flex - ActionScript 3 使用例

より込み入ったことをしたい場合など、ActionScript から直接 ActionScript 3 ネイティブのトラッキング用クラスを直接呼び出す必要が出てくるかと思います。このサンプルでは MXML ファイル内に記述していますが、<MX:script> タグ内で全てのトラッキング設定をしていることが分かると思います。もちろんこの手法はこれ以外の ActionScript 3 プロジェクトでも使える手法です。

このサンプルではステージ上に mybutton を追加し、スクリプトタグ内で2つのライブラリを import しています：

com.google.analytics.GATracker; //トラッキング用クラス本体
com.google.analytics.AnalyticsTracker; //GATracker クラスを実行するためのインターフェース

ライブラリをインポートした後、tracker というトラッキング用の変数を用意しています。アプリケーションがステージ上に生成されたタイミングで onComplete が呼び出され、トラッキング用オブジェクトのインスタンスが生成されます。GATracker オブジェクトのインスタンス生成の際に必要な4つのパラメータは：

カレントオブジェクトへの参照。このサンプルでは、this はディスプレイオブジェクトへの参照を指します。
web property ID。 web property ID とは、Flash コンテンツ解析を行い、そのプロファイル情報をあなたの適切な Analytics アカウントで集計するために必要なユニークな文字列です。
トラッキングモード。 Bridge か AS3 かをパラメータ設定してください。
デバッグモード。最終完成時は debug の値を false に、それまでの検証・デバッグ時には true にしておくとよいでしょ。

最後に、myButton をクリックすると onButtonClick メソッドが呼び出されて、トラッキングオブジェクトが架空のページビューを解析するようにしています。

アプリケーションが実行されると、ユーザがボタンをクリックするたびに "hello world" という架空のページが見られたという風に扱われ、その情報が Google Analytics tracking servers に送信されます。

<?xml version="1.0" encoding="utf-8"?>
<mx:Application
    xmlns:mx="http://www.adobe.com/2006/mxml"
    layout="absolute"
    width="800" height="600"
    addedToStage="onComplete()"
    >
    <mx:Script>
        <![CDATA[
            import com.google.analytics.GATracker;
            import com.google.analytics.AnalyticsTracker;

            public var tracker:AnalyticsTracker;

            private function onComplete():void
            {
                tracker = new GATracker( this, "UA-111-222", "AS3", false );
            }

            public function onButtonClick():void
            {
                tracker.trackPageview( "/hello/world" );
            }

        ]]>
    </mx:Script>

    <mx:Button id="mybutton" label="hello world" click="onButtonClick()" />

</mx:Application>

トップには戻らない