連絡先ピッカー API

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

連絡先ピッカー API (Contact Picker API) は、ユーザーが連絡先リストから項目を選択し、選択した項目の限定された詳細をウェブサイトやアプリケーションで共有できるようにします。

メモ: この API はウェブワーカーでは使用できません(WorkerNavigator に公開されていません)。

連絡先ピッカー API の概念と使用法

連絡先へのアクセスは、長い間、ネイティブアプリケーションの中で利用できる機能でした。連絡先ピッカー API は、その機能をウェブアプリケーションに提供します。

用途としては、メールやチャットアプリケーションでメッセージを送る連絡先を選択したり、Voice over IP ( VOIP ) で使用する連絡先の電話番号を選択したり、ソーシャルプラットフォームに既に参加している連絡先を発見したりするために使用されることがあります。また、ユーザーエージェントは、ユーザー機器上の他のアプリケーションとの一貫した使い勝手も提供することができます。

ContactsManager インターフェイスの select メソッドを呼び出すと、ユーザーに連絡先ピッカーが存在し、ユーザーはウェブアプリケーションと共有する連絡先情報を選択することができます。連絡先ピッカーを表示する許可を得るには、ユーザーとの対話が必要です。また、連絡先へのアクセスは永続的ではなく、アプリケーションからの要求があるたびにユーザーがアクセスを許可する必要があります。

このAPIが利用可能なのは、安全な最上位の閲覧コンテキストからのみであり、連絡先データの機密性とプライバシーについてとても慎重に考慮されています。共有するデータを選択する責任はユーザーにあり、選択した連絡先の特定のデータのみを許可し、他の連絡先のデータには一切アクセスできないようになっています。

インターフェイス

ContactAddress

物理的な住所を表します。

ContactsManager

ユーザーがウェブアプリケーションで連絡先の限定された詳細を選択し、共有する方法を提供します。

他のすべての機能にアクセス可能な ContactsManager オブジェクトのインスタンスを返します。

機能検出

以下のコードは、連絡先ピッカー API に対応しているかどうかを調べるものです。

js
const supported = "contacts" in navigator;

対応しているプロパティを調べる

以下の非同期関数は、getProperties() メソッドを使用して、対応しているプロパティを調べます。

js
async function checkProperties() {
  const supportedProperties = await navigator.contacts.getProperties();
  if (supportedProperties.includes("name")) {
    // 名前に対応したコードを実行
  }
  if (supportedProperties.includes("email")) {
    // メールアドレスに対応したコードを実行
  }
  if (supportedProperties.includes("tel")) {
    // 電話番号に対応したコードを実行
  }
  if (supportedProperties.includes("address")) {
    // 住所に対応したコードを実行
  }
  if (supportedProperties.includes("icon")) {
    // アバターに対応したコードを実行
  }
}

連絡先の選択

以下の例では、それぞれの連絡先に対して取得するプロパティの配列を設定し、また、複数の連絡先が選択できるようにオプションオブジェクトを設定しています。

そして、select() メソッドを使用して、ユーザーに連絡先ピッカーインターフェイスを表示し、選択された結果を処理する非同期関数を定義しています。

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

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

handleResults() は開発者が定義する関数です。

仕様書

Specification
Contact Picker API
# contacts-manager

ブラウザーの互換性

BCD tables only load in the browser

関連情報