알림 동의문 요청 (requestNotificationAgreement)

지원환경: React NativeReact Native SDKv2.5.0WebViewWebView SDKv2.5.0

실행환경: Toss AppSandbox App

requestNotificationAgreement는 사용자에게 알림 수신 동의 UI를 요청하는 함수예요.

재입고 알림, 이벤트 시작 알림처럼 특정 시점에 알림을 보내기 위해 사전 동의가 필요한 경우에 사용해요.
결제 완료, 배송 알림처럼 서비스 이용에 필수적인 메시지는 동의 없이도 발송할 수 있어요.

동의 결과는 onEvent 콜백으로 전달되며, 결과에 따라 알림 발송 여부를 결정할 수 있어요.

시그니처

function requestNotificationAgreement(params: RequestNotificationAgreementOptions): () => void;

파라미터

• params필수
  

  알림 동의 요청에 사용하는 파라미터예요. 자세한 타입은 RequestNotificationAgreementOptions를 참고하세요.

반환값

• () => void
  

  앱브릿지 cleanup 함수를 반환해요. 동의 결과를 받은 후에는 반드시 이 함수를 호출해서 리소스를 해제해야 해요.

예제

React

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

function NotificationAgreementButton() {
  const handleRequestAgreement = () => {
    const cleanup = requestNotificationAgreement({
      options: {
        templateCode: 'your-template-code',
      },
      onEvent: ({ type }) => {
        if (type === 'newAgreement') {
          console.log('알림 수신에 동의했어요.');
        } else if (type === 'alreadyAgreed') {
          console.log('이미 동의된 상태예요.');
        } else if (type === 'agreementRejected') {
          console.log('알림 수신을 거부했어요.');
        }
        cleanup();
      },
      onError: (error) => {
        console.error('알림 동의 요청에 실패했어요:', error);
        cleanup();
      },
    });
  };

  return <button onClick={handleRequestAgreement}>알림 받기</button>;
}

React Native

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

function NotificationAgreementButton() {
  const handleRequestAgreement = () => {
    const cleanup = requestNotificationAgreement({
      options: {
        templateCode: 'your-template-code',
      },
      onEvent: ({ type }) => {
        if (type === 'newAgreement') {
          console.log('알림 수신에 동의했어요.');
        } else if (type === 'alreadyAgreed') {
          console.log('이미 동의된 상태예요.');
        } else if (type === 'agreementRejected') {
          console.log('알림 수신을 거부했어요.');
        }
        cleanup();
      },
      onError: (error) => {
        console.error('알림 동의 요청에 실패했어요:', error);
        cleanup();
      },
    });
  };

  return <Button title="알림 받기" onPress={handleRequestAgreement} />;
}

RequestNotificationAgreementOptions

requestNotificationAgreement 함수에 전달하는 파라미터 타입이에요.

시그니처

interface RequestNotificationAgreementOptions {
  options: {
    templateCode: string;
  };
  onEvent: (result: { type: NotificationAgreementResult }) => void;
  onError: (error: unknown) => void | Promise<void>;
}

프로퍼티

• options필수
  

  알림 동의 요청에 사용할 옵션 객체예요.

  • options.templateCode필수
    

    알림 동의를 요청할 푸시 알림 템플릿 코드예요. 앱인토스 콘솔의 알림 메뉴에서 확인할 수 있어요.

• onEvent필수
  

  동의 결과가 확정됐을 때 실행되는 콜백이에요. NotificationAgreementResult 타입의 type 값이 전달돼요.

• onError필수
  

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

NotificationAgreementResult

onEvent 콜백으로 전달되는 동의 결과 타입이에요.

시그니처

type NotificationAgreementResult = 'newAgreement' | 'alreadyAgreed' | 'agreementRejected';

값 설명

값	설명
newAgreement	사용자가 새로 동의를 완료한 경우예요.
alreadyAgreed	이미 동의된 상태로, 추가 동의 없이 결과가 반환된 경우예요.
agreementRejected	사용자가 동의를 거부한 경우예요.

참고사항

• onEvent 또는 onError 콜백에서 반환된 cleanup 함수를 반드시 호출해 주세요.
• 동일 컴포넌트에서 함수를 재호출하기 전에 이전 cleanup을 먼저 실행해 주세요. 그렇지 않으면 이전 이벤트 리스너가 중복으로 남아 있을 수 있어요.