Web Activities

摘要

Web Activities 即定義「App 將 Activity 委託 (Delegate) 予另一個 App (往往是由使用者所選擇)」的方法。

Web Activities 目前僅能用於 Firefox OS 上，而完整規格可參閱 WikiMo。

Activity

所謂「Activity」就是使用者想做的事情，如選取影像、傳送電子郵件等。App 開發者可能會定義某個 App 去處理該 Activity，或定義某個 App 委託予 Activity。

將 App 註冊為 Activity handler

App 開發者可建構 App 以處理單或多個 Activity。也就是說，這個 App 可經由其他 App 呼叫之後，而執行 Activity 所定義的某些特定動作。舉例來說，我們可能用其他 App 呼叫相片管理 App，進而選取相片。若 App 是作為 Activity Handler，就會成為其他 App 作業流程的一部分。

註冊 Activity

如果要將 App 註冊為 Activity Handler，目前唯一方法就是到 App 的 manifest 檔案中宣告。

App manifest (亦所謂的宣告註冊)

如同下列範例所示，必須透過 App 的 manifest 檔案，宣告 App 將會處理 Activity：

{
  // Other App Manifest related stuff

  // Activity registration
  "activities": {

    // The name of the activity to handle (here "pick")
    "pick": {
      "href": "./pick.html",
      "disposition": "inline",
      "filters": {
        "type": ["image/*","image/jpeg","image/png"]
      },
      "returnValue": true
    }
  }
}

動態註冊

透過 navigator 物件，即可讓 App 動態的註冊自己。但目前尚未提供此 API。可留意 bug 775181 以持續追蹤此 API。

Activity Handler 說明

href

當其他 App 或網頁所啟動的 Activity，同樣也受到此 App 所支援時，則只要選定此 App 執行 Activity，則 href 將指定所應開啟的網頁。另可透過 disposition 屬性指定網頁的開啟方式。

注意：此頁面的 URL 將受到同源規範 (Same-origin policy) 的限制。

disposition 選擇性

在開始 Activity 時，指定「href 所指定的頁面」呈現方式。其值必為下列之一 (若略過不設定，則預設為 window)：

• window ─ 只要是處理 Activity 的頁面，均將以新視窗開啟之；若在行動裝置上，則是以此畫面取代「請求該 Activity 的原始 App」。頁面必須針對自己所支援的各個 Activity，呼叫 navigator.mozSetMessageHandler()，再執行「接收到訊息」的Activity。
• inline ─ 將以覆蓋原頁面的方式，開啟「處理 Activity 的頁面」；若在行動裝置上，則會在「請求該 Activity 的原始 App」上彈出框。如果 disposition 同樣是 window，則後續動作將一模一樣。

returnValue 選擇性

表示 Activity 是否將回傳數值。如果 App 不回傳數值，則一旦選定 App，UA 隨即傳送 success 事件。如果要回傳數值，那只要 Activity 成功，Activity Handler 會呼叫 MozActivityRequestHandler.postResult()；反之則呼叫 MozActivityRequestHandler.postError()。此處 Activity Handler 中，將於 mozSetMessageHandler 指定第一引數的類型，其實就是 MozActivityRequestHandler。在事件處理器呼叫了 postResult 或 postError 之後，將分別觸發 success 或 error 事件。

filters 選擇性

此 Dictionary 收錄了「用以指定篩選器 (Filter)」的各個屬性。在確認 App 是否適合處理目前 Activity 時，就會套用這些篩選器。篩選器名稱可為任何形式的文字，但需對應 MozActivityOptions 的 data 屬性名稱。篩選器的值可能為基本數值 (數字或字串)、基本數值構成的陣列，或篩選器的定義物件。任一 Activity 必須先滿足所有篩選器之後，才會決定是否要處理其他 Activity。

根據各個篩選器數值的不同，處理篩選器的方式也有所差異：

• 如果篩選器為基本數值，則可選填相對應的 MozActivityOptions.data 屬性。但若屬性已存在，則必須與篩選器所具備的數值相同。
• 如果篩選器數值為基本數值構成的陣列，則可選填相對應的 MozActivityOptions.data 屬性。但若屬性已存在，則必須與篩選器所具備的數值陣列之一相同。
• 如果篩選器數值為篩選器定義物件，則相對應的 MozActivityOptions.data 屬性只要遵守物件所定義的規範，即可滿足篩選器。篩選器定義物件可為下列屬性：
  • required：此 Boolean 值將指出對應的 MozActivityOptions.data 屬性，必為存在 (true) 或不存在 (false)。
  • value: ：基本數值或基本數值構成的陣列。相對應的 MozActivityOptions.data 屬性值，必須與篩選器中定義的數值之一相同。
  • min：如果所需的數值為數字，則相對應的 MozActivityOptions.data 屬性值必須大於或等於該值。
  • max：如果所需的數值為數字，則相對應的 MozActivityOptions.data 屬性值必須小於或等於該值。
  • pattern：字串形式必須遵照 JavaScript 正規表示式 (Regular expression) 語法。相對應的 MozActivityOptions.data 屬性值必須符合該形式。從 Firefox OS v1.2 起即支援此屬性。
  • patternFlag：若使用了 pattern 屬性，則必須透過此屬性提供某些額外的正規表示式旗標 (如 i 或 g)。從 Firefox OS v1.2 起即支援此屬性。
  • regexp：此字串包含的正規表示式內容，均遵循 JavaScript 正規表示式的語法。其對應的 MozActivityOptions.data 屬性值必須符合該樣式。與上方的 pattern 欄位相較，regexp可以只針對字串中間的部分值做比對；因此若要比對字串頭與字串尾，就必須使用 metacharacters 的「^」與「$」分別，即可與 patternFlag 一樣進行完全比對。目前僅限 Firefox OS v1.0 與 v1.1 支援此屬性。因此建議同時使用 pattern 與 regexp。

