공유 리워드

contactsViral

지원환경: React NativeReact Native SDKv1.0.3WebViewWebView SDKv1.0.3

실행환경: Toss AppSandbox App

contactsViral 함수는 친구에게 공유하고 리워드를 받을 수 있는 기능을 제공해요. 사용자가 친구에게 공유를 완료하면, 앱 브릿지를 통해 이벤트가 전달되고, 해당 이벤트를 기반으로 리워드 정보를 받을 수 있어요.

주의하세요

• 본 기능은 토스앱 5.223.0 버전부터 지원해요. 하위 버전에서는 undefined가 반환됩니다.
• 기능 사용을 위해서는 미니앱 승인이 반드시 필요합니다. 미승인 상태에서는 Internal Server Error가 발생합니다.

참고하세요

• 테스트 환경(샌드박스 앱)에서는 빈 화면으로 보여요. 리워드 지급 버튼을 눌러도 실제로 동작하지 않아요.
• 콘솔 내 QR코드로 테스트를 진행해 주세요.
• 콘솔에 등록된 리워드 ID를 활용하여 테스트를 할 수 있어요.
• 친구 목록은 상호 연락처 저장 여부 외에도 다음 조건에 따라 달라질 수 있어요
  • 마케팅 수신 동의 여부
  • 야간 마케팅 수신 동의 여부
  • 푸시 토큰 등록 여부
  • 연락처 알림 차단 여부

시그니처

function contactsViral(params: ContactsViralParams): () => void;

파라미터

• params필수
  

  연락처 공유 기능을 실행할 때 사용하는 파라미터예요. 옵션 설정과 이벤트 핸들러를 포함해요.
  자세한 내용은 ContactsViralParams 문서를 참고하세요.

반환값

• () => void
  

  앱브릿지 cleanup 함수를 반환해요. 공유 기능이 끝나면 반드시 이 함수를 호출해서 리소스를 해제해야 해요.

예제

js

import { contactsViral } from '@apps-in-toss/web-framework';

function handleContactsViral(moduleId) {
  const cleanup = contactsViral({
    options: { moduleId: moduleId.trim() },
    onEvent: (event) => {
      if (event.type === 'sendViral') {
        console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
      } else if (event.type === 'close') {
        console.log('모듈 종료:', event.data.closeReason);
        cleanup();
      }
    },
    onError: (error) => {
      console.error('에러 발생:', error);
      cleanup?.();
    },
  });
}

React

import { contactsViral } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';
import { useCallback } from 'react';

function ContactsViralButton({ moduleId }: { moduleId: string }) {
  const handleContactsViral = useCallback(() => {
    try {
      const cleanup = contactsViral({
        options: { moduleId: moduleId.trim() },
        onEvent: (event) => {
          if (event.type === 'sendViral') {
            console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
          } else if (event.type === 'close') {
            console.log('모듈 종료:', event.data.closeReason);
            cleanup();
          }
        },
        onError: (error) => {
          console.error('에러 발생:', error);
          cleanup?.();
        },
      });
    } catch (error) {
      console.error('실행 중 에러:', error);
    }
  }, [moduleId]);

  return <Button onClick={handleContactsViral}>친구에게 공유하고 리워드 받기</Button>;
}

React Native

import { contactsViral } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';
import { useCallback } from 'react';

function ContactsViralButton({ moduleId }: { moduleId: string }) {
  const handleContactsViral = useCallback(() => {
    try {
      const cleanup = contactsViral({
        options: { moduleId: moduleId.trim() },
        onEvent: (event) => {
          if (event.type === 'sendViral') {
            console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
          } else if (event.type === 'close') {
            console.log('모듈 종료:', event.data.closeReason);
            cleanup();
          }
        },
        onError: (error) => {
          console.error('에러 발생:', error);
          cleanup?.();
        },
      });
    } catch (error) {
      console.error('실행 중 에러:', error);
    }
  }, [moduleId]);

  return <Button onPress={handleContactsViral}>친구에게 공유하고 리워드 받기</Button>;
}

예제 앱 체험하기

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

ContactsViralOption

ContactsViralOption는 연락처 공유 기능을 사용할 때 필요한 옵션이에요.

시그니처

type ContactsViralOption = {
  moduleId: string;
};

프로퍼티

• moduleId필수
  

  공유 리워드를 구분하는 UUID 형식의 고유 ID예요.
  앱인토스 콘솔의 미니앱 > 공유 리워드 메뉴에서 확인할 수 있어요.

