Promotion.openContactsInvite

함수형 API contactsViral로도 같은 기능을 쓸 수 있어요. 함수형 API는 미지원 앱 버전이면 에러를 던지지 않고 빈 cleanup 함수를 반환해요.

기능 설명

친구에게 공유하고 리워드를 받을 수 있는 기능을 제공해요. 사용자가 친구에게 공유를 완료하면 이벤트를 통해 리워드 정보가 전달돼요.

토스앱 5.223.0 이상에서 사용할 수 있어요. 호출 전에 Promotion.openContactsInvite.isSupported()로 지원 여부를 확인할 수 있어요. 지원하지 않는 버전에서 호출하면 UNSUPPORTED_APP_VERSION 에러가 발생해요.

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

타입

Promotion.openContactsInvite(params: ContactsViralParams): () => void;

Params

type ContactsViralOption = {
  /** 공유 리워드를 구분하는 UUID 형식의 고유 ID예요. 앱인토스 콘솔의 미니앱 > 공유 리워드 메뉴에서 확인할 수 있어요. */
  moduleId: string;
};

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

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

type ContactsViralEvent =
  RewardFromContactsViralEvent | ContactsViralSuccessEvent;

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

Response

앱 브릿지 cleanup 함수를 반환해요.

에러 코드

에러 코드는 onError로 받거나 호출을 감싼 try/catch에서 잡은 에러의 error.code 값이에요.

코드	설명
UNSUPPORTED_APP_VERSION	실행 중인 토스앱 버전이 이 기능을 지원하지 않으면 호출 즉시 발생해요. Promotion.openContactsInvite.isSupported()로 사전 확인하고, 발생 시 error.message(업데이트 안내 문구)를 사용자에게 보여주세요.

예시 코드

import { Promotion } from "@apps-in-toss/web-framework";

function handleOpenContactsInvite(moduleId) {
  try {
    const cleanup = Promotion.openContactsInvite({
      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);
  }
}

document
  .querySelector("#contacts-invite")
  .addEventListener("click", () => handleOpenContactsInvite("MODULE_ID"));