AIR.SWF ブラウザー API

シームレスインストールの badge.swf のカスタマイズ

SDK に付属している badge.swf ファイルの使用に加え、ブラウザーページで使用できる独自の SWF ファイルを作成できます。カスタム SWF ファイルは、次の方法でランタイムと対話できます。

これらの機能はすべて、adobe.com: air.swf にホストされている SWF ファイル内の API を呼び出して使用できます。badge.swf をカスタマイズして、独自の SWF ファイルから air.swf API を呼び出すことができます。

また、ブラウザーで実行中の SWF ファイルは、LocalConnection クラスを使用して実行されている AIR アプリケーションと通信できます。詳しくは、「Flash Player および AIR の他のインスタンスとの通信」(ActionScript 開発者用)、または「Flash Player および AIR の他のインスタンスとの通信」(HTML 開発者用)を参照してください。

重要: Windows または Mac OS では、この節で説明する機能(および air.swf ファイルの API)を使用するには、エンドユーザーが Adobe® Flash® Player 9 アップデート 3 以降を Web ブラウザーでインストールしている必要があります。Linux では、シームレスインストール機能の実行に Flash Player 10(バージョン 10.0.12.36 以降)が必要です。インストールされている Flash Player のバージョンを確認し、Flash Player の必要なバージョンがインストールされていない場合は、ユーザーに代替のインターフェイスを提供するコードを作成できます。例えば、古いバージョンの Flash Player がインストールされている場合は、(badge.swf ファイルまたは air.swf API を使用してアプリケーションをインストールするのではなく)AIR ファイルのダウンロードバージョンへのリンクを提供します。

badge.swf ファイルを使用した AIR アプリケーションのインストール

AIR SDK および Flex SDK には、badge.swf ファイルが含まれています。このファイルを使用すると、シームレスインストール機能を簡単に使用できます。badge.swf では、ランタイムと AIR アプリケーションを Web ページのリンクからインストールできます。Web サイトに配布するための badge.swf ファイルとそのソースコードが提供されます。

Web ページへの badge.swf ファイルの埋め込み

  1. AIR SDK または Flex SDK の samples/badge ディレクトリにある次のファイルを探し、Web サーバーに追加します。

    • badge.swf

    • default_badge.html

    • AC_RunActiveContent.js

  2. default_badge.html ページをテキストエディターで開きます。

  3. default_badge.html ページの AC_FL_RunContent() JavaScript 関数で、FlashVars パラメーター定義を次のように調整します。

    パラメーター

    説明

    appname

    ランタイムがインストールされていないときに、SWF ファイルよって表示されるアプリケーションの名前。

    appurl

    (必須)ダウンロードする AIR ファイルの URL。相対 URL ではなく、絶対 URL を使用する必要があります。

    airversion

    (必須)ラインタイム 1.0 バージョンの場合は、このパラメーターに 1.0 を設定します。

    imageurl

    badge に表示される画像(オプション)の URL。

    buttoncolor

    ダウンロードボタンの色(FFCC00 のように、16 進数で指定します)。

    messagecolor

    ランタイムがインストールされていないときにボタンの下に表示されるテキストメッセージの色(FFCC00 のように、16 進数で指定します)。

  4. badge.swf ファイルの最小サイズは、217 ピクセル(幅)x 180 ピクセル(高さ)です。AC_FL_RunContent() 関数の width パラメーターと height パラメーターの値を、ニーズに合わせて調整します。

  5. default_badge.html ファイルの名前を変更し、ニーズに合わせてそのコードを調整します(または別の HTML ページにコードを含めます)。

注意: badge.swf ファイルを読み込む HTML embed タグに対しては、wmode 属性は設定せず、デフォルト("window")のままにしておいてください。デフォルト以外の wmode 設定を使用すると、システムによってはインストールが失敗します。また、他の wmode 設定を使用するとエラー「エラー #2044: ハンドルされていない ErrorEvent : text=Error #2074: ステージが小さすぎるため、ダウンロード UI を格納できません」が発生します。

