ウェブ用の連絡先選択ツール

Contact Picker API を使用すると、ユーザーは連絡先リストから簡単に連絡先を共有できます。

Contact Picker API とは

モバイル デバイスでのユーザーの連絡先へのアクセスは、(ほぼ)早い時期から iOS/Android アプリの機能でした。この機能はウェブ デベロッパーから寄せられる機能リクエストの中でも特に多く、iOS/Android アプリを作成する主な理由となっています。

Contact Picker API 仕様は、Android M 以降の Chrome 80 で利用できるオンデマンド API です。この API を使用すると、ユーザーは連絡先リストからエントリを選択し、選択したエントリの一部の詳細をウェブサイトと共有できます。ユーザーは必要なときに必要なコンテンツだけを共有でき、友だちや家族と連絡を取り合いやすくなります。

たとえば、ウェブベースのメール クライアントで Contact Picker API を使用してメールの受信者を選択できます。Voice-over-IP アプリで、発信先の電話番号を検索できます。または、ソーシャル ネットワークを利用して、ユーザーがすでに参加している友だちを見つけることもできます。

Contact Picker API の使用

Contact Picker API では、必要な連絡先情報の種類を指定するオプション パラメータを使用したメソッド呼び出しが必要です。2 つ目の方法では、基盤となるシステムが提供する情報を示します。

機能検出

Contact Picker API がサポートされているかどうかを確認するには、次のコマンドを使用します。

const supported = ('contacts' in navigator && 'ContactsManager' in window);

また、Android で連絡先選択ツールを使用するには Android M 以降が必要です。

連絡先選択ツールを開く

Contact Picker API のエントリ ポイントは navigator.contacts.select() です。呼び出されると、Promise が返されて連絡先選択ツールが表示され、ユーザーはサイトと共有する連絡先を選択できます。共有する対象を選択して [Done] をクリックすると、ユーザーが選択した連絡先の配列で Promise が解決されます。

select() を呼び出すときは、最初のパラメータとして返すプロパティの配列(指定できる値は 'name''email''tel''address''icon' のいずれか)と、必要に応じて複数の連絡先を 2 番目のパラメータとして選択できるかどうかを指定する必要があります。

const props = ['name', 'email', 'tel', 'address', 'icon'];
const opts = {multiple: true};

try {
  const contacts = await navigator.contacts.select(props, opts);
  handleResults(contacts);
} catch (ex) {
  // Handle any errors here.
}

Contacts Picker API は、セキュアでトップレベルのブラウジング コンテキストからのみ呼び出すことができます。他の強力な API と同様に、ユーザーの操作が必要です。

利用可能なプロパティの検出

使用可能なプロパティを検出するには、navigator.contacts.getProperties() を呼び出します。これは、使用可能なプロパティを示す文字列の配列で解決される Promise を返します。(例: ['name', 'email', 'tel', 'address'])。これらの値は select() に渡すことができます。

プロパティは常に使用できるとは限らず、新しいプロパティが追加される場合もあります。将来的には、他のプラットフォームや連絡先ソースで、共有されるプロパティが制限される可能性があります。

結果の処理

Contact Picker API は連絡先の配列を返します。各連絡先にはリクエストされたプロパティの配列が含まれます。リクエストされたプロパティに連絡先にデータがない場合、またはユーザーが特定のプロパティの共有をオプトアウトした場合、API は空の配列を返します。(ユーザーによるプロパティの選択方法については、ユーザー コントロールのセクションをご覧ください)。

たとえば、サイトが nameemailtel をリクエストし、ユーザーが名前フィールドにデータを持ち、電話番号が 2 つあるものの、メールアドレスがない連絡先を 1 つ選択した場合、次のようなレスポンスが返されます。

[{
  "email": [],
  "name": ["Queen O'Hearts"],
  "tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

セキュリティと権限

Chrome チームは、強力なウェブ プラットフォーム機能へのアクセスの制御で定義されている基本原則(ユーザー制御、透明性、エルゴノミクスなど)を使用して Contact Picker API を設計、実装しました。それぞれについて説明します。

ユーザー コントロール

ユーザーの連絡先へのアクセスは選択ツールを通じて行います。これは、安全なトップレベルのブラウジング コンテキストで、ユーザー操作でのみ呼び出すことができます。これにより、ページの読み込み時に選択ツールを表示したり、コンテキストなしで選択ツールをランダムに表示したりできなくなります。

ユーザーが共有するプロパティを選択できるスクリーンショット。
ユーザーは一部のプロパティを共有しないことを選択できます。このスクリーンショットでは、ユーザーが [電話番号] ボタンをオフにしています。サイトが電話番号を要求しても、サイトと共有されることはありません。

すべての連絡先を一括選択することはできないため、ユーザーは特定のウェブサイトで共有する必要がある連絡先のみを選択することをおすすめします。ユーザーは選択ツールの上部にあるプロパティ ボタンを切り替えて、サイトと共有するプロパティを制御することもできます。

透明性

どの連絡先情報が共有されているかを明確にするため、選択ツールには常に連絡先の名前とアイコンのほか、サイトがリクエストしたプロパティが表示されます。たとえば、サイトが nameemailtel をリクエストした場合、3 つのプロパティがすべて選択ツールに表示されます。または、サイトが tel のみをリクエストする場合、選択ツールには名前と電話番号のみが表示されます。

すべてのプロパティをリクエストするサイトの選択ツールのスクリーンショット。
選択ツール、nameemailtel をリクエストするサイト、1 件の連絡先が選択されています。
電話番号のみをリクエストするサイトの選択ツールのスクリーンショット。
選択ツール、tel のみをリクエストしているサイト、1 件の連絡先が選択されています。
連絡先を長押ししたときの選択ツールのスクリーンショット。
連絡先を長押しした結果。

連絡先を長押しすると、その連絡先が選択された場合に共有されるすべての情報が表示されます。(Cheshire Cat の連絡先画像をご覧ください)。

権限の永続化なし

連絡先へのアクセスはオンデマンドで行われ、永続化されません。サイトがアクセスを必要とするたびに、ユーザー操作で navigator.contacts.select() を呼び出し、サイトと共有する連絡先をユーザーが個別に選択する必要があります。

フィードバック

Chrome チームでは、Contact Picker API の使用経験を伺いたいと思います。

実装に問題がある場合

Chrome の実装にバグが見つかりましたか?それとも 実装が仕様と異なっているか?

  • https://new.crbug.com でバグを報告します。できる限り詳細を記載し、バグを再現するための簡単な手順を記載して、[Components] を Blink>Contacts に設定します。Glitch は、問題をすばやく簡単に再現するのに最適です。

API を使用する予定がある場合は、

Contact Picker API を使用する予定はありますか。一般公開のサポートは、Chrome チームが機能に優先順位を付けるのに役立ちます。また、他のブラウザ ベンダーに対して、サポートがいかに重要であるかを示します。

関連情報

ありがとう

この機能を実装した Finnur Thorarinsson 氏と Rayan Kanso 氏と、私が恥ずかしいことに盗み出し、このデモのためにリファクタリングしたコードである Peter Beverloo 氏に感謝いたします。

追伸: 連絡先選択ツールの名前は「不思議の国のアリス」のキャラクターです。