ContactsViralParams

ContactsViralParams 는 contactsViral 함수를 실행할 때 사용하는 파라미터 타입이에요. 옵션을 설정하고, 이벤트 및 에러 처리 콜백을 지정할 수 있어요.

시그니처

interface ContactsViralParams {
  options: ContactsViralOption;
  onEvent: (event: ContactsViralEvent) => void;
  onError: (error: unknown) => void;
}

프로퍼티

• options필수
  

  공유 기능에 사용할 옵션 객체예요.
  자세한 타입은 ContactsViralOption 문서를 참고하세요.

• onEvent필수
  

  공유 이벤트가 발생했을 때 실행되는 함수예요.
  RewardFromContactsViralEvent 또는 ContactsViralSuccessEvent 타입의 이벤트 객체가 전달돼요.

• onError필수
  

  예기치 않은 에러가 발생했을 때 실행되는 함수예요. 에러 객체는 타입이 unknown이에요.

ContactsViralSuccessEvent

ContactsViralSuccessEvent 는 연락처 공유 모듈이 정상적으로 종료됐을 때 전달되는 이벤트 객체예요. 종료 이유와 함께 리워드 상태 및 남은 친구 수 등 관련 정보를 제공해요.

시그니처

type ContactsViralSuccessEvent = {
  type: 'close';
  data: {
    closeReason: 'clickBackButton' | 'noReward';
    sentRewardAmount?: number;
    sendableRewardsCount?: number;
    sentRewardsCount: number;
    rewardUnit?: string;
  };
};

프로퍼티

• type필수
  

  이벤트의 타입이에요. 공유 모듈이 종료되었을 때 close 값을 갖고 돌아와요.

• data필수
  

  모듈 종료와 관련된 세부 정보를 담고 있어요.

  • data.closeReason필수
    

    모듈이 종료된 이유예요.
    clickBackButton: 사용자가 뒤로 가기 버튼을 눌러 종료한 경우
    noReward: 받을 수 있는 리워드가 없어서 종료된 경우

  • data.sentRewardAmount
    

    사용자가 받은 전체 리워드 수량이에요. 선택적으로 전달돼요.

  • data.sendableRewardsCount
    

    아직 공유할 수 있는 친구 수예요. 선택적으로 전달돼요.

  • data.sentRewardsCount필수
    

    사용자가 공유를 완료한 친구 수예요.

  • data.rewardUnit
    

    리워드의 단위예요. 앱인토스 콘솔에 설정된 하트, 보석 같은 이름이 들어가요. 선택적으로 전달돼요.

예제

모듈 종료 이벤트 처리하기

contactsViral({
  options: { moduleId: 'your-module-id' },
  onEvent: (event) => {
    if (event.type === 'close') {
      console.log('종료 사유:', event.data.closeReason);
      console.log('공유 완료한 친구 수:', event.data.sentRewardsCount);
    }
  },
  onError: (error) => {
    console.error('에러 발생:', error);
  },
});

RewardFromContactsViralEvent

RewardFromContactsViralEvent 는 친구에게 공유하기를 완료했을 때 지급할 리워드 정보를 담는 타입이에요. 이 타입을 사용하면 공유가 완료됐을 때 지급할 리워드 정보를 확인할 수 있어요.

시그니처

type RewardFromContactsViralEvent = {
  type: 'sendViral';
  data: {
    rewardAmount: number;
    rewardUnit: string;
  };
};

프로퍼티

• type필수
  

  이벤트의 타입이에요. 친구에게 공유를 완료했을 때 'sendViral' 값을 갖고 돌아와요.

• data필수
  

  지급할 리워드 관련 정보를 담고 있어요.

  • data.rewardAmount필수
    

    지급할 리워드 수량이에요. 앱인토스 콘솔에서 설정한 수량 및 금액 값이에요.

  • data.rewardUnit필수
    

    리워드의 단위예요. 앱인토스 콘솔에 설정된 리워드 이름인 '하트', '보석' 등이 들어가요.

예제

공유 완료 후 리워드 정보 처리하기

contactsViral({
  options: { moduleId: 'your-module-id' },
  onEvent: (event) => {
    if (event.type === 'sendViral') {
      console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
    }
  },
  onError: (error) => {
    console.error('에러 발생:', error);
  },
});