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

Contact Picker API (API bộ chọn người liên hệ) giúp người dùng dễ dàng chia sẻ người liên hệ trong danh bạ của họ.

Pete LePage

API Bộ chọn địa chỉ liên hệ 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 từ (gần như) khi mới bắt đầu. Đâ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ọ xây dựng ứng dụng iOS/Android.

Có trong Chrome 80 trên Android M trở lên, quy cách của API Bộ chọn địa chỉ liên hệ là một API theo yêu cầu cho phép người dùng chọn các mục trong danh bạ của họ và chia sẻ một số ít thông tin về các mục đã chọn với một trang web. Tính năng này cho phép người dùng chỉ chia sẻ những nội dung họ muốn vào thời điểm họ muốn, đồng thời giúp người dùng dễ dàng liên hệ cũng như kết nối với bạn bè và gia đình.

Ví dụ: ứng dụng email dựa trên web có thể sử dụng API Bộ chọn người liên hệ để chọn(các) người nhận email. Ứng dụng lồng tiếng IP 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ạ

API Bộ chọn người liên hệ yêu cầu một lệnh gọi phương thức với tham số tuỳ chọn 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 tính nă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 địa chỉ 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, lớp này sẽ trả về một lời hứa và hiển thị bộ chọn địa chỉ liên hệ, cho phép người dùng chọn(các) địa chỉ 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 phân giải bằng một mảng gồm các địa chỉ 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 được 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à có thể chọn nhiều người liên hệ làm tham số thứ hai.

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 API bộ chọn danh bạ 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 phân giải bằng một mảng chuỗi cho biết các 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().

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

Xử lý kết quả

Contact Picker API trả về một mảng gồm các thông tin liên hệ, và mỗi thông tin liên hệ bao gồm một mảng gồm các thuộc tính được yêu cầu. Nếu 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 Kiểm soát người dùng.)

Ví dụ: nếu một trang web yêu cầu name, email và tel, và người dùng chọn một người liên hệ có dữ liệu trong trường tên, cung cấp hai 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 API bộ chọn người liên hệ bằng cách sử dụng các nguyên tắc cốt lõi được xác định trong bài viết 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 cả quyền kiểm soát của người dùng, tính minh bạch và tính công thái học. 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à bạn chỉ có thể gọi bộ chọn bằng một cử chỉ của người dùng, trong ngữ cảnh duyệt web cấp cao nhất an toàn. Điều này đảm bảo rằng trang web không thể hiển thị bộ chọn khi tải trang hoặc hiển thị ngẫu nhiên bộ chọn mà không có bất kỳ ngữ cảnh nào.

Ảnh chụp màn hình, người dùng có thể chọn tài sản để chia sẻ.
Người dùng có thể chọn không chia sẻ một số thuộc tính. Trong ảnh chụp màn hình này, người dùng đã bỏ đánh dấu nút "Số điện thoại". Mặc dù trang web này đã yêu cầu cung cấp 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ả các địa chỉ liên hệ, vì vậy, người dùng nên chỉ chọn những địa chỉ 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 bộ 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 tài sản 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.
Bộ chọn, trang web yêu cầu name, email và tel, một người 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.
Bộ 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 bộ chọn khi người dùng nhấn và giữ một địa chỉ liên hệ.
Kết quả của thao tác nhấn và giữ một người liên hệ.

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

Không có quyền ổn định

Quyền truy cập vào danh bạ là theo yêu cầu và không tồn tại lâu dài. Mỗi khi một trang web 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 riêng(các) người 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 bộ chọn người liên hệ.

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

Bạn có phát hiện lỗi trong quá trình triển khai Chrome không? Hay cách triển khai khác với thông số kỹ thuật?

  • Gửi 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, cung cấp hướng dẫn đơn giản để tái hiện lỗi và đặt Components (Thành phần) thành Blink>Contacts. Glitch rất hữu ích để chia sẻ các bản sao vấn đề nhanh chóng và dễ dàng.

Bạn có dự định sử dụng API này không?

Bạn có định sử dụng API Bộ chọn địa chỉ liên hệ 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 đó.

Các đường liên kết hữu ích

Cảm ơn bạn!

Cảm ơn Finnur Thorarinsson và Rayan Kanso đã triển khai tính năng này và Peter Beverloo, người đã lấy cắp một cách vô tư mã của tôi để tái cấu trúc cho bản minh hoạ.

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