mozilla
您的搜尋結果

    App 的 manifest 檔案

    This translation is incomplete. Please help translate this article from English.

    App 的 manifest 檔案,即以單一提供 App 的必要資訊,如 App 名稱、圖示、相關說明、所屬的開發者等,並供消費者與 App 商城使用。最重要的,其中詳列了 App 所需的 Web API。在消費者安裝 App 之前,可先行得知必要資訊並決定是否安裝。這也是 Open Web App 與網站的重要差異之一。

    注意:瀏覽器若要能處理 manifest 檔案並安裝 Open Web App,就必須內建 Web runtime。而 Firefox OS,較新版本的 Firefox for AndroidFirefox 桌面版均屬於此類瀏覽器。

    注意:可至 App Manifest FAQ 參閱有關 manifest 檔案的常見問題與解答。

    注意:你會在「應用程式管理員 (App Manager)」看到「manifest」中文翻譯為「安裝資訊檔」。

    建立 manifest 檔案

    本章節將帶領你建立\使用 manifest 檔案。

    基礎:檔案名稱、位址、格式

    • 名稱:manifest.webapp (必使用 .webapp 為附檔名)
    • 位址:App 所在的根目錄
    • 格式:JSON (必為有效的 JSON)

    路徑處理

    • manifest 與圖示等適用的內部路徑,必須與 App 的原始路徑無關,不能為 App 的根目錄。舉例來說,如果 manifest 檔案位於 http://www.mysite.com/myapp/manifest.webapp,則安裝路徑必須為 /myapp/manifest.webapp,而不能為 /manifest.webapp
    • 內部路徑亦必須與 App 的原始路徑一致
    • 外部路徑必須完全合乎規定。舉例來說,如果你將封裝式 (Packaged) App 置於 Firefox Marketplace,另將圖示置於自己的伺服器中,則圖示路徑必為 http://mywebapp/images/myicon.png

    提交至 Firefox Marketplace 的要點

    如果想在 Firefox Marketplace 發佈自己的 App,則 manifest 檔案必須納入下列欄位:

    • name
    • description
    • launch_path (封裝式 App 適用)
    • icons (單一圖示至少 128×128;建議 512×512)
    • developer
    • default_locale (若已定義 locales)
    • type (適用於 Privileged 與內部 (即 Certified) App)

    一般 Open Web App 的要點

    如果你開發的一般 Open Web App 不會交由 Firefox Marketplace 發佈,則 manifest 檔案也必須納入下列欄位:

    • name
    • description
    • icons (單一圖示至少 128×128,建議 512×512)

    注意:若要透過自己的網頁自行發佈 App,則必須提供安裝機制,以利消費者觸發 App 安裝作業。托管\架設式 (Hosted) App 可透過按鈕呼叫 navigator.Apps.install();封裝式 App 則呼叫 navigator.Apps.installPackage() 即可觸發安裝作業。

    manifest 檔案驗證

    在將 App 提交至 Firefox Marketplace 時,manifest 檔案必先通過 Marketplace 的驗證作業。

    可先體驗我們的 App Validator,協助你找出任何錯誤。或可透過此 API 驗證自己 App 的 manifest 檔案。

    更新 manifest 檔案

    若要了解 App 更新的資訊,可參閱〈更新 App〉。

    manifest 範例

    下列是最基本的 manifest 檔案。你可根據自己的資訊而取代相關數值,再另存檔案。

    {
      "name": "My App",
      "description": "My elevator pitch goes here",
      "launch_path": "/index.html",
      "icons": {
        "512": "/img/icon-512.png",
        "128": "/img/icon-128.png"
      },
      "developer": {
        "name": "Your name or organization",
        "url": "http://your-homepage-here.org"
      },
      "default_locale": "en"
    }

    必要的 manifest 欄位

    manifest 檔案中的欄位順序不限。只要不是下面所列出的欄位,manifest 均將自動忽略。

    name

    注意:所有 manifest 檔案必備。

    可供任何人閱讀的 App 名稱,最長 128 字元。

    在 Marketplace 許可並發佈你的 App 之後,若你更改 App 的名稱,則所有已完成的安裝作業均不會立刻更新名稱。

    "name": "The Open Web!"

    description

    注意:所有 manifest 檔案必備。

    可供任何人閱讀的 App 敘述資訊,最長 1024 個字元。

    "description": "Exciting Open Web App!"

    launch_path

    注意:為封裝式 App 必備欄位。

    在啟動 App 時,將載入 App 來源中的路徑。

    針對封裝式 App 的本端 zip 壓縮檔,此欄位將指定內容的啟始點。舉例來說,若 launch_path 內含「/myApp/index.html」值,則一旦啟動此封裝式 App,隨即將開啟 /myApp/index.html 檔案。

    秘訣:
    • 如果 App 儲存於 Web 伺服器的根目錄中,例如 mywebapp.github.com/,則 launch_path 必須設定為「/」
    • 如果 App 儲存於子目錄中,例如 mymarket.github.com/mywebapp/,則 launch_path 必須設定為「/mywebapp/」。
    "launch_path": "/index.html"

    icons

    注意:所有 manifest 檔案的單一圖示至少須為 128×128;建議為 512×512。

    用以設定不同尺寸圖示的網址。

    圖示的內部路徑必須為 App 原始網址的相對路徑;若要連往外部托管的圖示,則路徑必須完全符合規格。

    圖示必為正方形的 .png 格式,且不該只用純色背景延伸到正方形的四個角落。

    特別注意:若要將 App 提交到 Firefox Marketplace 上,須依照 App 圖示設計準則來設計圖示。

    必要圖示尺寸

    128 x 128
    在 Firefox Marketplace 與裝置之上顯示所用。

    建議圖示尺寸

    512 x 512
    自 Firefox OS 2.0 起,大尺寸圖示才能在手機、平板、3\4 欄排版等各螢幕解析度可能組合上清晰顯示。而 512×512 圖示可再橫跨不同裝置的不同用途另行縮放,另外該尺寸也適合用在其他 App 所能安裝的平台上,例如 Android。

    應該可用的其他圖示尺寸

    60 x 60
    針對舊版 Firefox OS 的特定裝置才能使用。
    16 x 16、32 x 32、48 x 48、64 x 64、90 x 90、128 x 128、256 x 256
    這些圖示尺寸可讓你的 App 在其他平台上達到最佳顯示效果,例如 Windows、OS X、Android。
    "icons": {
      "128": "/img/icon-1.png",
      "512": "/img/icon-2.jpg"
    }

    注意:若想完全了解我們建議 512×512 尺寸的理由,可參閱〈圖示建構指南〉。

    developer

    注意:僅限其中的 name 為所有 manifest 檔案必備。

    • name:開發人員的姓名。所有 manifest 檔案所必備。
    • url:網站的網址,內含 App 開發人員的相關資訊。選填。
    "developer": {
        "name": "The Open Web!",
        "url": "http://www.mywebapp.com"
    }

     

    default_locale

    注意:若已經定義 locales,則該 App 的 manifest 檔案必備 default_locale

    語言標籤 (RFC 4646) 可指定 manifest 檔案所使用的語言。

    即使你的 App 不需要區分語系,我們仍建議你設定 default_locale 屬性並納入 manifest 檔案。若未定義 default_locale 屬性,Marketplace 就必須根據目前服務的地區而推測語言。

    以英文版的 App 為例,default_locale 應為

    "default_locale": "en"​

    type

    注意:若 App 屬於 Privileged 或內部 (Certified) App,則 manifest 檔案必備 type 欄位。

    不同類型的 App,所能存取的 Sensitive Device API (WebAPI) 層級亦不相同。若沒有在 manifest 中指定 type 欄位,則預設值即為 web

    • web:一般的托管\架設式 App。此類 App 所存取的 WebAPI 層級最低。
    • Privileged:屬於授權過的 App,並由 App 商城 (如 Firefox Marketplace) 所許可。此類型 App 所存取的 WebAPI 層級高於 web App。
    • Certified:屬於授權過的 App,專為重要的系統功能所設計,如智慧型手機上的預設撥號介面或系統設定。此類 App 亦不屬於 App 商城中的第三方 App。所存取的 WebAPI 層級最高。

    注意:若要進一步了解 App 的類型,可參閱〈封裝式 (Packaged) App〉。

    "type": "certified"

    選填的 manifest 檔案欄位

    下列欄位為選填。

    activities

    App 支援的一系列 Web Activities。其架構如下:

    • 該欄位中的各個屬性均為一種 activity。
    • Activity 的名稱可為任意形式之文字。
    • 各種 activity 均以 1 組物件表示

    下列即以「share」的 activity 為例:

    "activities": {
      "share": {
        "filters": {
          "type": [ "image/png", "image/gif" ]
        },
        "href": "foo.html",
        "disposition": "window",
        "returnValue": true
      }
    }

    在此範例中,share 的 activity 物件具備「filters」、「href」、「disposition」、「returnValue」等屬性。另於〈Activity handler description〉中說明。

    appcache_path

    App 快取 (AppCache) 的 manifest 檔案之絕對路徑。在安裝某個 Open Web App 之後,隨即會提取 (Fetch) 並剖析 (Parse) AppCache 的 manifest 檔案,且其 CACHE 標頭之下所指定的靜態資源,亦將進一步完成快取。

    注意:封裝式 App 快取外部檔案,均在安裝之後置於裝置之上。不須針對封裝式 App 另外設定 AppCache。

    注意:AppCache 目前仍未完善,短期內將由更高效率的 Service Workers 取代。

    "appcache_path": "/cache.manifest"

    chrome

    Requires Firefox OS 1.1

    於畫面底部新增一系列瀏覽控制介面,如「前一頁」、「下一頁」、「重新載入」、「我的最愛」等。

    chrome navigation

    "chrome": { "navigation": true​ }
    

    注意:建議幫自己的 App 介面設計「退回」按鈕,以提供較佳的使用者經驗。

    csp

    注意:選填。只要是已安裝於 Firefox OS、Firefox 桌面版、Firefox for Android 的所有封裝式 App,均可套用。

    此欄位可定義 App 中套用〈內容安全性準則 (Content Security Policy,CSP)〉的所有頁面。另由〈CSP policy directives〉詳列你能夠添增至 CSP 的所有政策。你必須如下所示,將政策加入 App 之中:

    "csp" : "default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'"

    Firefox OS 針對 Privileged 與 Certified App 所套用的預設政策如下:

    Privileged CSP
    default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'
    Certified/Internal CSP
    default-src *; script-src 'self'; object-src 'none'; style-src 'self'

    這些預設值無法覆寫,僅供新增。也就是在 Privileged 與 Certified App 的狀態下,manifest 檔案中的 CSP 政策,僅能限縮已套用的實際 CSP。

    注意:可參閱 Apps CSP 頁面進一步了解 CSP 對 App 的限制。

    datastores-owned

    注意:僅限套用至可安裝於 Firefox OS 的 Certified App 之上。

    在使用 Data Store API 時,只要是具備資料儲存功能的 App,其 manifest 必定要有 datastores-owned 欄位,才能主張其所有權,例如:

    "datastores-owned": {
      "myData": {
        "access": "readwrite",
        "description": "my data store"
      }
    }

    你可納入多個屬性,以代表不同的資料儲存區。且各個屬性均可使用 readonly/readwrite 的 access,藉以指定該資料儲存區是否可交由其他 App 讀取\修改。另可加入 description 以說明該資料儲存區的用途。

    datastores-access

    注意:僅限套用至可安裝於 Firefox OS 的 Certified App 之上。

    在使用 Data Store API 之時,只要是無人擁有的 App 須存取資料儲存區時,其 manifest 檔案必定要有 datastores-access 欄位,例如:

    "datastores-access": {
      "myData": {
        "access": "readwrite",
        "description": "Read and modify my data store"
      }
    }

    若未指定此欄位,即預設為「no access」。同樣的,你也可加入多重參數以存取多個資料儲存區。另可設定 readonlyreadwrite 的「access」,以主張該 App 所需的存取類型。

    fullscreen

    可告知執行環境 (Runtime) 是否以全螢幕模式啟動 App。

    由於大多數 App 均以全螢幕模式執行,建議將此欄位設定為 true

    "fullscreen": "true"

    installs_allowed_from

    可由 1 個 (或多個) 網址觸發 App 的安裝作業。

    此欄位本為搭配消費者可購買的付費 App 所設計。只要是與開發者進行商業活動的商城,均可透過此欄位進一步識別。若開發者要提供免費 App,則建議略過此欄位,即可供消費者隨意安裝此 App。

    特別注意:勿於網址最末加上結尾斜線,否則將導致安裝作業失敗。

    如果要從 Firefox Marketplace 安裝 App,則 installs_allowed_from 應如下列:

    "installs_allowed_from": [
      "https://marketplace.firefox.com" 
    ]

    另請注意:陣列 ["*"] 則代表任何網頁均可允許此 App 的安裝作業 (此為預設值)。請注意空白陣列 [] 亦可拒絕任何網頁的安裝作業,包含你自己的網頁在內。

    locales

    以 1 個或多個特定語系,覆寫 manifest 檔案中的欄位值。

    各組 locales 輸入項,均包含 manifest 檔案欄位的清單,讓你針對某一特定語言進行覆寫。locales 鍵值所使用的語言標籤,及與 default_locale 所用的語言標籤相同 (RFC 4646)。

    特別注意:

    • 如果你定義了 locales,請一併定義 default_locale

    • 不要在 locales 之中再次定義 default_locale 的值。

    • 無法覆寫下列欄位:default_localelocales、installs_allowed_from

    舉例來說,若 App 預設語言為英文,則 default_locale 即為 en。但你想用翻譯過的 namedescription,為義大利和德國消費者覆寫 name 以及 description 欄位,如此你的 locales 輸入項應如下:

    "locales": {
      "it": {
        "name": "L'Open Web",
        "description": "Eccitante azione di sviluppo web open!"
      },
      "de": {
        "name": "Der Open Web",
        "description": "Spannende offene Web-Entwicklung-Action!"
      }
    }

    messages

    注意:僅限套用至可安裝於 Firefox OS 的  App 之上。

    你允許 App 所能取得的系統訊息。一旦訊息產生,則 App 中的頁面將顯示訊息發生的時刻。

    下列為 Firefox OS 撥號器 App 的範例。每次只要有外來電話 (系統訊息:telephony-new-call),則裝置應顯示撥號器的鍵盤 (URL: /dialer/index.html#keyboard-view)。

    "messages": [
      { "alarm": "/index.html" }
      { "notification": "/index.html" }
      { "telephony-new-call": "/dialer/index.html#keyboard-view" }
    ]

    orientation

    注意:僅限套用到 Android 或 Firefox OS 的 App 之上。

    定義 App 鎖定的方向。

    有效值如下表:

    有效值 App 鎖定方向
    portrait-primary Phone upright in portrait orientation
    portrait-secondary Phone upsidedown in portrait orientation
    portrait
    若宣告此值,則不再需要 -primary-secondary
    Phone upright in portrait orientationPhone upsidedown in portrait orientation
    landscape-primary Phone lying on its left hand side in landscape orientation
    landscape-secondary Phone lying on its right hand side in landscape orientation
    landscape
    若宣告此值,則不再需要 -primary-secondary

    Phone lying on its left hand side in landscape orientation

    Phone lying on its right hand side in landscape orientation

    "orientation": [ "landscape-primary" ]

    origin

    Requires Firefox OS 1.1

    注意:僅限套用至 Privileged 或 Certified 的封裝式 App。

    封裝式 App 內部又具備特殊的通訊協定「app://<UUID>」。而 <UUID> 長字串又專屬於安裝此 App 的裝置。開發者目前無法輕易存取 UUID。origin 欄位則可讓你使用單一域名即能替換此 UUID 值,並可用於所有已安裝的 App。

    特別注意:網域名稱須以 app:// 起頭。你所使用的域名,應該要是你所能控制的網域。

    "origin": "app://my-app.com"

    permissions

    使用者所允許的權限,將決定你的 App 是否能存取 Sensitive Device API (WebAPI),例如聯絡人資料。請參閱 WebAPI 權限\功能的完整列表。任一 App 若要使用 WebAPI,則必須列出所有「需要使用者授權」的 WebAPI。

    各組權限均需要:

    • name:權限的名稱。
    • description:App 需要此權限之理由。
    • access:必要的存取層級,可能為 readonlyreadwritereadcreate、createonly。僅有少數 API 需要此屬性,如 Data Store

    舉例來說,某個 App 的 manifest 輸入項需要裝置的 contactsalarms 權限

    "permissions": {
      "contacts": {
        "description": "Required for autocompletion in the share screen",
        "access": "readcreate"
        },
      "alarms": {
        "description": "Required to schedule notifications"
      }
    }

    注意:若 App 嘗試使用這些 API 之一,但 permissions 欄位中卻沒有對應的輸入項,就會導致作業失敗。

    某些 WebAPI 可能會要求 App 的 type 必為 Privileged 或 Certified。例如 systemXHR 就要 type 欄位設定為 privileged 才能作業:

    "type": "privileged",
      "permissions": {
        "systemXHR": {
          "description": "Required to download podcasts."
        }
      }

    precompile

    Requires Firefox OS 2.0

    注意:僅限用於封裝式 App。

    此路徑將指向「開發者指定於安裝期間進行編譯」的 JavaScript 檔案 (內含的 asm.js 程式碼)。若於安裝期間進行編譯,雖然初始安裝需要較長時間,但可大幅加快 App 在首次啟動時的速度。

    "precompile": [
      "game.js",
      "database.js"
    ]

    redirects

    注意:僅限套用於 Firefox OS 的封裝式 App。

    此內部網址,可讓 App 處理外部程序。

    舉例來說,App 為了取得聯絡人資料而進行 Facebook OAuth 認證。在認證完成作業之後,伺服器往往會將 App 重新導向你所控制的網址。因為封裝式 App 並不會托管於其他地方,也就不具備可重新導向的有效網址。所以可透過 redirects 欄位,將外部網址重新導向至內部的 App 網址。

    根據上述,redirects 欄位應如下:

    "redirects": [
      {"from": "http://facebook.com/authentication/success.html",
        "to": "/app/main_interface.html"}
    ]

    redirects 所宣告的內部網址範圍,僅限於 App 本身。所以多個 App 可將相同的公開網址重新導向自己的本端資源,也進一步避免單一 App 綁架全域公開的網址。

    role

    此欄位主要提供 Gaia 工程團隊內部使用,可指定 B2G 使用 App 的方法,及其在系統中所扮演的角色。到底該是鍵盤或是主畫面的替代畫面?

    "role": "system",

    選項包含:

    • system:不會於主畫面上顯示該 App,且本來是要嘗試替代系統 App。請注意,這實際上並不會真正成為系統 App,只是用來隱藏 App 不讓使用者直接取用 (例如 Bluetooth App)。
    • input:顯示於「設定 (Settings)」App 中的替代性鍵盤,並不會顯示於主畫面上。
    • homescreen:顯示於「設定 (Settings)」App 中的替代性主畫面選項,並不會顯示於主畫面之上。
    • search:顯示於主畫面之上,但......待後續討論。

    version

    此字串代表 manifest 檔案的版本。

    此欄位是為了因應你方便所用,且執行環境並不會使用此欄位,所以可為任何值。建議你應該定義此欄位。

    "version": "2.1"

    manifest 檔案來源

    「App 的 manifest 檔案」與「App 本身」兩者的來源必須一致
    儲存 manifest 檔案的副檔名必須為「.webapp」;且提供 manifests 文件時,application/x-web-app-manifest+json 必須為 Content-Type 的標頭。目前 Firefox 尚未強制使用此格式;但 Firefox Marketplace 則強制使用此格式。另針對「使用者觸發安裝作業的頁面」與「App 本身」此兩者的來源 (origin),Firefox OS 僅將檢查是否不同。你不需要如 Content-Security-PolicyX-UA-Compatible 的其他標頭。

    若是以 SSL 提供 manifest 檔案,將可減少特定類別的攻擊。你也能以 HTTP compression 提供 manifest 檔案,但將無法快取 manifest 檔案。

    為了能將 App 順利提交至 Firefox Marketplace,檔案必為 UTF-8 編碼格式。且建議忽略位元組順序記號 (BOM)。另可透過 Content-Type 標頭上的 charset 參數,指定其他編碼 (例如 Content-Type: application/x-web-app-manifest+json; charset=ISO-8859-4);但 Marketplace 仍不會接受。

    在提醒使用者安裝 App 時,應能送出有意義的網站識別與 TLS 狀態等訊息。

    以 Apache 提供

    .htaccess 檔案中必須加入:

    AddType application/x-web-app-manifest+json .webapp
    注意:此範例是假設你正使用 .webapp 為副檔名。若是使用 .json 或其他副檔名,則必須更新程式碼以切合上述範例。

    如果你新增進 .htaccess 檔案也沒有用,則可在自己 Apache 組態檔案中加進相同的程式碼。根據你使用的作業系統與設定,組態檔案可能命名為 httpd.conf000-default.conf

    以 IIS 提供

    你必須編輯自己的 web.config 檔案。該檔案可能置於網站的根目錄之內。

    另必須於 <configuration> <system.webServer> <staticContent> 區段中添增新的輸入項。

    <remove fileExtension=".webapp" />
    <mimeMap fileExtension=".webapp" mimeType="application/x-web-app-manifest+json; charset=UTF-8" />

    進一步了解該如何在 IIS 中添增靜態內容 MIME 映射。

    注意:此均假設你是使用 .webapp 作為附檔名。如果你是使用 .json 或其他附檔名,則必須更新程式碼以確實反應。
     
    以 nginx 提供

    必須編輯 conf 目錄中的 mime.types 檔案。該檔案亦可能位於 /etc/nginx//opt/nginx/ 中。

    你應該會找到類似下列的編碼,請增加最後一行:

    types {
    text/html   html htm shtml;
    text/css    css;
    text/xml    xml;
    application/x-web-app-manifest+json   webapp;
    }
    注意:此範例是假設你正使用 .webapp 為副檔名。若是使用 .json 或其他副檔名,則必須更新程式碼以切合上述範例。
    以 GitHub 提供

    若是以 GitHub 頁面提供自己的 manifest 檔案,則 GitHub 亦將使用 application/x-web-app-manifest+jsonContent-Type 表頭。而 manifest 檔案必須為 .webapp 副檔名。例如「manifest.webapp」。

    以 Python 提供

    若你已經安裝了 Python,則可輕鬆從本端目錄執行伺服器,只要執行 Python 並貼上相同的:

    import SimpleHTTPServer
    import SocketServer
    SimpleHTTPServer.SimpleHTTPRequestHandler.extensions_map['.webapp'] = 'application/x-web-app-manifest+json'
    httpd = SocketServer.TCPServer(("", 3000), SimpleHTTPServer.SimpleHTTPRequestHandler)
    httpd.serve_forever()
    
    以 Rack (Ruby) 提供

    在 config/initializers/mime_types.rb 內添增:

    Rack::Mime::MIME_TYPES['.webapp'] = 'application/x-web-app-manifest+json'

    規格

    Specification Status Comment
    Manifest for web application Editor's Draft  

     

    Document Tags and Contributors

    標籤: 
    Contributors to this page: evanxd, chrisdavidmills, foxbrush, MashKao
    最近更新: MashKao,
    隱藏側邊欄