연락처

권한 설정이 필요해요

fetchContacts를 사용하기 전에 연락처 권한을 설정해야 해요. 권한 설정 가이드를 먼저 확인해 주세요.

---

연락처 가져오기

SDK 함수: fetchContacts

fetchContacts는 사용자의 연락처 목록을 페이지 단위로 가져오는 함수예요.

시그니처

function fetchContacts(options: {
  size: number;
  offset: number;
  query?: {
    contains?: string;
  };
}): Promise<ContactResult>;

파라미터

• options · 필수

  연락처를 가져올 때 지정하는 옵션 객체예요.

  • options.size · 필수

    한 번에 가져올 연락처 개수예요. 예를 들어, 10을 전달하면 최대 10개의 연락처를 가져와요.
  • options.offset · 필수

    가져올 연락처의 시작 지점이에요. 처음 호출할 때는 0을 전달해야 해요. 이후에는 이전 호출에서 반환된 nextOffset 값을 사용해요.

    • options.query · 필수

      추가적인 필터링 옵션이에요.

      • options.query.contains · 필수

        이름에 특정 문자열이 포함된 연락처만 가져오고 싶을 때 사용해요. 이 값을 전달하지 않으면 모든 연락처를 가져와요.

프로퍼티

• openPermissionDialog

  연락처 읽기 권한을 다시 요청하는 다이얼로그를 표시해요. 사용자는 "허용", "한 번만 허용", "안하기" 중 하나를 선택할 수 있어요. "허용"이나 "한 번만 허용"을 선택하면 allowed를 반환하고, "안하기"를 선택하면 denied를 반환해요.
• getPermission

  연락처 읽기 권한의 현재 상태를 반환해요. allowed는 사용자가 연락처 읽기 권한을 허용한 상태예요. denied는 사용자가 연락처 읽기 권한을 거부한 상태예요. notDetermined는 연락처 읽기 권한 요청을 한 번도 하지 않은 상태예요. 토스앱 설정에서 연락처 권한이 거절되어 있는 경우에는 osPermissionDenied를 반환해요.

반환 값

• Promise<ContactResult>

연락처 목록과 페이지네이션 정보를 포함한 객체를 반환해요.

• result: 가져온 연락처 목록이에요.
• nextOffset: 다음 호출에 사용할 오프셋 값이에요. 더 가져올 연락처가 없으면 null이에요.
• done: 모든 연락처를 다 가져왔는지 여부를 나타내요. 모두 가져왔다면 true예요.

연락처 권한 에러

에러 타입: FetchContactsPermissionError

연락처 권한이 거부되었을 때 발생하는 에러예요. 에러가 발생했을 때 error instanceof FetchContactsPermissionError를 통해 확인할 수 있어요.

시그니처

class FetchContactsPermissionError extends PermissionError {
  constructor();
}

예제

특정 문자열이 포함된 연락처 목록 가져오기

연락처 목록을 가져오는 예제예요. "권한 확인하기"버튼을 눌러서 현재 연락처 읽기 권한을 확인해요. 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 FetchContactsPermissionError를 반환해요. "권한 요청하기"버튼을 눌러서 연락처 읽기 권한을 요청할 수 있어요.

js

import { fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/web-framework';

async function handleFetchContacts() {
  try {
    const response = await fetchContacts({
      size: 10,
      offset: 0,
      query: { contains: '김' },
    });

    return response;
  } catch (error) {
    if (error instanceof FetchContactsPermissionError) {
      console.log('연락처 읽기 권한 없음');
    }
    console.error('연락처를 가져오는 데 실패했어요:', error);
  }
}

async function handleGetPermissionForFetchContacts() {
  const permission = await fetchContacts.getPermission();
  return permission;
}

async function handleOpenPermissionDialogForFetchContacts() {
  const permission = await fetchContacts.openPermissionDialog();
  return permission;
}

React

import { ContactEntity, fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function ContactsList() {
  const [contacts, setContacts] = useState<{
    result: ContactEntity[];
    nextOffset: number | null;
    done: boolean;
  }>({
    result: [],
    nextOffset: null,
    done: false,
  });

  const handlePress = async () => {
    try {
      if (contacts.done) {
        console.log('모든 연락처를 가져왔어요.');
        return;
      }

      const response = await fetchContacts({
        size: 10,
        offset: contacts.nextOffset ?? 0,
        query: { contains: '김' },
      });
      setContacts((prev) => ({
        result: [...prev.result, ...response.result],
        nextOffset: response.nextOffset,
        done: response.done,
      }));
    } catch (error) {
      if (error instanceof FetchContactsPermissionError) {
        console.log('연락처 읽기 권한 없음');
      }
      console.error('연락처를 가져오는 데 실패했어요:', error);
    }
  };

  return (
    <div>
      {contacts.result.map((contact, index) => (
        <span key={index}>
          {contact.name}: {contact.phoneNumber}
        </span>
      ))}
      <input
        type="button"
        value={contacts.done ? '모든 연락처를 가져왔어요.' : '다음 연락처 가져오기'}
        disabled={contacts.done}
        onClick={handlePress}
      />
      <input
        type="button"
        value="권한 확인하기"
        onClick={async () => {
          const permission = await fetchContacts.getPermission();
          alert(permission);
        }}
      />
      <input
        type="button"
        value="권한 요청하기"
        onClick={async () => {
          const permission = await fetchContacts.openPermissionDialog();
          alert(permission);
        }}
      />

  );
}

React Native

import { ContactEntity, fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

function ContactsList() {
  const [contacts, setContacts] = useState<{
    result: ContactEntity[];
    nextOffset: number | null;
    done: boolean;
  }>({
    result: [],
    nextOffset: null,
    done: false,
  });

  const handlePress = async () => {
    try {
      if (contacts.done) {
        console.log('모든 연락처를 가져왔어요.');
        return;
      }

      const response = await fetchContacts({
        size: 10,
        offset: contacts.nextOffset ?? 0,
        query: { contains: '김' },
      });
      setContacts((prev) => ({
        result: [...prev.result, ...response.result],
        nextOffset: response.nextOffset,
        done: response.done,
      }));
    } catch (error) {
      if (error instanceof FetchContactsPermissionError) {
        console.log('연락처 읽기 권한 없음');
      }
      console.error('연락처를 가져오는 데 실패했어요:', error);
    }
  };

  return (
    <View>
      {contacts.result.map((contact, index) => (
        <Text key={index}>
          {contact.name}: {contact.phoneNumber}
        </Text>
      ))}
      <Button
        title={contacts.done ? '모든 연락처를 가져왔어요.' : '다음 연락처 가져오기'}
        disabled={contacts.done}
        onPress={handlePress}
      />
      <Button
        title="권한 확인하기"
        onPress={async () => {
          const permission = await fetchContacts.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="권한 요청하기"
        onPress={async () => {
          const permission = await fetchContacts.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}