Web アクティビティ

Web アクテビティは現在 Firefox OS 上でのみ有効です。仕様の全体は  WikiMo で見ることができます。

アクティビティ

アクティビティとは、画像の選択やメールの送信などユーザーが行いたいと思うことです。アプリ作成者はあるアクティビティを処理するものとして、あるいはあるアクティビティを委譲するものとしてアプリを定義することができます。

アプリをアクティビティハンドラーとして登録する

アプリ作成者は、一つ以上のアクティビティを処理するアプリをビルドすることができます。これは、ほかのアプリから呼び出して、アクティビティで定義したある特定の動作を行わせられるということです。例えばフォトマネージャーをビルドしたいとしましょう。ほかのアプリケーションからそれを使って写真を選択することができます。このアプリは、アクティビティハンドラーとしてほかのアプリのワークフロー上の一部となるのです。

アクティビティの登録

現在のところ、アプリをアクティビティハンドラーとして登録する方法は一つだけです。それはアプリマニフェスト内で宣言することです。

アプリマニフェスト（または宣言による登録）

アプリがあるアクティビティを処理するよう期待されるということを表明するには、以下の例のようにアプリマニフェストを使う必要があります。

{
  // その他のアプリマニフェスト関連事項

  // アクティビティの登録
  "activities": {

    // 処理するアクティビティ名（ここでは"pick"）
    "pick": {
      "href": "./pick.html",
      "disposition": "inline",
      "filters": {
        "type": ["image/*","image/jpeg","image/png"]
      },
      "returnValue": true
    }
  }
}

動的な登録

アプリが navigator オブジェクトを使って動的に登録できるようにする予定があります。ですが、この API はまだ使用できません。この API に関連した動きを追いかけるには バグ 775181 を参照してください。

アクティビティハンドラーの記述

href

これは、ほかのアプリや Web ページがこのアプリでサポートしているアクティビティを起動し、アクティビティを実行するのにこのアプリが選ばれた場合に開かれるページを指定します。ページは disposition プロパティに指定した方法で開かれます。

注： このページの URL は同一生成元ポリシーの制約を受けます。

disposition Optional

アクティビティが起動された時に、href で指定したページがどのように表示されるかを指定します。指定する場合、値は以下のどちらかでなければなりません（省略時のデフォルトは window）。

• window - アクティビティを処理するページは新規「ウィンドウ」で開きます（モバイルデバイスでは、この表示はアクティビティをリクエストした元のアプリを置き換えるでしょう）。このページはサポートするアクティビティごとに navigator.mozSetMessageHandler() を呼び、それから受け取ったメッセージに合わせてアクティビティを実行する必要があります。
• inline - アクティビティを処理するページはオーバーレイで開きます（モバイルデバイスでは、このページはアクティビティをリクエストした元のアプリ上のポップアップで描画されるでしょう）。その後の振る舞いは disposition が window の場合と完全に同じです。

returnValue Optional

アクティビティが値を返すか否かを宣言します。アプリケーションが値を返す物ではない場合、 UA はアプリケーションが選択されてすぐに success イベントを送信することができます。値を返す時には、アクティビティハンドラーは、アクティビティが成功した場合には MozActivityRequestHandler.postResult() を、失敗した場合には MozActivityRequestHandler.postError() を呼ぶ必要があります（ここで MozActivityRequestHandler はアクティビティハンドラーが mozSetMessageHandler 内で指定する関数に渡す第一引数の型）。 success イベントと error イベントはそれぞれ postResult、postError がアクティビティハンドラーに呼ばれた後に発火します。

filters Optional

各プロパティでフィルターを指定する形式の辞書。このフィルターは、アプリがあるアクティビティを処理するのに適切かどうか決定する際に適用されます。フィルター名は自由形式のテキストで、MozActivityOptions の data プロパティ内の名前を反映させるべきです。フィルターの値は基本的な値（文字列または数値）、基本的な値の配列、あるいはフィルター定義オブジェクトのいずれかです。フィルターの条件が全て満たされた場合にのみ、アクティビティが処理可能だと見做されます。

フィルターの適用方法は以下のように各フィルターの値によります。

• フィルターの値が基本的な値の場合、対応する MozActivityOptions.data プロパティは任意ですが、もし存在すればフィルターが指定する物と同一でなければなりません。
• フィルターの値が基本的な値の配列である場合、対応する MozActivityOptions.data プロパティは任意ですが、もし存在すれば、その値はフィルターが指定する配列内の値のいずれかと等しくなければなりません。
• フィルターの値がフィルター定義オブジェクトの場合、そのフィルターは対応する MozActivityOptions.data プロパティがオブジェクトの定めるルールに従う場合に満たされたとされますフィルター定義オブジェクトには以下のプロパティが定義できます。
  • required: 対応する MozActivityOptions.data プロパティが存在する必要がある（true）か否（false）かを指定するブール値。
  • value: 基本的な値か基本的な値の配列。対応する MozActivityOptions.data プロパティの値はフィルターで定義する値のいずれかに等しくなければならない。
  • min: 数値が期待される場合、対応する MozActivityOptions.data プロパティの値はこの値以上でなければならない。
  • max: 数値が期待される場合、対応する MozActivityOptions.data プロパティの値はこの値以下でなければならない。
  • pattern: JavaScript の正規表現の文法に従った文字列のパターン。対応する MozActivityOptions.data プロパティの値はこのパターンにマッチしなければならない。Firefox OS v1.2 以降でサポート。
  • patternFlags: パターンが使われる場合、追加で i や g といった正規表現のフラグを指定するのにこのプロパティを使うことができる。Firefox OS v1.2 以降でサポート。
  • regexp: JavaScript の正規表現の文法に従った正規表現リテラルを含む文字列。対応する MozActivityOptions.data プロパティの値はこのパターンにマッチしなければならない。pattern フラグと異なり、値に部分マッチさせることができるため、文字列の始点と終点にマッチさせるにはそれぞれメタ文字の ^ と $ を使う必要がある。Firefox OS v1.0 と v1.1 のみでサポート。 よって pattern と regexp の両方を使うことが望ましい。

