Promotion.openContactsInvite

Functional API contactsViralYou can use the same feature there as well. The functional API returns an empty cleanup function instead of throwing an error if the app version does not support it.

Feature description

Provides a feature that lets you share with friends and receive rewards. When the user completes sharing with a friend, reward information is delivered through an event.

Toss app 5.223.0 You can use it on version and above. Before calling, Promotion.openContactsInvite.isSupported()You can check support status with Promotion.grantReward.isSupported(). If you call it on an unsupported version, UNSUPPORTED_APP_VERSION an error occurs.

The returned cleanup function must be called after the sharing feature ends to release resources.

Type

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

Params

type ContactsViralOption = {
  /** A unique ID in UUID format that identifies a share reward. You can find it in the Mini App > Share Rewards menu in the Apps in Toss console. */
  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

Returns an app bridge cleanup function.

Error code

Error codes are onErrorcan be received as, or wrapped around the try/catcherrors caught in error.code value.

Code	Description
UNSUPPORTED_APP_VERSION	If the running version of the Toss app doesn't support this feature, it occurs immediately upon call. Promotion.openContactsInvite.isSupported()Check in advance with error.messageand, if it occurs, show the user the (update guidance message).

Example code

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(
            "Reward payout:",
            event.data.rewardAmount,
            event.data.rewardUnit,
          );
        } else if (event.type === "close") {
          console.log("Module closed:", event.data.closeReason);
          cleanup();
        }
      },
      onError: (error) => {
        console.error("Error occurred:", error);
        cleanup?.();
      },
    });
  } catch (error) {
    console.error("Error during execution:", error);
  }
}

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