また、badge.swf ファイルを編集および再コンパイルすることもできます。詳しくは、badge.swf ファイルの変更を参照してください。

Web ページのシームレスインストールリンクからの AIR アプリケーションのインストール

ページにシームレスインストールリンクを追加すると、SWF ファイル内のリンクをクリックして AIR アプリケーションをインストールできます。

  1. Flash Player(Windows および Mac OS ではバージョン 9 アップデート 3 以降、Linux ではバージョン 10)がインストールされている Web ブラウザーで HTML ページへ移動します。

  2. Web ページで、badge.swf ファイル内のリンクをクリックします。

    • ランタイムを既にインストールしている場合は、次の手順にスキップします。

    • ランタイムをインストールしていない場合は、インストールするかどうかを確認するダイアログボックスが表示されます。ランタイムをインストールして(Adobe AIR のインストールを参照)、次の手順に進みます。

  3. インストールウィンドウで、デフォルトの設定を選択した状態のまま、「続行」をクリックします。

    Windows コンピューターでは、AIR が次の動作を自動的に行います。

    • c:¥Program Files¥ にアプリケーションをインストールします。

    • アプリケーションのデスクトップショートカットを作成します。

    • スタートメニューショートカットを作成します。

    • 「プログラムの追加と削除」コントロールパネルにアプリケーションのエントリを追加します。

    Mac OS では、インストーラーによってアプリケーションがアプリケーションディレクトリ(Mac OS の /アプリケーションディレクトリなど)に追加されます。

    Linux コンピューターでは、AIR が次の動作を自動的に行います。

    • アプリケーションを /opt にインストールします。

    • アプリケーションのデスクトップショートカットを作成します。

    • スタートメニューショートカットを作成します。

    • アプリケーションのエントリをシステムパッケージマネージャーに追加します。

  4. 必要なオプションを選択し、「インストール」ボタンをクリックします。

  5. インストールが完了したら、「完了」をクリックします。

badge.swf ファイルの変更

Flex SDK および AIR SDK には badge.swf ファイル用のソースファイルが用意されています。SDK の samples/badge フォルダーには、次のファイルが含まれています。

ソースファイル

説明

badge.fla

badge.swf ファイルのコンパイルに使用するソースの Flash ファイル。badge.fla ファイルは、SWF 9 ファイル(Flash Player に読み込み可能)にコンパイルされます。

AIRBadge.as

basdge.fla ファイルで使用される基本クラスを定義する ActionScript 3.0 クラス。

Flash Professional を使用して、badge.fla ファイルの仮想インターフェイスを再デザインできます。

AIRBadge クラスで定義される AIRBadge() コンストラクター関数は、http://airdownload.adobe.com/air/browserapi/air.swf にホストされている air.swf ファイルを読み込みます。air.swf ファイルには、シームレスインストール機能を使用するためのコードが含まれています。

onInit() メソッド(AIRBadge クラス内)は、air.swf ファイルが正常に読み込まれると呼び出されます。

private function onInit(e:Event):void { 
    _air = e.target.content; 
    switch (_air.getStatus()) { 
        case "installed" : 
            root.statusMessage.text = ""; 
            break; 
        case "available" : 
            if (_appName && _appName.length > 0) { 
                root.statusMessage.htmlText = "<p align='center'><font color='#"  
                        + _messageColor + "'>In order to run " + _appName +  
                        ", this installer will also set up Adobe® AIR®.</font></p>"; 
            } else { 
                root.statusMessage.htmlText = "<p align='center'><font color='#"  
                        + _messageColor + "'>In order to run this application, " 
                        + "this installer will also set up Adobe® AIR®.</font></p>"; 
            } 
            break; 
        case "unavailable" : 
            root.statusMessage.htmlText = "<p align='center'><font color='#"  
                        + _messageColor  
                        + "'>Adobe® AIR® is not available for your system.</font></p>"; 
            root.buttonBg_mc.enabled = false; 
            break; 
    } 
}

