PDF (5.2M)

從網頁安裝及執行 AIR 應用程式



隱藏安裝功能讓您可將 SWF 檔內嵌在網頁中,供使用者從瀏覽器安裝 AIR 應用程式。如果尚未安裝執行階段,隱藏安裝功能就會安裝執行階段。隱藏安裝功能讓使用者不需要將 AIR 檔儲存至電腦便能安裝 AIR 應用程式。AIR SDK 隨附了 badge.swf 檔案,讓您得以輕鬆使用隱藏安裝功能。如需詳細資訊,請參閱使用 badge.swf 檔案安裝 AIR 應用程式

關於自訂隱藏安裝 badge.swf 檔案

除了使用 SDK 隨附的 badge.swf 檔案,您也能自行建立 SWF 檔以供瀏覽器網頁使用。您自訂的 SWF 檔可以透過下列方式與執行階段互動:

這些功能是經由呼叫裝載於 adobe.com 上的 SWF 檔 air.swf 中的 API 所取得。本節會說明如何使用與自訂 badge.swf 檔案,以及如何從自訂的 SWF 檔呼叫 air.swf API。

此外,在瀏覽器內執行的 SWF 檔還能利用 LocalConnection 類別,與執行中的 AIR 應用程式進行通訊。如需詳細資訊,請參閱應用程式間的通訊。

重要事項: 若要運行本節所述的功能 (以及 air.swf 檔案中的 API),使用者的網頁瀏覽器必須安裝 Adobe® Flash® Player 9 更新 3。您可以撰寫程式碼來檢查已安裝的 Flash Player 版本,並於使用者未安裝必要的 Flash Player 版本時提供替代介面予以告知。例如,若是安裝了舊版的 Flash Player,便可以提供下載版 AIR 檔的連結 (而不是使用 badge.swf 檔案或 air.swf API 來安裝應用程式)。

使用 badge.swf 檔案安裝 AIR 應用程式

AIR SDK 隨附了 badge.swf 檔案,讓您得以輕鬆使用隱藏安裝功能。badge.swf 能夠從網頁上的連結來安裝執行階段和 AIR 應用程式。所附的項目包括 badge.swf 檔案及其原始碼,可供您的網站進行散佈。

本節中的指示包含了有關如何設定 Adobe 所提供 badge.swf 檔案各項參數的資訊。而 badge.swf 檔案的原始碼也附在其中,您可以自訂其內容。

將 badge.swf 檔案內嵌在網頁中

  1. 在 AIR SDK 的 samples/badge 目錄中找出下列檔案,然後將這些檔案加入到您的網站伺服器。

    • 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

    標誌上顯示的影像 (選擇性) 所在 URL。

    buttoncolor

    下載按鈕的顏色 (指定成十六進位值,例如 FFCC00)。

    messagecolor

    當執行階段未安裝時,按鈕下方所顯示文字訊息的顏色 (指定成十六進位值,例如 FFCC00)。

  4. badge.swf 檔案的最小尺寸為 217 像素寬 x 180 像素高。請將 AC_FL_RunContent() 函數的 widthheight 參數調整成您所需要的值。

  5. 重新命名 default_badge.html 檔案並修改其程式碼 (或將之加入其它 HTML 網頁) 以符合您的需求。

您也可以編輯並且重新編譯 badge.swf 檔案。如需詳細資訊,請參閱修改 badge.swf 檔案

從網頁上的隱藏安裝連結安裝 AIR 應用程式

一旦您將隱藏安裝連結加入網頁後,使用者就可以按一下 SWF 檔中的連結來安裝 AIR 應用程式。

  1. 在已安裝 Flash Player (第 9 版更新 3 或更新版本) 的網頁瀏覽器中,瀏覽至 HTML 網頁。

  2. 按一下網頁上 badge.swf 檔案中的連結。

    • 如果您已安裝執行階段,請跳到下一個步驟。

    • 如果您尚未安裝執行階段,便會顯示對話方塊詢問您是否要安裝執行階段。請安裝執行階段 (請參閱:Adobe AIR 安裝),然後繼續進行下一個步驟。

  3. 在安裝視窗中,保持選取各項預設設定,然後按一下「繼續」。

    在 Windows 電腦上,AIR 會自動執行下列事項:

    • 將應用程式安裝於 c:\Program Files\ 中

    • 建立應用程式的桌面捷徑

    • 建立「開始」選單捷徑

    • 在「控制台」的「新增/移除程式」中加入應用程式項目

    在 Mac OS 上,安裝程式會將應用程式加入至 Applications 目錄 (例如 Mac OS 的 /Applications 目錄)。

  4. 選取您想要的各種選項,然後按「安裝」按鈕。

  5. 安裝完成後,按一下「完成」。

修改 badge.swf 檔案

AIR SDK 提供了 badge.swf 檔案的原始檔案。這些檔案位於 SDK 的 src 資料夾中:

原始檔案

說明

badge.fla

