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

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

Pete LePage

Contact Picker API とは

モバイル デバイス上のユーザーの連絡先へのアクセスは、iOS/Android アプリのほぼ初期から機能として存在しています。これは、ウェブ デベロッパーから最もよく聞かれる機能リクエストの 1 つであり、多くの場合、iOS/Android アプリを構築する主な理由となっています。

Android M 以降の Chrome 80 以降で利用できる Contact Picker 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 が返され、連絡先選択ツールが表示され、ユーザーはサイトと共有する連絡先を選択できます。共有する内容を選択して [完了] をクリックすると、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 は空の配列を返します。（ユーザーがプロパティを選択する方法については、ユーザー制御セクションで説明します）。

たとえば、サイトが name、email、tel をリクエストし、ユーザーが名前フィールドにデータが入力された連絡先を 1 つ選択し、2 つの電話番号を指定してメールアドレスを指定しなかった場合、返されるレスポンスは次のようになります。

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

セキュリティと権限

Chrome チームは、強力なウェブ プラットフォーム機能へのアクセスを制御するで定義されているコア プリンシプル（ユーザー制御、透明性、人間工学など）を使用して、Contact Picker API を設計して実装しました。それぞれについて説明します

ユーザー コントロール

ユーザーの連絡先へのアクセスはピッカーを介して行われます。これは、安全な最上位のブラウジング コンテキストで、ユーザーの操作によってのみ呼び出すことができます。これにより、サイトがページの読み込み時に選択ツールを表示したり、コンテキストなしでランダムに選択ツールを表示したりすることがなくなります。

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

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

透明性

共有される連絡先情報を確認できるように、選択ツールには常に連絡先の名前とアイコン、およびサイトがリクエストしたプロパティが表示されます。たとえば、サイトが name、email、tel をリクエストすると、3 つのプロパティすべてが選択ツールに表示されます。サイトが tel のみをリクエストする場合は、名前と電話番号のみが選択ツールに表示されます。

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

連絡先を長押しすると、その連絡先を選択した場合に共有されるすべての情報が表示されます。（チェシャ猫の連絡先画像を参照）。

権限の永続性なし

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

フィードバック

Chrome チームでは、Contact Picker API に関するご意見やご感想をお待ちしています。

実装に関する問題

Chrome の実装にバグが見つかりましたか？あるいは、実装が仕様と異なっているのでしょうか？

  • https://new.crbug.com でバグを報告します。できる限り詳細に説明し、バグを再現するための簡単な手順を示して、[Components] を Blink>Contacts に設定します。Glitch は、問題の再現をすばやく簡単に共有できる優れたツールです。

API を使用する予定ですか？

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

  • WICG Discourse スレッドで、どのように使用する予定かをお知らせください。
  • ハッシュタグ #ContactPicker を使用して @ChromiumDev にツイートを送信し、どこでどのように使用しているかをお知らせください。

関連情報

ありがとう

この機能を実装してくれた Finnur Thorarinsson と Rayan Kanso に感謝します。また、デモのためにコードを盗み、リファクタリングしてくれた Peter Beverloo にも感謝します。

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