Device.getContacts

함수형 API fetchContacts로도 같은 기능을 쓸 수 있어요.

기능 설명

사용자의 연락처 목록을 페이지 단위로 가져와요. size·offset으로 페이지네이션하고, query.contains로 이름 포함 검색을 할 수 있어요. offset은 첫 호출에 0, 이후에는 응답의 nextOffset을 사용해요.

연락처 읽기 권한이 없으면 FetchContactsPermissionError가 발생해요. Device.getContacts.getPermission() / Device.getContacts.openPermissionDialog()로 권한을 확인·요청할 수 있어요.

타입

Device.getContacts(options: FetchContactsOptions): Promise<ContactResult>;

Params

type FetchContactsOptions = {
  size: number;
  offset: number;
  query?: {
    contains?: string;
  };
};

Response

type ContactEntity = {
  name: string;
  phoneNumber: string;
};

type ContactResult = {
  result: ContactEntity[];
  nextOffset: number | null;
  done: boolean;
};

에러

에러는 클래스로 던져져요 — error instanceof FetchContactsPermissionError로 식별해요. 클래스는 @apps-in-toss/web-framework에서 import할 수 있어요.

에러 클래스	설명
FetchContactsPermissionError	연락처 읽기 권한이 거부된 경우예요. Device.getContacts.openPermissionDialog()로 다시 요청할 수 있어요.

예시 코드

import {
  Device,
  FetchContactsPermissionError,
} from "@apps-in-toss/web-framework";

let nextOffset = 0;
let done = false;

async function loadNextContacts() {
  if (done) {
    return;
  }

  try {
    const response = await Device.getContacts({
      size: 10,
      offset: nextOffset ?? 0,
      query: { contains: "김" },
    });

    for (const contact of response.result) {
      console.log(`${contact.name}: ${contact.phoneNumber}`);
    }

    nextOffset = response.nextOffset;
    done = response.done;
  } catch (error) {
    if (error instanceof FetchContactsPermissionError) {
      console.warn("연락처 읽기 권한이 없어요.");
      return;
    }
    console.error(error);
  }
}

document
  .getElementById("load-contacts")
  .addEventListener("click", loadNextContacts);