Promotion.openContactsInvite

函数式 API contactsViral也能使用相同功能。函数式 API 在不受支持的应用版本中不会抛出错误，而是返回一个空的 cleanup 函数。

功能说明

提供可以分享给朋友并获得奖励的功能。用户完成向朋友分享后，会通过事件传递奖励信息。

Toss App 5.223.0 可在以上版本中使用。调用前 Promotion.openContactsInvite.isSupported()可通过它确认是否支持。若在不支持的版本中调用， UNSUPPORTED_APP_VERSION 会发生错误。

返回的 cleanup 函数在分享功能结束后必须调用，以释放资源。

类型

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

Params

type ContactsViralOption = {
  /** 用于区分分享奖励的 UUID 格式唯一 ID。可在 Apps in Toss 控制台的迷你应用 > 分享奖励菜单中查看。 */
  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	如果当前运行的 Toss App 版本不支持此功能，调用后会立即发生。 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"));