Appearance

연락처 가져오기 ​

지원환경: React NativeWebView
실행환경: Toss AppSandbox App

fetchContacts ​

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

시그니처 ​

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

시그니처 ​

typescript
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는 연락처 읽기 권한 요청을 한 번도 하지 않은 상태예요.

반환 값 ​

  • Promise<ContactResult>

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

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

FetchContactsPermissionError ​

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

시그니처 ​

typescript
class FetchContactsPermissionError extends PermissionError {
    constructor();
}

예제 ​

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

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

tsx
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.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);
        }}
      />
    </div>
  );
}
tsx
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.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>
  );
}

예제 앱 체험하기 ​

apps-in-toss-examples 저장소에서 with-contacts 코드를 내려받거나, 아래 QR 코드를 스캔해 직접 체험해 보세요.