Bộ chọn người liên hệ cho web

Contact Picker API giúp người dùng dễ dàng chia sẻ danh bạ trong danh sách liên hệ.

Pete LePage

Contact Picker API là gì?

Quyền truy cập vào danh bạ của người dùng trên thiết bị di động là một tính năng của các ứng dụng iOS/Android kể từ (gần như) thuở sơ khai. Đây là một trong những yêu cầu phổ biến nhất về tính năng mà tôi nhận được từ các nhà phát triển web và thường là lý do chính khiến họ tạo một ứng dụng iOS/Android.

Có trong Chrome 80 trên Android M trở lên, Contact Picker API spec là một API theo yêu cầu, cho phép người dùng chọn các mục trong danh sách liên hệ và chia sẻ thông tin chi tiết có giới hạn của các mục đã chọn với một trang web. Nhờ đó, người dùng chỉ chia sẻ những gì họ muốn, khi họ muốn và giúp người dùng dễ dàng liên hệ và kết nối với bạn bè và gia đình hơn.

Ví dụ: một ứng dụng email dựa trên web có thể dùng Contact Picker API để chọn(các) người nhận email. Một ứng dụng thoại qua giao thức Internet có thể tra cứu số điện thoại cần gọi. Hoặc một mạng xã hội có thể giúp người dùng khám phá những người bạn đã tham gia.

Sử dụng API Bộ chọn danh bạ

Contact Picker API yêu cầu một lệnh gọi phương thức có tham số options chỉ định các loại thông tin liên hệ mà bạn muốn. Phương thức thứ hai cho bạn biết thông tin mà hệ thống cơ bản sẽ cung cấp.

Phát hiện đối tượng

Để kiểm tra xem Contact Picker API có được hỗ trợ hay không, hãy sử dụng:

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

Ngoài ra, trên Android, Công cụ chọn người liên hệ yêu cầu Android M trở lên.

Mở Trình chọn địa chỉ liên hệ

Điểm truy cập vào Contact Picker API là navigator.contacts.select(). Khi được gọi, phương thức này sẽ trả về một lời hứa và cho thấy trình chọn người liên hệ, cho phép người dùng chọn(các) người liên hệ mà họ muốn chia sẻ với trang web. Sau khi chọn nội dung cần chia sẻ và nhấp vào Xong, lời hứa sẽ được thực hiện với một mảng các số liên hệ do người dùng chọn.

Khi gọi select(), bạn phải cung cấp một mảng các thuộc tính mà bạn muốn trả về dưới dạng tham số đầu tiên (với các giá trị được phép là bất kỳ giá trị nào trong số 'name', 'email', 'tel', 'address' hoặc 'icon') và tuỳ chọn là liệu bạn có thể chọn nhiều người liên hệ làm tham số thứ hai hay không.

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

Bạn chỉ có thể gọi Contacts Picker API từ một bối cảnh duyệt web cấp cao nhất an toàn và giống như các API mạnh mẽ khác, API này yêu cầu một cử chỉ của người dùng.

Phát hiện các thuộc tính có sẵn

Để phát hiện những thuộc tính có sẵn, hãy gọi navigator.contacts.getProperties(). Phương thức này trả về một lời hứa được giải quyết bằng một mảng các chuỗi cho biết những thuộc tính có sẵn. Ví dụ: ['name', 'email', 'tel', 'address']. Bạn có thể truyền các giá trị này đến select().

Xin lưu ý rằng không phải lúc nào các thuộc tính cũng có sẵn và các thuộc tính mới có thể được thêm vào. Trong tương lai, các nền tảng và nguồn liên hệ khác có thể hạn chế những thuộc tính được chia sẻ.

Xử lý kết quả

Contact Picker API trả về một mảng các số liên hệ và mỗi số liên hệ bao gồm một mảng các thuộc tính được yêu cầu. Nếu một người liên hệ không có dữ liệu cho thuộc tính được yêu cầu hoặc người dùng chọn không chia sẻ một thuộc tính cụ thể, thì API sẽ trả về một mảng trống. (Tôi mô tả cách người dùng chọn các thuộc tính trong phần Quyền kiểm soát của người dùng.)

Ví dụ: nếu một trang web yêu cầu name, email và tel, đồng thời người dùng chọn một số liên hệ duy nhất có dữ liệu trong trường tên, cung cấp 2 số điện thoại nhưng không có địa chỉ email, thì phản hồi được trả về sẽ là:

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

Tính bảo mật và quyền truy cập