處理 Activity

一旦把 App 宣告為 Activity Handler 之後，我們就必須在實作中處理其他 App 所傳來的 Activity 請求。

若要處理 Activity，就必須註冊「執行所有必要動作」的函式。先透過 navigator.mozSetMessageHandler() 來設定訊息處理器 (Message handler)，並特別指派至「activity」訊息 (不能為 Activity 的名稱)。接著將傳入 MozActivityRequestHandler 物件，以作為 Activity Handler 函式的參數。

navigator.mozSetMessageHandler('activity', function(activityRequest) {
  // Do something to handle the activity
});

在 Activity Handler 函式執行動作時，將透過 Activity 請求而檢索 Activity 的相關資訊，並依需要而回傳答案。

另外，呼叫 Activity 的 App 必須提供某些資料 (請參閱下表)。而透過請求的 source 屬性 (亦為 MozActivityOptions 物件) 即可取得這些資料。該物件將提供 Activity 呼叫的 name 與相關 data。

navigator.mozSetMessageHandler('activity', function(activityRequest) {
  var option = activityRequest.source;

  if (option.name === "pick") {
    // Do something to handle the activity
  }
});

一旦執行所有動作以處理 Activity 之後，我們就可以呼叫請求的 postResult() 函式，針對委託該 Activity 的 App，回傳所需的結果。

如果發生錯誤，則可呼叫請求的 postError() 函式，以回傳該 Activity 的錯誤訊息。

navigator.mozSetMessageHandler('activity', function(activityRequest) {
  var option = activityRequest.source;

  if (option.name === "pick") {
    // Do something to handle the activity
    ...

    // Send back the result
    if (picture) {
      activityRequest.postResult(picture);
    } else {
      activityRequest.postError("Unable to provide a picture");
    }
  }
});

開始 Activity

就 Web Activities 的另一方面來說，就是有 App 會將 Activity 委託予我們的 App。若要執行這種委託作業，則 App 必須建立 (Instantiate) MozActivity 物件，進而呼叫 Activity。這種物件其實就是 DOMRequest 物件，可等待來自於 Activity Handler 的任何反應。只要建立了物件之後，就會開始 Activity (也會立刻為使用者顯示 UI)。

var activity = new MozActivity({
  // Ask for the "pick" activity
  name: "pick",

  // Provide de data required by the filters of the activity
  data: {
    type: "image/jpeg"
  }
});

activity.onsuccess = function() {
  var picture = this.result;
  console.log("A picture has been retrieve");
};

activity.onerror = function() {
  console.log(this.error);
};

Firefox OS 的 Activity

Gaia 即為 Firefox OS 的原生介面，並已內建許多 App 以定義基本的 Activity。這些 Activity 如下：

type: "photos"

target: "device"

type: "webtelephony/number",
number: { 
  regexp:/^[\\d\\s+#*().-]{0,50}$/
}

type: "webcontacts/contact"

type: "mail"

type: "websms/sms",
number: {
  regexp:/^[\\w\\s+#*().-]{0,50}$/
}

type: "webcontacts/contact"

type: [
  "image/jpeg",
  "image/png",
  "image/gif",
  "image/bmp"
]

type: [
  "audio/mpeg",
  "audio/ogg",
  "audio/mp4"
]

type: [
  "video/webm",
  "video/mp4",
  "video/3gpp",
  "video/youtube"
]

type: ["image/*", "image/jpeg"]

type: [
  "webcontacts/contact",
  "webcontacts/email"
]

type: ["photos", "videos"]

type: "url",
url: {
  required:true,
  regexp:/^https?:/
}

number: 1

type: "image/*"

type: "url"
url: {
  required: true,
  regexp: /^https?:.{1,16384}$/
}

type: "url",
url: {
  required:true,
  regexp:/^mailto:/
}

type: "application/pdf"

type: [
  "video/webm",
  "video/mp4",
  "video/3gpp",
  "video/youtube"
]

type: "webcontacts/contact"

規格

Web Activities 目前尚不屬於任何規格，但其中某些部分與當前的 Web Intents 有所重複。事實上，Mozilla 規劃 Web Activities 正是想提議用以替代 Web Intents。若要進一步了解相關資訊，可參閱 Web Intents Task Force ML 上的討論。

另可參閱

• MozActivity
• MozActivityRequestHandler
• MozActivityOptions
• navigator.mozSetMessageHandler()
• Introducing Web Activities