コードでは、グローバルな _air 変数が、読み込んだ air.swf ファイルのメインクラスに設定されます。このクラスには、badge.swf ファイルがシームレスインストール機能を呼び出す際にアクセスする次のパブリックメソッドが含まれています。

メソッド

説明

getStatus()

コンピューターにランタイムがインストールされているか(またはインストール可能か)どうかを確認します。詳しくは、ランタイムがインストールされているかどうかの確認を参照してください。
  • runtimeVersion - インストールするアプリケーションに必要なランタイムのバージョンを示すストリング(「1.0.M6」など)。

installApplication()

指定されたアプリケーションをユーザーのマシンにインストールします。詳しくは、ブラウザーからの AIR アプリケーションのインストールを参照してください。

  • url - URL を定義するストリング。URL のパスには、相対 URL ではなく、絶対 URL を使用する必要があります。

  • runtimeVersion - インストールするアプリケーションに必要なランタイムのバージョンを示すストリング(「2.5.」など)。

  • arguments - インストール時にアプリケーションが起動する場合にアプリケーションに渡される引数。アプリケーション記述ファイルで allowBrowserInvocation エレメントが true に設定されている場合、アプリケーションはインストール時に起動します(アプリケーション記述ファイルについて詳しくは、AIR アプリケーション記述ファイルを参照してください)。ブラウザーからのシームレスインストールによりアプリケーションが起動している場合(インストール時に起動することをユーザーが選択している場合)、アプリケーションの NativeApplication オブジェクトは、引数が渡されている場合にのみ BrowserInvokeEvent オブジェクトを送出します。アプリケーションに渡すデータのセキュリティ上の影響を考慮します。詳しくは、インストール済み AIR アプリケーションのブラウザーからの起動を参照してください。

url および runtimeVersion の設定は、コンテナの HTML ページの FlashVars 設定を通じて SWF ファイルに渡されます。

インストール時にアプリケーションが自動的に起動する場合は、LocalConnection 通信を使用して、インストールされたアプリケーションの呼び出し時に badge.swf ファイルと通信させることができます。詳しくは、「Flash Player および AIR の他のインスタンスとの通信」(ActionScript 開発者用)、または「Flash Player および AIR の他のインスタンスとの通信」(HTML 開発者用)を参照してください。

また、air.swf ファイルの getApplicationVersion() メソッドを呼び出して、アプリケーションがインストールされているかどうかを確認することもできます。このメソッドは、アプリケーションのインストールプロセスの前、またはインストールの開始後に呼び出すことができます。詳しくは、AIR アプリケーションがインストールされているかどうかの Web ページからの確認を参照してください。

air.swf ファイルの読み込み

air.swf ファイルの API を使用する独自の SWF ファイルを作成し、ブラウザー内の Web ページからランタイムおよび AIR アプリケーションを操作できます。air.swf ファイルは、http://airdownload.adobe.com/air/browserapi/air.swf にホストされています。SWF ファイルから air.swf API を参照するには、air.swf ファイルを SWF ファイルと同じアプリケーションドメインに読み込みます。次のコードは、読み込み中の SWF ファイルのアプリケーションドメインに air.swf ファイルを読み込む例を示しています。

var airSWF:Object; // This is the reference to the main class of air.swf 
var airSWFLoader:Loader = new Loader(); // Used to load the SWF 
var loaderContext:LoaderContext = new LoaderContext();  
                                // Used to set the application domain  
 
loaderContext.applicationDomain = ApplicationDomain.currentDomain; 
 
airSWFLoader.contentLoaderInfo.addEventListener(Event.INIT, onInit); 
airSWFLoader.load(new URLRequest("http://airdownload.adobe.com/air/browserapi/air.swf"),  
                    loaderContext); 
 
function onInit(e:Event):void  
{ 
    airSWF = e.target.content; 
}

