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ọ.
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 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, thông số kỹ thuật API bộ chọn danh bạ 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ạ 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. 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 thoại qua 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 đị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 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 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 có thể chọn nhiều 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 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 một địa chỉ liên hệ không có dữ liệu cho tài sản được yêu cầu hoặc người dùng chọn không chia sẻ một tài sản 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 bước.
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 sẽ thông qua bộ chọn. Bộ chọn này chỉ có thể được gọi bằng cử chỉ của người dùng, trong ngữ 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.
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ả ba 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.
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 Cheshire Cat.)
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 đề trong quá trình triển khai?
Bạn có phát hiện lỗi khi 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ó 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 đó.
- Hãy chia sẻ cách bạn dự định sử dụng công cụ này trên luồng thảo luận Discourse của WICG.
- Gửi một tweet đến @ChromiumDev bằng hashtag
#ContactPicker
và cho chúng tôi biết bạn đang sử dụng ở đâu và như thế nào.
Đường liên kết hữu ích
- Video giải thích công khai
- Quy cách của Trình chọn địa chỉ liên hệ
- Bản minh hoạ về API Bộ chọn địa chỉ liên hệ và Nguồn minh hoạ về API Bộ chọn địa chỉ liên hệ
- Theo dõi lỗi
- Mục nhập trên ChromeStatus.com
- Thành phần Blink:
Blink>Contacts
Cảm ơn bạn!
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.