Nhóm Chrome đã thiết kế và triển khai Contact Picker API dựa trên các nguyên tắc cốt lõi được xác định trong Kiểm soát quyền truy cập vào các tính năng mạnh mẽ của nền tảng web, bao gồm quyền kiểm soát của người dùng, tính minh bạch và tính tiện dụng. Tôi sẽ giải thích từng loại.

Quyền kiểm soát của người dùng

Quyền truy cập vào danh bạ của người dùng là thông qua bộ chọn và chỉ có thể được gọi bằng cử chỉ của người dùng, trong một ngữ cảnh duyệt web cấp cao nhất an toàn. Điều này đảm bảo rằng một trang web không thể hiện trình chọn khi tải trang hoặc hiện trình chọn một cách ngẫu nhiên mà không có ngữ cảnh nào.

Ảnh chụp màn hình, người dùng có thể chọn những tài sản cần chia sẻ.
Người dùng có thể chọn không chia sẻ một số tài sản. Trong ảnh chụp màn hình này, người dùng đã bỏ chọn nút "Số điện thoại". Mặc dù trang web yêu cầu số điện thoại, nhưng số điện thoại sẽ không được chia sẻ với trang web đó.

Không có lựa chọn chọn hàng loạt tất cả người liên hệ để khuyến khích người dùng chỉ chọn những người liên hệ mà họ cần chia sẻ cho trang web cụ thể đó. Người dùng cũng có thể kiểm soát những tài sản được chia sẻ với trang web bằng cách bật/tắt nút tài sản ở đầu trình chọn.

Sự minh bạch

Để làm rõ thông tin liên hệ nào đang được chia sẻ, bộ chọn luôn hiển thị tên và biểu tượng của người liên hệ, cùng với mọi thuộc tính mà trang web đã yêu cầu. Ví dụ: nếu một trang web yêu cầu name, email và tel, thì cả 3 thuộc tính này sẽ xuất hiện trong bộ chọn. Ngoài ra, nếu một trang web chỉ yêu cầu tel, thì bộ chọn sẽ chỉ hiển thị tên và số điện thoại.

Ảnh chụp màn hình của bộ chọn cho trang web yêu cầu tất cả tài sản.
Trình chọn, trang web yêu cầu name, email và tel, một số liên hệ được chọn.
Ảnh chụp màn hình của bộ chọn cho trang web chỉ yêu cầu số điện thoại.
Trình chọn, trang web chỉ yêu cầu tel, một người liên hệ được chọn.
Ảnh chụp màn hình của bộ chọn khi một người liên hệ được nhấn và giữ.
Kết quả của thao tác nhấn và giữ một người liên hệ.

Khi bạn nhấn và giữ một người liên hệ, tất cả thông tin sẽ xuất hiện nếu người liên hệ đó được chọn. (Xem hình ảnh liên hệ của Mèo Cheshire.)

Không có quyền duy trì

Quyền truy cập vào danh bạ là theo yêu cầu và không được duy trì. Mỗi khi muốn truy cập, trang web phải gọi navigator.contacts.select() bằng một cử chỉ của người dùng và người dùng phải chọn(các) số liên hệ mà họ muốn chia sẻ với trang web.

Phản hồi

Nhóm Chrome muốn biết trải nghiệm của bạn với API Trình chọn danh bạ.

Bạn gặp vấn đề khi triển khai?

Bạn có phát hiện thấy lỗi trong quá trình triển khai của Chrome không? Hay việc triển khai có khác với quy cách không?

  • Gửi báo cáo lỗi tại https://new.crbug.com. Hãy nhớ cung cấp càng nhiều thông tin chi tiết càng tốt, đưa ra hướng dẫn đơn giản để mô phỏng lỗi và đặt Components (Thành phần) thành Blink>Contacts.

Bạn đang lên kế hoạch sử dụng API này?

Bạn có dự định sử dụng Contact Picker API không? Sự ủng hộ công khai của bạn giúp nhóm Chrome ưu tiên các tính năng và cho các nhà cung cấp trình duyệt khác thấy tầm quan trọng của việc hỗ trợ các tính năng này.

Đường liên kết hữu ích

Cảm ơn bạn!

Xin gửi lời cảm ơn chân thành đến Finnur Thorarinsson và Rayan Kanso, những người đang triển khai tính năng này, cũng như Peter Beverloo, người có mã mà tôi đã lấy cắp một cách trơ trẽn và tái cấu trúc cho bản minh hoạ.

Tái bút: Tên trong trình chọn người liên hệ của tôi là các nhân vật trong truyện Alice ở xứ sở thần tiên.