air.swf ファイルが読み込まれたら(Loader オブジェクトの contentLoaderInfo オブジェクトが init イベントを送出した後)、以下の節で説明している air.swf API のいずれかを呼び出すことができます。

注意: AIR SDK および Flex SDK に付属している badge.swf ファイルでは、air.swf ファイルを自動的に読み込みます。badge.swf ファイルを使用した AIR アプリケーションのインストールを参照してください。この節に示す手順は、air.swf ファイルを読み込む独自の SWF ファイルの作成に適用されます。

ランタイムがインストールされているかどうかの確認

SWF ファイルでは、http://airdownload.adobe.com/air/browserapi/air.swf から読み込んだ air.swf ファイルで getStatus() メソッドを呼び出してランタイムがインストールされているかどうかを確認できます。詳しくは、air.swf ファイルの読み込みを参照してください。

air.swf ファイルが読み込まれると、SWF ファイルでは air.swf ファイルの getStatus() メソッドを呼び出すことができます。

var status:String = airSWF.getStatus();

getStatus() メソッドは、コンピューター上のランタイムのステータスに基づいて、次のストリング値のいずれか 1 つを返します。

ストリング値

説明

"available"

ランタイムはコンピューターにインストールできますが、現在インストールされていません。

"unavailable"

ランタイムはこのコンピューターにインストールできません。

"installed"

ランタイムはこのコンピューターにインストールされています。

getStatus() メソッドでは、必要なバージョンの Flash Player(Windows および Mac OS ではバージョン 9 アップデート 3 以降、Linux ではバージョン 10)がブラウザーにインストールされていない場合、エラーがスローされます。

AIR アプリケーションがインストールされているかどうかの Web ページからの確認

SWF ファイルでは、http://airdownload.adobe.com/air/browserapi/air.swf から読み込んだ air.swf ファイルの getApplicationVersion() メソッドを呼び出して、AIR アプリケーション(対応するアプリケーション ID と発行者 ID を持つ)がインストールされているかどうかを確認できます。詳しくは、air.swf ファイルの読み込みを参照してください。

air.swf ファイルが読み込まれると、SWF ファイルでは air.swf ファイルの getApplicationVersion() メソッドを呼び出すことができます。

var appID:String = "com.example.air.myTestApplication"; 
var pubID:String = "02D88EEED35F84C264A183921344EEA353A629FD.1"; 
airSWF.getApplicationVersion(appID, pubID, versionDetectCallback); 
 
function versionDetectCallback(version:String):void 
{ 
    if (version == null) 
    { 
        trace("Not installed."); 
        // Take appropriate actions. For instance, present the user with 
        // an option to install the application. 
    } 
    else 
    { 
        trace("Version", version, "installed."); 
        // Take appropriate actions. For instance, enable the 
        // user interface to launch the application. 
    } 
}

getApplicationVersion() メソッドには、次のパラメーターがあります。

パラメーター

説明

appID

アプリケーションのアプリケーション ID。詳しくは、idを参照してください。

pubID

アプリケーションの発行者 ID。詳しくは、publisherIDを参照してください。対象のアプリケーションに発行者 ID がない場合は、pubID パラメーターを空のストリング("")に設定します。

callback

ハンドラー関数として処理されるコールバック関数。getApplicationVersion() メソッドは非同期に動作し、インストールされているバージョンを検出するとき(またはインストールされているバージョンがないことを検出するとき)に、このコールバックメソッドが呼び出されます。コールバックメソッドの定義では、1 つのパラメーター(インストールされているアプリケーションのバージョンストリングに設定されているストリング)を含める必要があります。アプリケーションがインストールされていない場合は、前のコード例に示したように null 値が関数に渡されます。

getApplicationVersion() メソッドでは、必要なバージョンの Flash Player(Windows および Mac OS ではバージョン 9 アップデート 3 以降、Linux ではバージョン 10)がブラウザーにインストールされていない場合、エラーがスローされます。