用來編譯 badge.swf 檔案的原始 Flash CS3 或 CS4 檔案。badge.fla 檔案將編譯成 SWF 9 檔案 (可載入至 Flash Player)。

AIRBadge.as

此 ActionScript 3.0 類別定義了 basdge.fla 檔案中所使用的基底類別。

您可以使用 Flash CS3 或 CS4 重新設計 badge.fla 檔案的視覺介面。

AIRBadge 類別中所定義的 AIRBadge() 建構函數會載入 air.swf 檔案 (裝載於 http://airdownload.adobe.com/air/browserapi/air.swf)。air.swf 檔案包含了使用隱藏安裝功能的程式碼。

一旦順利載入 air.swf 檔案,便會叫用 AIRBadge 類別的 onInit() 方法:

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()

判斷電腦是否已安裝 (或能否安裝) 執行階段。如需詳細資訊,請參閱檢查是否已安裝執行階段

installApplication()

在使用者的電腦上安裝指定的應用程式。如需詳細資訊,請參閱從瀏覽器安裝 AIR 應用程式

  • url:此字串定義 URL。必須使用絕對 URL 而非相對 URL 路徑。

  • runtimeVersion:此字串指定即將安裝的應用程式所需要的執行階段版本 (例如 "1.0.M6")。

  • arguments:這些引數會傳遞給安裝後即啟動的應用程式。如果應用程式描述器檔案中的 allowBrowserInvocation 元素設定為 true,應用程式將於安裝後即啟動 (如需有關應用程式描述器檔案的詳細資訊,請參閱設定 AIR 應用程式屬性)。若是以隱藏安裝的方式從瀏覽器啟動應用程式 (由於使用者選擇在安裝後即啟動),但卻未傳遞這些引數,應用程式的 NativeApplication 物件就不會傳送 BrowserInvokeEvent 物件。傳遞資料給應用程式時,請務必考量安全性方面的隱憂。如需詳細資訊,請參閱從瀏覽器啟動已安裝的 AIR 應用程式

urlruntimeVersion 的設定值是透過容器 HTML 網頁中的 FlashVars 設定而傳入 SWF 檔。

如果應用程式將於安裝後自動啟動,您就可以利用 LocalConnection 通訊方式,讓已安裝的應用程式一經叫用便與 badge.swf 檔案聯繫。如需詳細資訊,請參閱應用程式間的通訊。

您也可以呼叫 air.swf 檔案的 getApplicationVersion() 方法,檢查是否安裝了特定的應用程式。不論是在應用程式安裝程序進行之前或開始安裝後,皆可呼叫此方法。如需詳細資訊,請參閱從網頁檢查是否已安裝 AIR 應用程式

載入 air.swf 檔案

您可以取用 air.swf 檔案中的 API 來自行建立 SWF 檔,然後透過瀏覽器內的網頁與執行階段及 AIR 應用程式進行互動。air.swf 檔案裝載於 http://airdownload.adobe.com/air/browserapi/air.swf。若要從您的 SWF 檔中參考 air.swf API,請將 air.swf 檔案載入到與您的 SWF 檔相同的應用程式網域。下列程式碼會示範如何將 air.swf 檔案載入到載入端 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。這些 API 將於下列各節中詳加說明:

備註: AIR SDK 所隨附的 badge.swf 檔案會自動載入 air.swf 檔案。請參閱使用 badge.swf 檔案安裝 AIR 應用程式。您可以參照該章節的指示,自行建立 SWF 檔並將 air.swf 檔案載入至其中。

檢查是否已安裝執行階段

SWF 檔可藉由呼叫 air.swf 檔案 (載入來源為 http://airdownload.adobe.com/air/browserapi/air.swf) 所提供的 getStatus() 方法,檢查是否已經安裝執行階段。如需詳細資訊,請參閱載入 air.swf 檔案

一旦載入 air.swf 檔案之後,SWF 檔即可呼叫 air.swf 檔案的 getStatus() 方法,如下所示:

var status:String = airSWF.getStatus();

getStatus() 方法會傳回下列任一字串值,視電腦上的執行階段狀態而定:

字串值

說明

"available"

這部電腦可以安裝執行階段,但目前尚未安裝。

"unavailable"

這部電腦無法安裝執行階段。

"installed"

這部電腦已經安裝執行階段。

如果瀏覽器並未安裝必要的 Flash Player 版本 (第 9 版更新 3),getStatus() 方法會擲回錯誤。

從網頁檢查是否已安裝 AIR 應用程式

SWF 檔可藉由呼叫 air.swf 檔案 (載入來源為 http://airdownload.adobe.com/air/browserapi/air.swf) 所提供的 getApplicationVersion() 方法,透過比對應用程式 ID 和發行者 ID 的方式,檢查是否已經安裝特定的 AIR 應用程式。如需詳細資訊,請參閱載入 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。如需詳細資訊,請參閱定義基本的應用程式資訊

pubID

應用程式的發行者 ID。如需詳細資訊,請參閱關於 AIR 發行者識別名稱

callback

回呼函數,當做處理常式函數使用。getApplicationVersion() 方法是以非同步方式運作,一旦偵測到已安裝的版本 (或是找不到已安裝的版本) 便會叫用此回呼方法。此回呼方法的定義必須包含單一字串參數,且其值設定為已安裝的應用程式版本字串。如果應用程式尚未安裝,則會傳遞 null 值給此函數,如上述程式碼樣本所示。

如果瀏覽器並未安裝必要的 Flash Player 版本 (第 9 版更新 3),getApplicationVersion() 方法會擲回錯誤。

從瀏覽器安裝 AIR 應用程式

SWF 檔可藉由呼叫 air.swf 檔案 (載入來源為 http://airdownload.adobe.com/air/browserapi/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 路徑。

runtimeVersion

此字串指定即將安裝的應用程式所需要的執行階段版本 (例如 "1.0")。

arguments

此引數陣列會傳遞給安裝後即啟動的應用程式。如果應用程式描述器檔案中的 allowBrowserInvocation 元素設定為 true,應用程式將於安裝後即啟動 (如需有關應用程式描述器檔案的詳細資訊,請參閱設定 AIR 應用程式屬性)。若是以隱藏安裝的方式從瀏覽器啟動應用程式 (由於使用者選擇在安裝後即啟動),但卻未傳遞這些引數,應用程式的 NativeApplication 物件就不會傳送 BrowserInvokeEvent 物件。如需詳細資訊,請參閱從瀏覽器啟動已安裝的 AIR 應用程式

您必須在使用者事件 (例如按下滑鼠) 的事件處理常式中呼叫 installApplication() 方法,否則此方法不能運作。

如果瀏覽器並未安裝必要的 Flash Player 版本 (第 9 版更新 3),installApplication() 方法會擲回錯誤。

若要在 Mac OS 上安裝更新版的應用程式,使用者必須具有適當的系統權限,才能在應用程式目錄內進行安裝 (如果應用程式要更新執行階段,則必須具有系統管理權限)。在 Windows 上,使用者必須具有系統管理權限。

您也可以呼叫 air.swf 檔案的 getApplicationVersion() 方法,檢查是否安裝了特定的應用程式。不論是在應用程式安裝程序進行之前或開始安裝後,皆可呼叫此方法。如需詳細資訊,請參閱從網頁檢查是否已安裝 AIR 應用程式。執行中的應用程式可以使用 LocalConnection 類別,與瀏覽器內的 SWF 內容進行通訊。如需詳細資訊,請參閱應用程式間的通訊。

從瀏覽器啟動已安裝的 AIR 應用程式

若要使用瀏覽器叫用功能 (以便可從瀏覽器啟動應用程式),目標應用程式的應用程式描述器檔案必須包含下列設定:

<allowBrowserInvocation>true</allowBrowserInvocation>

如需有關應用程式描述器檔案的詳細資訊,請參閱設定 AIR 應用程式屬性

瀏覽器內的 SWF 檔可藉由呼叫 air.swf 檔案 (載入來源為 http://airdownload.adobe.com/air/browserapi/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 檔的應用程式網域)。若已安裝指定的應用程式,且應用程式描述器檔案中的 allowBrowserInvocation 設定為允許瀏覽器叫用功能,呼叫此方法將導致 AIR 啟動該應用程式。這個方法具有下列參數:

參數

說明

appID

要啟動之應用程式的應用程式 ID。如需詳細資訊,請參閱定義基本的應用程式資訊

pubID

要啟動之應用程式的發行者 ID。如需詳細資訊,請參閱關於 AIR 發行者識別名稱

arguments

要傳遞至應用程式的引數陣列。應用程式的 NativeApplication 物件會傳送 BrowserInvokeEvent 事件,而該事件的 arguments 屬性即是設定成此陣列。

您必須在使用者事件 (例如按下滑鼠) 的事件處理常式中呼叫 launchApplication() 方法,否則此方法不能運作。

如果瀏覽器並未安裝必要的 Flash Player 版本 (第 9 版更新 3),launchApplication() 方法會擲回錯誤。

如果應用程式描述器檔案將 allowBrowserInvocation 元素設定為 false,呼叫 launchApplication() 方法就沒有任何效用。

您或許可以先呼叫 air.swf 檔案所提供的 getApplicationVersion() 方法,再決定是否顯示使用者介面告知即將啟動應用程式。如需詳細資訊,請參閱從網頁檢查是否已安裝 AIR 應用程式

透過瀏覽器叫用功能叫用應用程式時,應用程式的 NativeApplication 物件會傳送 BrowserInvokeEvent 事件。如需詳細資訊,請參閱瀏覽器叫用

如果您要使用瀏覽器叫用功能,請務必考量瀏覽器叫用中所述的安全性隱憂。

執行中的應用程式可以使用 LocalConnection 類別,與瀏覽器內的 SWF 內容進行通訊。如需詳細資訊,請參閱應用程式間的通訊。