MOGS API 文档

# 邀请系统

# 普通邀请

# 一、介绍

为了增加玩家 分享游戏的积极性，接入该系统可以使玩家分享游戏后，在被邀请的玩家进入游戏后得到奖励。支持区分邀请新玩家或者老玩家进入游戏增加活跃度，支持同时配置多个活动。该系统需要填写配置表，参考配置

# 二、使用

代码中通过以下方式使用

// 导入模块
import { invitationSystem } from "@timi/mogs-sdk";
...
// 获取当前的邀请活动列表
const invitationRewardActivities = await invitationSystem.invitationRewardActivities;
...
// 监听邀请奖励状态的改变
invitationSystem.onInvitationRewardStatusChange((res) => {
  // TODO
});

// 监听邀请人数的改变，该接口表示有新玩家通过分享进入了游戏
invitationSystem.onInvitationCountUpdate((res) => {
  // TODO
});
...
// 该接口来获取邀请的所有玩家，可通过邀请时间来筛选出属于该活动邀请的
let playList = (await invitationSystem.getInvitedPlayers({})).invitedPlayers;
...
// 分享游戏时需要带上当前玩家的openId
shareButton.on("touchend", async () => {
  const userInfo = await accountSystem.account;
  mogs.shareAppMessage({
    title: "快来和我一起战斗吧",
    query: `inviterId=${userInfo.openId}`,
  });
});
// 判断下链接，是否是点击的邀请链接进入的，是的话绑定一下
const query = mogs.getLaunchOptionsSync().query;
if (query.inviterId) {
  invitationSystem.bindInviter({
    openId: query.inviterId,
    success() {
      mogs.showToast({
        icon: "none",
        title: `成功绑定邀请玩家`,
      });
    },
    fail() {
      mogs.showToast({
        icon: "none",
        title: `绑定邀请玩家错误`,
      });
    },
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

TIP

更多邀请模块的api请参考邀请模块

# 快速邀请（主动邀请）

# 概述

有时候可能需要在小游戏中直接绘制好友列表，并对其中某些好友发起快速邀请，邀请后无需对方回应即可得到邀请奖励。下图是快速邀请好友并阶段性得到奖励的示例。

此时，需要使用邀请模块的快速邀请能力。本模块在此部分提供的能力有：

  • 支持 1 个快速邀请活动同时开启，最多支持邀请 75 个好友
  • 获取同玩好友能力
  • 获取一定数量的未注册好友能力
  • 可识别好友是否在本次活动中被邀请过
  • 跟随配置智能清除上一阶段活动的邀请记录

本节将介绍如何使用邀请模块实现快速邀请功能。

# 注意事项

  1. 请先阅读文档 开放能力 - 关系链数据
  2. 如果您在 微信/QQ 平台下使用本模块，请确保用户的普通型托管数据至少还有 3个 key 的空间！如果空间不足会导致初始化失败，将不能正常使用 API！ （如果您在项目中从未使用 setUserCloudStorage API，请忽略此段）
  3. 如果您使用游戏引擎，请先阅读该引擎接入开放数据域文档

# 在开放数据域中

# 初始化快速邀请

在调用接下来的 API 前，必须调用 invitationSystem.intializeQuickInvitation 初始化快速邀请。此步骤必须实现！ 示例代码如下。

// 导入模块
import { invitationSystem } from "@timi/mogs-sdk-open";

// 假设 onStart 是一个生命周期方法
onStart() {
  invitationSystem.intializeQuickInvitation();
}
1
2
3
4
5
6
7

# 渲染

渲染同玩好友或未注册好友列表，附带在本阶段中被邀请过信息。示例代码如下。

// 导入模块
import mogs, { invitationSystem } from "@timi/mogs-sdk-open";

async drawFriendList() {
  // 获取好友列表
  const invitationInfo = await invitationSystem.getFriendQuickInvitationInfo({
    // 指定为同玩好友，若指定 invitationSystem.FriendType.PotentialFriend 则为未注册好友
    friendType: invitationSystem.FriendType.RegisteredFriend,
  });
  invitationInfo.forEach((info) => {
    // 假设有方法 renderPlayerInfo 用于渲染玩家信息
    renderPlayerInfo({
      openid: info.openid, // 用户 openid
      avatarUrl: info.avatarUrl,  // 用户头像地址
      nickname: info.nickname, // 用户昵称
    });

    // 假设有方法 renderInviteButton 用于渲染邀请按钮
    renderInviteButton({
      isInvited: info.isInvited // 玩家是否被邀请过
    });
  });
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 快速邀请好友

针对某个好友，对其发起快速邀请。示例代码如下。

const invitationInfo = await invitationSystem.getFriendQuickInvitationInfo({
  friendType: invitationSystem.FriendType.RegisteredFriend,
});
invitationInfo.forEach((info) => {
  //...

  renderInviteButton({
    isInvited: info.isInvited,
    // 邀请方法
    inviteFunc: () => invitationSystem.quickInviteFriend({
      openId: info.openid,
      title: "分享标题",
    }),
  });
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 监听活动改变

可调用 onActivityChange 注册一个监听活动改变的事件的方法。调用 offActivityChange 可取消注册某一方法或全部方法。此处 "活动改变" 是指以下情形：

  • 邀请活动开始了一个新的周目，原本邀请过的人可重新邀请
// 假设 onLoad 是一个生命周期方法
onLoad() {

  // 假设 reRenderList 是一个重新渲染好友列表的方法
  invitationSystem.onActivityChange(reRenderList);
}

// 假设 onDestroy 是一个生命周期方法
onDestroy() {
  // 取消在活动改变时，执行 reRenderList
  invitationSystem.offActivityChange(reRenderList);
}
1
2
3
4
5
6
7
8
9
10
11
12

# 在主域中

# 初始化快速邀请

主域调用 invitationSystem.intializeQuickInvitation 初始化快速邀请。此步骤必须实现，且必须要在开放数据域中的邀请模块调用 intializeQuickInvitation 后再执行。 示例代码如下。

import { invitationSystem } from "@timi/mogs-sdk";

// 假设 onStart 是一个生命周期方法
onStart() {
  invitationSystem.intializeQuickInvitation();
}
1
2
3
4
5
6

# 其他

快速邀请中的 获取奖励物品列表、玩家获取奖励物品 等逻辑，与普通邀请逻辑基本一致，除了有以下不同：

  • 不能 执行绑定邀请人相关逻辑，如调用函数 bindInviter
  • 不能 执行查看邀请人相关逻辑，如调用函数 getInvitedPlayers

← 奖励系统 →