注意: AIR 1.5.3 では、発行者 ID の使用は推奨されません。発行者 ID はアプリケーションに自動的に割り当てられなくなりました。下位互換性を維持するため、アプリケーションでは引き続き発行者 ID を指定することができます。

ブラウザーからの AIR アプリケーションのインストール

SWF ファイルでは、http://airdownload.adobe.com/air/browserapi/air.swf から読み込んだ air.swf ファイルで installApplication() メソッドを呼び出して AIR アプリケーションをインストールできます。詳しくは、air.swf ファイルの読み込みを参照してください。

air.swf ファイルが読み込まれると、SWF ファイルでは、次のコードに示すように、air.swf ファイルの installApplication() メソッドを呼び出すことができます。

var url:String = "http://www.example.com/myApplication.air"; 
var runtimeVersion:String = "1.0"; 
var arguments:Array = ["launchFromBrowser"]; // Optional 
airSWF.installApplication(url, runtimeVersion, arguments); 

installApplication() メソッドは、指定されたアプリケーションをユーザーのマシンにインストールします。このメソッドのパラメーターは次のとおりです。

パラメーター

説明

url

インストールする AIR ファイルの URL を定義するストリング。URL のパスには、相対 URL ではなく、絶対 URL を使用する必要があります。

runtimeVersion

インストールするアプリケーションに必要なランタイムのバージョンを示すストリング(「1.0」など)。

arguments

インストール時にアプリケーションが起動する場合にアプリケーションに渡される引数の配列。引数内で認識される文字は半角英数のみです。その他の値を渡す必要がある場合は、何らかのエンコード方式を使用してください。

アプリケーション記述ファイルで allowBrowserInvocation エレメントが true に設定されている場合、アプリケーションはインストール時に起動します(アプリケーション記述ファイルについて詳しくは、AIR アプリケーション記述ファイルを参照してください)。ブラウザーからのシームレスインストールによりアプリケーションが起動している場合(インストール時に起動することをユーザーが選択している場合)、アプリケーションの NativeApplication オブジェクトは、引数が渡されている場合にのみ BrowserInvokeEvent オブジェクトを送出します。詳しくは、インストール済み AIR アプリケーションのブラウザーからの起動を参照してください。

installApplication() メソッドは、マウスのクリックなどのユーザーイベントのイベントハンドラーで呼び出されたときにのみ動作できます。

installApplication() メソッドでは、必要なバージョンの Flash Player(Windows および Mac OS ではバージョン 9 アップデート 3 以降、Linux ではバージョン 10)がブラウザーにインストールされていない場合、エラーがスローされます。

Mac OS でアプリケーションのアップデートバージョンをインストールするには、アプリケーションディレクトリにインストールするための適切なシステム権限(アプリケーションでランタイムをアップデートする場合は管理権限も)が必要です。Windows では、管理権限が必要です。

また、air.swf ファイルの getApplicationVersion() メソッドを呼び出して、アプリケーションが既にインストールされているかどうかを確認することもできます。このメソッドは、アプリケーションのインストールプロセスの開始前、またはインストールの開始後に呼び出すことができます。詳しくは、AIR アプリケーションがインストールされているかどうかの Web ページからの確認を参照してください。実行中のアプリケーションは、LocalConnection クラスを使用してブラウザーで SWF コンテンツと通信できます。詳しくは、「Flash Player および AIR の他のインスタンスとの通信」(ActionScript 開発者用)、または「Flash Player および AIR の他のインスタンスとの通信」(HTML 開発者用)を参照してください。

インストール済み AIR アプリケーションのブラウザーからの起動

ブラウザー呼び出し機能を使用するには(ブラウザーから起動できるようにするには)、対象アプリケーションのアプリケーション記述ファイルに次の設定を含める必要があります。

<allowBrowserInvocation>true</allowBrowserInvocation>

アプリケーション記述ファイルについて詳しくは、AIR アプリケーション記述ファイルを参照してください。

