Web アクティビティ

非標準
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

この API は Firefox for Android 上で動いているインストール済みコードで使用可能であり、Firefox for Android 32+ の Firefox for Android Web アプリでの使用を想定しています。

Web アクテビティはアプリケーションが他の(普通はユーザーが選択した)アプリケーションへ動作を委譲する方法を定義します。

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

アクティビティ

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

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

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

アクティビティの登録

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

注:どんなアプリでも自分自身をアクティビティハンドラーとして登録したり独自のアクティビティを作成できます。どちらの場合もアプリマニフェストで同じように行います。ただ、新しいアクティビティを作る時には URL をアクティビティの接頭辞にしてアクティビティ名の衝突を避けるのがベストプラクティスとされています(例:example.org/myActivity または org.example.myActivity)。

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

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

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

  // アクティビティの登録
  "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 イベントはそれぞれ postResultpostError がアクティビティハンドラーに呼ばれた後に発火します。
filters Optional
各プロパティでフィルターを指定する形式の辞書。このフィルターは、アプリがあるアクティビティを処理するのに適切かどうか決定する際に適用されます。フィルター名は自由形式のテキストで、MozActivityOptionsdata プロパティ内の名前を反映させるべきです。フィルターの値は基本的な値(文字列または数値)、基本的な値の配列、あるいはフィルター定義オブジェクトのいずれかです。フィルターの条件が全て満たされた場合にのみ、アクティビティが処理可能だと見做されます。

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

  • フィルターの値が基本的な値の場合、対応する 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");
    }
  }
});

注:postError()postResult() も呼ばれなかった場合 -- 例えばユーザーが(デスクトップ版であればタブを閉じたり、モバイルデバイスであればホームスクリーンに戻ったりして)アプリケーションから離脱した場合 -- にはどこかの時点で UA がエラーを送ることが期待されます。

アクテビティの開始

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 は基本的なアクティビティを定義している組み込みアプリケーションを多数提供しています。そのアクティビティは以下の通りです。

アクティビティ名 アプリケーション 期待するデータ(フィルター)
browse Gallery
type: "photos"
 
configure Settings
target: "device"
 
costcontrol/balance Costcontrol なし  
costcontrol/data_usage Costcontrol なし  
costcontrol/telephony Costcontrol なし  
dial Communication
type: "webtelephony/number",
number: { 
  regexp: "^[\\d\\s+#*().-]{0,50}$"
}
アプリが電話呼び出しを渡したい時に使用。
new Communication
type: "webcontacts/contact"
アプリが新しいコンタクトエントリーを作成したい時に使用。
Email
type: "mail"

アプリが新規メールを送信したい時に使用。メールアプリは "url" または "URI" プロパティとして渡された mailto URI 文字列をパースすることができます。添付ファイルは "blob" の配列と "filenames" の配列を、n 番目のファイル名は n 番目の blob に対応、というように対応させながら追加することで渡せます。

SMS
type: "websms/sms",
number: {
  regexp: "^[\\w\\s+#*().-]{0,50}$"
}
アプリが SMS を送信したい時に使用。
nfc-ndef-discovered n/a なし アプリが他デバイス上のアプリと data/tag を交換したい時に使用。
open Communication
type: "webcontacts/contact"
 
Gallery
type: [
  "image/jpeg",
  "image/png",
  "image/gif",
  "image/bmp"
]
 
Music
type: [
  "audio/mpeg",
  "audio/ogg",
  "audio/mp4"
]
 
Video
type: [
  "video/webm",
  "video/mp4",
  "video/3gpp",
  "video/youtube"
]

Blob オブジェクトとなっている blob プロパティも必要です。

アプリが動画を表示したい時に使用(view アクティビティでも同様のことが可能)。
pick Camera, Gallery, Wallpaper
type: ["image/*", "image/jpeg"]
アプリが画像を取得したい時に使用。
Communication
type: [
  "webcontacts/contact",
  "webcontacts/email"
]

Firefox OS 2.0 以降では、下のように fullContact: "true" というフィールドを指定して、プロパティに直接アクセスできる完全なオブジェクトを返すことができます。

type: [
  "webcontacts/contact",
  fullContact: "true"
]
アプリがコンタクト情報またはメールを読み込みたい時に使用。
record Camera
type: ["photos", "videos"]
アプリが何らかの動画を撮りたい時に使用。
save-bookmark Homescreen
type: "url",
url: {
  required:true,
  regexp:/^https?:/
}
 
share Bluetooth
number: 1
 
Email, Wallpaper
type: "image/*"
アプリが画像をシェアしたい時に使用。
view Browser
type: "url"
url: {
  required: true,
  regexp: /^https?:.{1,16384}$/
}
アプリが URL を開きたい時に使用。
Email
type: "url",
url: {
  required:true,
  regexp: "^mailto:"
}
 
PDFs
type: "application/pdf"
アプリが PDF ドキュメントの内容を表示したい時に使用。
Video
type: [
  "video/webm",
  "video/mp4",
  "video/3gpp",
  "video/youtube"
]

文字列である url プロパティも必要です。

アプリが動画を表示したい時に使用(open アクティビティでも同様のことが可能)。
update Communication
type: "webcontacts/contact"
アプリがコンタクト情報を更新したい時に使用。

Firefox for Android のアクティビティ

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

MozActivity Android のインテント
アクティビティ名 期待されるデータ アクション名 Extras MIME URI
dial
type: "webtelephony/number",
number: "+11234567890"
DIAL     tel:+11234567890
open
type: "image/jpeg",
uri: "http://mozilla.org/image.jpg"
VIEW   image/jpeg http://mozilla.org/image.jpg
pick
type: "image/jpeg"
GET_CONTENT   image/jpeg  
send
type: "text/plain",
text: "my message"
SEND TEXT: "my message" text/plain  
type: "text/html",
html_text: "<strong>my</strong> message"
SEND HTML_TEXT: "<strong>my</strong> message" text/html  
view
type: "url",
url: "http://mozilla.org/"
VIEW     http://mozilla.org/
type: "url",
uri: "mailto:user@mozilla.org"
VIEW     mailto:user@mozilla.org

仕様

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

関連項目

ドキュメントのタグと貢献者

 このページの貢献者: KitaitiMakoto
 最終更新者: KitaitiMakoto,