웹용 연락처 선택 도구

Contact Picker API는 사용자가 연락처 목록에서 연락처를 쉽게 공유할 수 있도록 합니다.

Pete LePage

Contact Picker API란 무엇인가요?

휴대기기에서 사용자의 연락처에 액세스하는 기능은 거의 처음부터 iOS/Android 앱의 기능이었습니다. 웹 개발자로부터 가장 자주 듣는 기능 요청 중 하나이며 iOS/Android 앱을 빌드하는 주요 이유가 되기도 합니다.

Android M 이상에서 Chrome 80부터 사용할 수 있는 Contact Picker API 사양은 사용자가 연락처 목록에서 항목을 선택하고 선택한 항목의 제한된 세부정보를 웹사이트와 공유할 수 있는 주문형 API입니다. 사용자가 원하는 시기와 방식에 따라 원하는 콘텐츠만 공유할 수 있으며, 친구 및 가족과 더 쉽게 소통할 수 있습니다.

예를 들어 웹 기반 이메일 클라이언트는 Contact Picker API를 사용하여 이메일 수신자를 선택할 수 있습니다. VoIP 앱이 전화를 걸 전화번호를 조회할 수 있습니다. 또는 소셜 네트워크를 사용하면 사용자가 이미 가입한 친구를 찾을 수 있습니다.

Contact Picker API 사용

Contact Picker API를 사용하려면 원하는 연락처 정보의 유형을 지정하는 옵션 매개변수가 포함된 메서드 호출이 필요합니다. 두 번째 메서드는 기본 시스템에서 제공할 정보를 알려줍니다.

기능 감지

Contact Picker API가 지원되는지 확인하려면 다음을 사용하세요.

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

또한 Android에서는 연락처 선택 도구를 사용하려면 Android M 이상이 필요합니다.

연락처 선택 도구 열기

Contact Picker API의 진입점은 navigator.contacts.select()입니다. 호출되면 약속을 반환하고 연락처 선택 도구를 표시하여 사용자가 사이트와 공유할 연락처를 선택할 수 있도록 합니다. 공유할 항목을 선택하고 완료를 클릭하면 사용자가 선택한 연락처 배열로 약속이 확인됩니다.

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

Contacts Picker API는 안전한 최상위 탐색 컨텍스트에서만 호출할 수 있으며, 다른 강력한 API와 마찬가지로 사용자 동작이 필요합니다.

사용 가능한 속성 감지

사용 가능한 속성을 감지하려면 navigator.contacts.getProperties()를 호출합니다. 사용 가능한 속성을 나타내는 문자열 배열로 확인되는 프라미스를 반환합니다. 예를 들면 ['name', 'email', 'tel', 'address']입니다. 이러한 값을 select()에 전달할 수 있습니다.

속성이 항상 제공되는 것은 아니며 새로운 속성이 추가될 수 있습니다. 향후 다른 플랫폼 및 연락처 소스에서 공유할 속성을 제한할 수 있습니다.

결과 처리

Contact Picker API는 연락처 배열을 반환하며 각 연락처에는 요청된 속성 배열이 포함됩니다. 요청된 속성에 관한 데이터가 연락처에 없거나 사용자가 특정 속성을 공유하지 않도록 선택한 경우 API는 빈 배열을 반환합니다. (사용자 컨트롤 섹션에서는 사용자가 속성을 선택하는 방법을 설명합니다.)

예를 들어 사이트에서 name, email, tel를 요청하고 사용자가 이름 필드에 데이터가 있는 연락처 하나를 선택하고 전화번호 2개를 입력했지만 이메일 주소가 없는 경우 다음과 같은 응답이 반환됩니다.

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

보안 및 권한

Chrome팀은 사용자 제어, 투명성, 인체공학을 비롯하여 강력한 웹 플랫폼 기능에 대한 액세스 제어에 정의된 핵심 원칙을 사용하여 Contact Picker API를 설계하고 구현했습니다. 각각에 대해 설명해 드리겠습니다.

사용자 제어

사용자의 연락처에 대한 액세스는 선택 도구를 통해 이루어지며 안전한 최상위 탐색 컨텍스트에서 사용자 동작으로만 호출할 수 있습니다. 이렇게 하면 사이트에서 페이지 로드 시 선택 도구를 표시하거나 컨텍스트 없이 선택 도구를 무작위로 표시할 수 없습니다.

스크린샷: 사용자가 공유할 속성을 선택할 수 있습니다.
사용자는 일부 속성을 공유하지 않도록 선택할 수 있습니다. 이 스크린샷에서 사용자는 '전화번호' 버튼을 선택 해제했습니다. 사이트에서 전화번호를 요청하더라도 사이트에 공유되지 않습니다.

모든 연락처를 일괄 선택하는 옵션은 없으므로 사용자는 특정 웹사이트에 공유해야 하는 연락처만 선택하는 것이 좋습니다. 사용자는 선택 도구 상단의 속성 버튼을 전환하여 사이트와 공유할 속성을 제어할 수도 있습니다.

투명성

공유되는 연락처 세부정보를 명확히 하기 위해 선택 도구에는 항상 연락처 이름과 아이콘, 사이트에서 요청한 모든 속성이 표시됩니다. 예를 들어 사이트에서 name, email, tel를 요청하면 세 가지 속성이 모두 선택 도구에 표시됩니다. 또는 사이트에서 tel만 요청하는 경우 선택 도구에 이름과 전화번호만 표시됩니다.

모든 속성을 요청하는 사이트의 선택 도구 스크린샷
선별 도구, name, email, tel를 요청하는 사이트, 선택된 연락처 1개
전화번호만 요청하는 사이트의 선택 도구 스크린샷
선택 도구, tel만 요청하는 사이트, 연락처 1개가 선택되었습니다.
연락처를 길게 누르면 선택 도구가 표시되는 화면 스크린샷
연락처를 길게 누른 결과입니다.

연락처를 길게 누르면 연락처를 선택할 경우 공유되는 모든 정보가 표시됩니다. 체셔 캣 연락처 이미지를 참고하세요.

권한 지속성 없음

연락처에 대한 액세스는 주문형이며 유지되지 않습니다. 사이트에서 액세스 권한을 요청할 때마다 사용자 동작으로 navigator.contacts.select()를 호출해야 하며, 사용자는 사이트와 공유할 연락처를 개별적으로 선택해야 합니다.

의견

Chrome팀에서는 Contact Picker API 사용 경험에 관한 의견을 듣고자 합니다.

구현에 문제가 있나요?

Chrome 구현에서 버그를 발견했나요? 아니면 구현이 사양과 다른가요?

  • https://new.crbug.com에서 버그를 신고합니다. 최대한 많은 세부정보를 포함하고 버그 재현을 위한 간단한 안내를 제공하며 구성요소를 Blink>Contacts로 설정해야 합니다. Glitch는 쉽고 빠르게 문제를 재현하는 데 유용합니다.

API를 사용하려면 어떻게 해야 하나요?

Contact Picker API를 사용할 계획인가요? 공개적으로 지원하면 Chrome팀에서 기능의 우선순위를 지정하는 데 도움이 되며 다른 브라우저 공급업체에 기능을 지원하는 것이 얼마나 중요한지 보여줍니다.

유용한 링크

감사합니다.

이 기능을 구현하는 Finnur Thorarinsson과 Rayan Kanso, 그리고 데모를 위해 뻔뻔하게 훔치고 리팩터링한 코드를 제공해 준 Peter Beverloo에게 감사의 인사를 전합니다.

추신: 연락처 선택 도구의 이름은 이상한 나라의 앨리스에 나오는 캐릭터입니다.