ブラウザーの SWF ファイルでは、http://airdownload.adobe.com/air/browserapi/air.swf から読み込んだ air.swf ファイルで launchApplication() メソッドを呼び出して AIR アプリケーションを起動できます。詳しくは、air.swf ファイルの読み込みを参照してください。

air.swf ファイルが読み込まれると、SWF ファイルでは、次のコードに示すように、air.swf ファイルの launchApplication() メソッドを呼び出すことができます。

var appID:String = "com.example.air.myTestApplication"; 
var pubID:String = "02D88EEED35F84C264A183921344EEA353A629FD.1"; 
var arguments:Array = ["launchFromBrowser"]; // Optional 
airSWF.launchApplication(appID, pubID, arguments);

launchApplication() メソッドは、air.swf ファイルのトップレベルで定義されます(ユーザーインターフェイス SWF ファイルのアプリケーションドメインに読み込まれます)。このメソッドを呼び出すと、AIR で指定されたアプリケーションが起動します(アプリケーションがインストール済みで、アプリケーション記述ファイルの allowBrowserInvocation 設定でブラウザー呼び出しが許可されている場合)。このメソッドのパラメーターは次のとおりです。

パラメーター

説明

appID

起動するアプリケーションのアプリケーション ID。詳しくは、idを参照してください。

pubID

起動するアプリケーションの発行者 ID。詳しくは、publisherIDを参照してください。対象のアプリケーションに発行者 ID がない場合は、pubID パラメーターを空のストリング("")に設定します。

arguments

アプリケーションに渡す引数の配列。アプリケーションの NativeApplication オブジェクトは、引数のプロパティがこの配列に設定されている BrowserInvokeEvent イベントを送出します。引数内で認識される文字は半角英数のみです。その他の値を渡す必要がある場合は、何らかのエンコード方式を使用してください。

launchApplication() メソッドは、マウスのクリックなどのユーザーイベントのイベントハンドラーで呼び出されたときにのみ動作できます。

launchApplication() メソッドでは、必要なバージョンの Flash Player(Windows および Mac OS ではバージョン 9 アップデート 3 以降、Linux ではバージョン 10)がブラウザーにインストールされていない場合、エラーがスローされます。

アプリケーション記述ファイルで allowBrowserInvocation エレメントが false に設定されている場合、launchApplication() メソッドを呼び出してもアプリケーションは起動されません。

アプリケーションを起動するためのユーザーインターフェイスを示す前に、air.swf ファイルで getApplicationVersion() メソッドを呼び出す必要があります。詳しくは、AIR アプリケーションがインストールされているかどうかの Web ページからの確認を参照してください。

ブラウザー呼び出し機能によりアプリケーションが呼び出されると、アプリケーションの NativeApplication オブジェクトは BrowserInvokeEvent オブジェクトを送出します。詳しくは、「ブラウザーからの AIR アプリケーションの呼び出し」(ActionScript 開発者用)または「ブラウザーからの AIR アプリケーションの呼び出し」(HTML 開発者用)を参照してください。

ブラウザー呼び出し機能を使用する場合は、セキュリティ上の影響を考慮してください。セキュリティ上の影響については、「ブラウザーからの AIR アプリケーションの呼び出し」(ActionScript 開発者用)および「ブラウザーからの AIR アプリケーションの呼び出し」(HTML 開発者用)で説明しています。

実行中のアプリケーションは、LocalConnection クラスを使用してブラウザーで SWF コンテンツと通信できます。詳しくは、「Flash Player および AIR の他のインスタンスとの通信」(ActionScript 開発者用)、または「Flash Player および AIR の他のインスタンスとの通信」(HTML 開発者用)を参照してください。

注意: AIR 1.5.3 では、発行者 ID の使用は推奨されません。発行者 ID はアプリケーションに自動的に割り当てられなくなりました。下位互換性を維持するため、アプリケーションでは引き続き発行者 ID を指定することができます。