アクティビティの処理

アプリケーションをアクティビティハンドラーとして宣言した場合には、他のアプリからのアクティビティリクエストを受け取った時に何らかのアクションを実行して実効性を持たせる必要があります。

アクティビティを処理するには必要なアクションを全て実行する関数を登録しなければなりません。そのためには navigator.mozSetMessageHandler() でメッセージハンドラーを設定し（アクティビティ名ではなく）'activity' を明示的に割り当てる必要があります。アクティビティハンドラー関数の引数として MozActivityRequestHandler オブジェクトが渡されます。

navigator.mozSetMessageHandler('activity', function(activityRequest) {
  // アクティビティ処理のための何かをする
});

アクティビティハンドラー関数がアクションを実行する際に、必要であればアクティビティについての情報を読み出して返答を送り返すためにアクティビティリクエストをつかうことになります。

アクティビティを呼び出すアプリは幾らかのデータ（後述）を提供する必要があります。このデータはリクエストの source プロパティ経由で伝わり、MozActivityOptions オブジェクトになっています。 このオブジェクトはアクティビティ呼び出しの name と関連する data を提供します。

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

  if (option.name === "pick") {
    // アクティビティ処理のための何かをする
  }
});

アクティビティを処理するためのアクションを全て実行すれば、リクエストの postResult() メソッドを呼んでアクティビティを委譲してきたアプリに結果を送り返すことができます。

問題が起きた場合にはリクエストの postError() メソッドを呼んでアクティビティに関するエラーメッセージを送り返すことができます。

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

  if (option.name === "pick") {
    // アクティビティ処理のための何かをする
    ...

    // 結果を送り返す
    if (picture) {
      activityRequest.postResult(picture);
    } else {
      activityRequest.postError("Unable to provide a picture");
    }
  }
});

アクテビティの開始

Web アクティビティの他方では、我らがアプリにアクティビティを委譲したいアプリがあります。この委譲を実行するには MozActivity オブジェクトをインスタンス化することによってアクティビティを呼び出す必要があります。このオブジェクトには、アクティビティハンドラーからのレスポンスを待つことのできる DOMRequest オブジェクトである、ということ以上のことはありません。アクティビティはオブジェクトが作成されるなり開始し、UI は可能な限り速やかにユーザーに表示されます。

var activity = new MozActivity({
  // "pick" アクティビティを要求
  name: "pick",

  // アクティビティのフィルターに必要なデータを提供
  data: {
    type: "image/jpeg"
  }
});

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

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

追加情報：コンタクト情報の取得

Firefox OS 1.3 以下では、コンタクト情報の取得は以下のように処理します。

switch (this.activityDataType) {
  case 'webcontacts/tel':
    type = 'contact';
    dataSet = theContact.tel;
    noDataStr = _('no_contact_phones');
    break;
  case 'webcontacts/contact':
    type = 'number';
    dataSet = theContact.tel;
    noDataStr = _('no_contact_phones');
    break;
  case 'webcontacts/email':
    type = 'email';
    dataSet = theContact.email;
    noDataStr = _('no_contact_email');
    break;
}

その後、ある人の名前と電話番号が欲しい場合には次のようにそれを使用できます。

var pick = new MozActivity({
  name: "pick",
  data: {
    type: "webcontacts/contact"
  }
});

pick.onsuccess = function () {
  console.log("got contact");
  var contact = this.result;
  if( contact ){
    console.log( "Name " + contact.name + " number "+ contact.number );
  }
};

Firefox OS 2.0+ では、次のように、webcontacts/contact を使う際にコンタクト情報全体を取得できるようにするか、というフィールドを追加しました。

var pick = new MozActivity({
  name: "pick",
  data: {
    type: "webcontacts/contact",
    fullContact: "true"
  }
});

これは Contact オブジェクトを返します。下のように直接そのプロパティを使うことができます。

pick.onsuccess = function (Contact) {
  console.log( "Name " + Contact.name + " number "+ Contact.number );
};

Firefox OS のアクティビティ

Firefox OS のネイティブインターフェイスである Gaia は基本的なアクティビティを定義している組み込みアプリケーションを多数提供しています。そのアクティビティは以下の通りです。

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: [
  "webcontacts/contact",
  fullContact: "true"
]

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"

Firefox for Android のアクティビティ

Firefox for Android 32+ では、WebappRT を使っている Web アプリが Web アクティビティ経由で Android のネイティブのインテントを送ることができます。セキュリティ上の理由から、明示的に対応付けされているアクティビティ/インテントのみがサポートされています。該当するアクティビティは以下の通りです。

type: "webtelephony/number",
number: "+11234567890"

type: "image/jpeg",
uri: "https://mozilla.org/image.jpg"

type: "image/jpeg"

type: "text/plain",
text: "my message"

type: "text/html",
html_text: "<strong>my</strong> message"

type: "url",
url: "https://mozilla.org/"

type: "url",
uri: "mailto:[email protected]"

仕様

Web アクティビティはどの仕様にも含まれていません。ですが、提案中の Web Intents 仕様と共通する部分があります。実際、Mozilla は Web アクティビティを Web Intents への 対案 として提案しています。このことについての詳細は Web Intents タスクフォースの ML 上の議論をご覧ください。

関連項目

• MozActivity
• MozActivityRequestHandler
• MozActivityOptions
• navigator.mozSetMessageHandler()
• Introducing Web Activities（日本語訳）