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

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

Pete LePage

Contact Picker API とは

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

Android M 以降の Chrome 80 で利用可能な Contact Picker API 仕様は、ユーザーが連絡先リストからエントリを選択し、選択したエントリの限定的な詳細情報をウェブサイトと共有できるようにするオンデマンド API です。ユーザーは、必要なときに必要なものだけを共有できます。また、友だちや家族と簡単に連絡を取り合うことができます。

たとえば、ウェブベースのメール クライアントは、連絡先選択ツール API を使用してメールの受信者を選択できます。VoIP アプリは、どの電話番号に電話をかけるかを検索できます。また、ソーシャル ネットワークで、すでに参加している友だちを確認することもできます。

Contact Picker API の使用

連絡先選択ツール API では、必要な連絡先情報の種類を指定するオプション パラメータを含むメソッド呼び出しが必要です。2 つ目のメソッドは、基盤となるシステムが提供する情報を返します。

特徴検出

連絡先選択ツール API がサポートされているかどうかを確認するには、次のコードを使用します。

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

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

連絡先ピッカーを開く

Contact Picker API のエントリ ポイントは navigator.contacts.select() です。呼び出されると、プロミスを返し、連絡先選択ツールを表示して、ユーザーがサイトと共有する連絡先を選択できるようにします。共有する内容を選択して [完了] をクリックすると、ユーザーが選択した連絡先の配列で 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.
}

連絡先選択ツール API は、安全な最上位のブラウジング コンテキストからのみ呼び出すことができ、他の強力な API と同様に、ユーザー操作が必要です。

使用可能なプロパティを検出する

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

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

結果を処理する

連絡先選択ツール API は連絡先の配列を返します。各連絡先には、リクエストされたプロパティの配列が含まれます。連絡先にリクエストされたプロパティのデータがない場合、またはユーザーが特定のプロパティの共有をオプトアウトした場合、API は空の配列を返します。（ユーザーがプロパティを選択する方法については、ユーザー制御セクションで説明します）。

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

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

セキュリティと権限

Chrome チームは、強力なウェブ プラットフォーム機能へのアクセスの制御で定義されたユーザー制御、透明性、人間工学などの基本原則を使用して、連絡先選択ツール API を設計、実装しました。それぞれについて説明します。

ユーザー コントロール

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

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

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

透明性

共有される連絡先の詳細を明確にするため、ピッカーには常に連絡先の名前とアイコンが表示され、サイトがリクエストしたプロパティも表示されます。たとえば、サイトが name、email、tel をリクエストした場合、3 つのプロパティすべてがピッカーに表示されます。また、サイトが tel のみをリクエストしている場合、ピッカーには名前と電話番号のみが表示されます。

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

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

権限の永続性なし

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

フィードバック

Chrome チームは、連絡先選択ツール API の使用感について皆様のご意見をお待ちしています。

実装に関する問題ですか？

Chrome の実装にバグが見つかりましたか？それとも、実装が仕様と異なるのでしょうか？

  • https://new.crbug.com でバグを報告します。できるだけ詳細な情報を記載し、バグを再現するための簡単な手順を記載して、[コンポーネント] を Blink>Contacts に設定してください。

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

連絡先選択ツール API を使用する予定はありますか？公開サポートは、Chrome チームが機能の優先順位を決定するのに役立ち、他のブラウザ ベンダーにサポートの重要性を示すことができます。

関連情報

ありがとう

この機能を実装している Finnur Thorarinsson と Rayan Kanso、そしてデモ用にコードを盗んでリファクタリングした Peter Beverloo に感謝します。

追伸: 連絡先選択ツールに表示されている名前は、『不思議の国のアリス』の登場人物です。