網頁版聯絡人選擇器

Contact Picker API 可讓使用者輕鬆分享聯絡人清單中的聯絡人。

Pete LePage

什麼是 Contact Picker API？

自從 iOS/Android 應用程式問世以來，使用者行動裝置上的聯絡資訊存取權一直是這類應用程式的功能。這是我聽到網頁開發人員最常提出的功能要求之一，也是他們建構 iOS/Android 應用程式的主要原因。

Contact Picker API 規格是 Android M 以上版本的 Chrome 80 推出的按需 API，可讓使用者從聯絡人清單中選取項目，並與網站分享所選項目的部分詳細資料。使用者可以隨時分享自己想分享的內容，並更輕鬆地與親朋好友聯繫。

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

使用 Contact Picker API

聯絡人挑選器 API 需要使用方法呼叫，其中包含指定所需聯絡資訊類型的選項參數。第二種方法會告訴您基礎系統會提供哪些資訊。

特徵偵測

如要檢查是否支援 Contact Picker API，請使用：

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

此外，在 Android 裝置上，聯絡人挑選工具需要 Android M 以上版本。

開啟聯絡人選擇工具

Contact Picker API 的進入點為 navigator.contacts.select()。在呼叫時，會傳回承諾並顯示聯絡人挑選器，讓使用者選取要與網站分享的聯絡人。選取要分享的內容並按一下「Done」後，承諾會解析使用者選取的聯絡人陣列。

呼叫 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.
}

聯絡人挑選器 API 只能從安全的頂層瀏覽內容中呼叫，而且與其他強大的 API 一樣，需要使用者手勢。

偵測可用的資源

如要偵測可用的屬性，請呼叫 navigator.contacts.getProperties()。它會傳回承諾，並以字串陣列解析，指出可用的屬性。例如：['name', 'email', 'tel', 'address']。您可以將這些值傳遞至 select()。

請注意，資源不一定隨時可用，且可能會新增資源。日後，其他平台和聯絡來源可能會限制要分享的資源。

處理結果

Contact Picker API 會傳回聯絡資料陣列，而每個聯絡資料都包含要求的屬性陣列。如果聯絡人沒有所要求屬性的資料，或是使用者選擇不分享特定屬性，API 就會傳回空陣列。(我會在「使用者控管」一節說明使用者如何選擇屬性)。

舉例來說，如果網站要求 name、email 和 tel，而使用者選取的聯絡人有名稱欄位資料、提供兩個電話號碼，但沒有電子郵件地址，則系統會傳回以下回應：

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

安全性和權限

Chrome 團隊根據「控管強大網路平台功能的存取權」一文中定義的核心原則，設計並實作了聯絡人挑選器 API，包括使用者控管、資訊公開和人體工學。我會逐一說明。

使用者控制項

使用者聯絡資料的存取權是透過挑選器取得，且只能在安全的頂層瀏覽內容上，透過使用者手勢呼叫。這麼做可確保網站不會在網頁載入時顯示挑選器，或在沒有任何背景資訊的情況下隨機顯示挑選器。

螢幕截圖，使用者可以選擇要分享的資源。
使用者可以選擇不分享部分資源。在這個螢幕截圖中，使用者已取消勾選「電話號碼」按鈕。即使網站要求提供電話號碼，系統也不會將電話號碼提供給該網站。

系統不會提供選取所有聯絡人的選項，因此建議使用者只選取他們需要分享給特定網站的聯絡人。使用者也可以切換挑選器頂端的資源按鈕，控管要與網站共用的資源。

透明度

為了清楚說明要分享哪些聯絡詳細資料，挑選器一律會顯示聯絡人的姓名和圖示，以及網站要求的任何屬性。舉例來說，如果網站要求 name、email 和 tel，則挑選器會顯示這三個屬性。或者，如果網站只要求 tel，則挑選器只會顯示名稱和電話號碼。

要求所有資源的網站選擇器螢幕截圖。
Picker、要求 name、email 和 tel 的網站，以及所選聯絡人。
網站只要求電話號碼時的挑選畫面截圖。
Picker，網站只要求 tel，已選取一個聯絡人。
長按聯絡人時，挑選器的螢幕截圖。
長按聯絡人的結果。

長按聯絡人，即可查看選取該聯絡人時會分享的所有資訊。(請參閱 Cheshire Cat 聯絡圖片)。

不保留權限

聯絡人的存取權是按需存取，不會保留。每當網站想要存取權限時，都必須使用使用者手勢呼叫 navigator.contacts.select()，且使用者必須個別選擇要與網站分享的聯絡人。

意見回饋

Chrome 團隊希望瞭解你使用 Contact Picker API 的體驗。

導入時發生問題？

你是否發現 Chrome 實作項目有錯誤？還是實作方式與規格不同？

  • 請前往 https://new.crbug.com 回報錯誤。請務必盡可能提供詳細資訊，提供重現錯誤的簡單操作說明，並將「元件」設為 Blink>Contacts。Glitch 可讓您快速輕鬆地重現問題。

打算使用 API 嗎？

您打算使用聯絡人挑選工具 API 嗎？您的公開支援有助於 Chrome 團隊決定功能的優先順序，並向其他瀏覽器供應商顯示支援這些功能的重要性。

實用連結

謝謝

在此要特別感謝負責實作這項功能的 Finnur Thorarinsson 和 Rayan Kanso，以及 Peter Beverloo，因為我為了示範，不顧廉恥地盜用他的程式碼並進行重構。

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