網頁版聯絡人選擇器

使用者可以透過 Contact Picker API,輕鬆分享聯絡人清單中的聯絡人。

什麼是 Contact Picker API?

自古以來 (幾乎),iOS/Android 應用程式就提供存取行動裝置上使用者聯絡人的功能。這是網頁開發人員最常提出的功能要求之一,也是他們建構 iOS/Android 應用程式的主要原因。

聯絡人挑選器 API 規格適用於 Android M 以上版本,是隨選 API,可讓使用者從聯絡人清單中選取項目,並與網站分享所選項目的有限詳細資料。使用者可以選擇要分享的內容和時間,並輕鬆與親友聯絡。

舉例來說,網路電子郵件用戶端可以使用 Contact Picker API 選取電子郵件收件者。網際網路通話應用程式可以查詢要撥打的電話號碼。或者,社群網路可以協助使用者找出已加入的朋友。

使用 Contact Picker API

Contact Picker API 需要使用選項參數呼叫方法,指定所需的聯絡資訊類型。第二種方法會說明基礎系統提供的資訊。

特徵偵測

如要檢查是否支援 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'),並視需要提供是否可選取多個聯絡人做為第二個參數。

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,而使用者選取只有名稱欄位有資料的單一聯絡人,並提供兩個電話號碼,但沒有電子郵件地址,則傳回的回應會是:

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

安全性和權限

Chrome 團隊設計及實作了 Contact Picker API,並採用「控管強大的網頁平台功能存取權」中定義的核心原則,包括使用者控制權、透明度和人體工學。以下將逐一說明。

使用者控制項

使用者可透過挑選器存取聯絡人,且只能在安全的頂層瀏覽環境中,透過使用者手勢呼叫挑選器。這麼做可確保網站不會在網頁載入時顯示挑選器,也不會在沒有任何脈絡的情況下隨機顯示挑選器。

螢幕截圖:使用者可以選擇要分享哪些房源。
使用者可以選擇不分享部分屬性。在此螢幕截圖中,使用者已取消勾選「電話號碼」按鈕。即使網站要求提供電話號碼,系統也不會將電話號碼分享給網站。

系統不會提供大量選取所有聯絡人的選項,而是鼓勵使用者只選取要與特定網站分享的聯絡人。使用者也可以切換挑選器頂端的屬性按鈕,控管要與網站共用哪些屬性。

透明度

為清楚說明要分享哪些聯絡資料,挑選器一律會顯示聯絡人姓名和圖示,以及網站要求的任何屬性。舉例來說,如果網站要求 nameemailtel,這三項屬性都會顯示在挑選器中。或者,如果網站只要求 tel,選擇器只會顯示名稱和電話號碼。

網站要求所有屬性的選擇器螢幕截圖。
選擇器、要求 nameemailtel 的網站,已選取一個聯絡人。
網站只要求提供電話號碼時,系統顯示的選擇器畫面截圖。
選擇器,網站僅要求 tel,已選取一個聯絡人。
長按聯絡人時,挑選器會顯示的螢幕截圖。
長按聯絡人後顯示的結果。

長按聯絡人會顯示選取該聯絡人後要分享的所有資訊。(請參閱柴郡貓聯絡人圖片)。

權限不會保留

聯絡人存取權是依要求提供,不會持續保留。每次網站想存取聯絡人時,都必須透過使用者手勢呼叫 navigator.contacts.select(),且使用者必須個別選擇要與網站分享的聯絡人。

意見回饋

Chrome 團隊想瞭解您使用 Contact Picker API 的體驗。

導入時發生問題嗎?

您是否發現 Chrome 實作方式有錯誤?還是實作方式與規格不同?

  • 請前往 https://new.crbug.com 回報錯誤。請務必盡可能提供詳細資料、簡單的錯誤重現說明,並將「Components」設為 Blink>Contacts

打算使用 API 嗎?

您打算使用 Contact Picker API 嗎?您的公開支持有助於 Chrome 團隊排定功能優先順序,並向其他瀏覽器供應商展現支援這些功能的重要性。

實用連結

謝謝

特別感謝 Finnur Thorarinsson 和 Rayan Kanso 實作這項功能,以及 Peter Beverloo 的程式碼,我毫不避諱地竊取並重構了這些程式碼,用於示範。

附註:聯絡人挑選器中的名稱是《愛麗絲夢遊仙境》的角色。