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

API Bộ chọn địa chỉ liên hệ giúp người dùng dễ dàng chia sẻ địa chỉ liên hệ từ 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 đã trở thành một tính năng của các ứng dụng iOS/Android kể từ đó (gần như) bình minh của thời gian. Đây là một trong những yêu cầu phổ biến nhất về tính năng Tôi nghe được câu chuyện của các nhà phát triển web và thường là lý do chính khiến họ tạo ra một ứng dụng iOS/Android .

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

Ví dụ: ứng dụng email dựa trên nền tảng web có thể sử dụng API Bộ chọn địa chỉ liên hệ để chọn(những) người nhận email. Ứng dụng lồng tiếng IP có thể tra cứu số điện thoại để gọi. Hoặc một mạng xã hội có thể giúp người dùng khám phá ra mà bạn bè đã tham gia.

Sử dụng API Bộ chọn địa chỉ liên hệ

API Bộ chọn địa chỉ liên hệ yêu cầu lệnh gọi phương thức có tham số tuỳ chọn chỉ định các loại thông tin liên hệ mà bạn muốn. Phương pháp 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 API Bộ chọn địa chỉ liên hệ 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ở Bộ chọn Địa chỉ Liên hệ

Điểm truy cập vào API Bộ chọn địa chỉ liên hệ là navigator.contacts.select(). Khi được gọi, lệnh này sẽ trả về một lời hứa và hiển thị bộ chọn người 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 chọn nội dung bạn muốn chia sẻ rồi nhấp vào Xong, lời hứa sẽ được giải quyết bằng mảng đị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 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ỳ 'name', 'email', 'tel', 'address' hoặc 'icon'), và có thể lựa chọn xem có thể liên hệ với nhiều người liên hệ hay không được chọn 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ảo mật, ngữ cảnh duyệt web cấp cao nhất và giống như các API mạnh mẽ khác, tính năng này đòi hỏi 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 cơ sở lưu trú có sẵn, hãy gọi navigator.contacts.getProperties(). Phương thức này trả về một hứa hẹn phân giải bằng một mảng chuỗi cho biết các cơ sở lưu trú. 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 tài sản không phải lúc nào cũng có sẵn và tài sản mới có thể đã thêm. Trong tương lai, các nền tảng khác và nguồn liên hệ có thể hạn chế những thuộc tính nào sẽ được dùng chung.

Xử lý kết quả

API Bộ chọn địa chỉ liên hệ trả về một mảng địa chỉ liên hệ và mỗi địa chỉ liên hệ bao gồm một mảng các thuộc tính được yêu cầu. Nếu người liên hệ không có dữ liệu về thuộc tính được yêu cầu hoặc người dùng chọn không chia sẻ 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 cơ sở lưu trú trong phầ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 và một người dùng chọn một địa chỉ liên hệ có dữ liệu trong trường tên, cung cấp hai nhưng không có địa chỉ email, câu trả lờ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 địa chỉ liên hệ bằng cách sử dụng nguyên tắc đượ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 cả quyền kiểm soát của người dùng, tính minh bạch và công thái học. Tôi sẽ giải thích từng bước.

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

Quyền truy cập vào danh bạ qua bộ chọn và chỉ có thể được gọi bằng cử chỉ của người dùng trong bối cảnh duyệt web bảo mật ở cấp cao nhất. Điều này đảm bảo rằng một 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 những thuộc tính cầ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 "Số điện thoại" . Mặc dù trang web được yêu cầu cung cấp số điện thoại, chúng sẽ không được chia sẻ với trang web.

Không thể chọn hàng loạt tất cả người liên hệ để khuyến khích người dùng để chọn chỉ những địa chỉ liên hệ mà họ cần chia sẻ cho của bạn. 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 thuộc tính ở đầ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 sẽ 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 có đã yêu cầu. Ví dụ: nếu một trang web yêu cầu name, email và tel, cả 3 tài sản đều 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ỉ cho thấy tên, và số điện thoại.

Ảnh chụp màn hình bộ chọn cho trang web yêu cầu tất cả thuộc tính.
Bộ chọn, trang web yêu cầu name, email và tel, đã chọn một người liên hệ.
Ảnh chụp màn hình 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, đã chọn một địa chỉ liên hệ.
Ả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 việc nhấn và giữ một mục liên hệ.

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

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

Quyền truy cập vào danh bạ theo yêu cầu và không được duy trì. Mỗi khi một trang web muốn thì mã này 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) địa chỉ liên hệ họ muốn chia sẻ với trang web.

Phản hồi

Nhóm Chrome muốn biết ý kiến của bạn về trải nghiệm của bạn với Bộ chọn địa chỉ liên hệ API.

Bạn gặp vấn đề trong quá trình triển khai?

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

  • Báo cáo lỗi tại https://new.crbug.com. Hãy nhớ bao gồm nhiều chi tiết nhất có thể, cung cấp hướng dẫn đơn giản để tái tạo lỗi và đặt Components (Thành phần) thành Blink>Contacts. Đột phá hoạt động rất hiệu quả để chia sẻ việc mô phỏng nhanh chóng và dễ dàng vấn đề.

Dự định sử dụng API?

Bạn có định sử dụng API Bộ chọn địa chỉ liên hệ không? Sự hỗ trợ công khai của bạn giúp Nhóm Chrome ưu tiên các tính năng và hướng dẫn các nhà cung cấp trình duyệt khác điều quan trọng là cần hỗ trợ họ.

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

Cảm ơn bạn!

Xin chân thành cảm ơn và cảm ơn Finnur Horarinsson và Rayan Kanso, những người triển khai tính năng này và Peter Beverloo, người có tầm ảnh hưởng code mà tôi xấu hổ lấy cắp và tái cấu trúc cho bản minh hoạ.

Tái bút: 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.