简介

需求来源

是否是渠道必接：可选

通过实现 A邀请了B，B如果通过A的链接进入了游戏，注册后客户端可以收到回调，同时给A发奖的功能，实现邀请好友裂变的效果

功能简介

通过小游戏渠道提供的分享功能，在分享中附带邀请人A的游戏ID，被邀请人B进入游戏后通过获取启动项，可以拿到分享中的附带信息，再通过公司服务器通知邀请人A，实现邀请人A成功邀请新人加入游戏后获取奖励的功能

各种别称

好友邀请，好友裂变

对应功能截图

前置条件

框架版本：1.2.0框架以上

支持渠道：微小，抖小

其他要求：需要配置白名单（会跟账号系统使用同一个域名）

需要联系账号系统的服务器添加【事件系统】功能

接入

接入流程

基础功能

更新公共库到需求版本
在启动账号系统的同时，给事件服务器设置地址

XYX.SetServerEventURL

邀请人A相关功能

参考竞品制作UI

点击邀请好友按钮后调用带邀请功能的分享接口

        void btn_Invite_Click()
        {
            LogUI.Log("带邀请功能的分享");//昵称可不传
            XYX.ShareAppFirendInvite(new XYX.ShareAppFirendInviteParams(){
                    userNickName = "test_nick"
                });
        }

userNickName 可不管，在后面的分享带昵称中会说明

主动刷新调用拉取玩家邀请好友成功事件

javascript

        void btn_pop_Click()
        {
            LogUI.Log("开始拉取邀请成功消息");
            XYX.PopFirendInviteSuccessMsg((code, data) =>
            {
                switch (code)
                {
                    case ServerEventAPI.PopCallbackCode.Success:
                    LogUI.Log("拉取邀请成功了");
                        var str = "";
                        if (data != null)
                            for (int i = 0; i < data.Length; i++)
                            {
                                str += data[i] + Environment.NewLine;
                            }
                            //这里data数据是被邀请人推送的customData
                        LogUI.Log("Data数据：" + str);
                        break;
                    case ServerEventAPI.PopCallbackCode.Fail:
                        LogUI.Log("拉取邀请成功消息失败：" + code);
                        break;
                    case ServerEventAPI.PopCallbackCode.IntervalTooShort:
                        LogUI.Log("拉取邀请成功消息失败：" + code + "，间隔时间太短");
                        break;
                    default:
                        break;
                }
            });
        }

服务器在拉取到数据后会把当前服务器的数据清空，每个数据只会拉取到一次，发放奖励后本地要保存一次存档
XYX.PopFirendInviteSuccessMsg 内置了 60 秒的 CD ，间隔太短会直接返回 PopCallbackCode.IntervalTooShort。需要避免频繁拉取信息，增大服务器压力
回调中的 data 参数为 string[]，内容为被邀请人B发送的数据，由研发自行配置。如果没有额外需求，直接使用 data.length 的数量发放奖励即可
拉取后服务器的数据会清空，所以每次拉到的数据都是上次拉取后新增的拉取成功信息

被邀请人B相关功能

进入游戏后判断是否是新玩家

在接入账号系统的脚本中的 LoginSuccess 中，添加对 useInfo.IsNewPlayer 的判断

确认是新玩家后，确认是不是是通过被邀请分享进入游戏

sql

            LogUI.Log("开始尝试获取是否被邀请");
            if (XYX.TryGetInviterNickName(out string inviterNickName))
            {
                LogUI.Log("是被邀请状态,邀请人：" + inviterNickName);
            }
            else
            {
                LogUI.Log("没有被邀请");
            }

inviterNickName，跟邀请人A调用 XYX.ShareAppFirendInvite 时传入的 userNickName 对应。即便 userNickName 为空，也可以获取到是被邀请状态

确认是新玩家并且是被带邀请功能的分享进入游戏时，通知邀请人A邀请成功

            LogUI.Log("开始推送邀请成功消息");
            XYX.PushInviteSuccessMsg(customData: NickNameKey + "=" + nickName, expiredAt: 0, callback: (data) =>
            {
                LogUI.Log("推送邀请成功消息结果：" + data.code + "," + data.msg);
            });

如果是不需要额外功能的情况 customData 可以直接传空
expiredAt 是消息失效时间，不填默认是 7 天

分享中带昵称

先获取邀请人A微小用户信息

需要制作对应的UI，提供一个给玩家点击的按钮才能获取用户数据

javascript

XYX.BindFunctionButton_UserInfo(btn_userInfo, (nick, url) =>
            {
                nickName = nick;
                UserNameText.text = nick;
                UserNameText.gameObject.SetActive(true);
                Log("用户信息：" + nick);
            }, (x) =>
            {
                Log("用户信息失败：" + x);
            });

邀请人A调用 XYX.ShareAppFirendInvite 时把用户昵称传入 userNickName
被邀请人B进入游戏后，通过 XYX.TryGetInviterNickName 获取到邀请人A的昵称
给被邀请人B制作UI，此时可以显示邀请人A的昵称，并提供获取微信信息的按钮
获取到被邀请人B的昵称后，调用 XYX.PushInviteSuccessMsg 接口，并把 appendData 参数设置为被邀请人B昵称

appendData 可以配置为研发需要的自定义数据，但是限制长度为 128

邀请人A在点击邀请好友界面的刷新按钮时，调用 XYX.PopFirendInviteSuccessMsg 接口，通过解析回调参数中的 data，可以获取到被邀请人B的昵称

显示分享好友的头像

暂不支持，需要使用到开放数据域，功能实现比较复杂

API

XYX.SetServerEventURL

    /// <summary>
    /// 设置事件服务URL
    /// </summary>
    /// <param name="url">事件服务URL,跟账号系统同一个地址</param>
    public static void SetServerEventURL(string url)

设置事件服务器地址，如果没设置地址就调用其他接口会抛出异常

代码示例

XYX.ShareAppFirendInvite

    /// <summary>
    /// 带好友邀请功能的分享
    /// </summary>
    /// <param name="title">分享的标题</param>
    /// <param name="content">分享的内容（该条在微小无效）</param>
    /// <param name="imgFile">分享的图片</param>
    /// <param name="userNickName">邀请人的昵称</param>
    /// <param name="args">自定义参数，通过该分享进入的用户，可以使用 XYX.GetLaunchOption获取</param>
public static void ShareAppFirendInvite(string title, string content, string imgFile, string userNickName, params string[] args)

带邀请功能的分享

title 微信分享的标题，不填使用默认配置
content 微小渠道无效，保留是为了适配框架的分享接口，方便后续扩展到其他渠道
imgFile 分享显示的图片，不填使用默认配置
args 自定义参数，会包含在分享中，点击分享进入游戏的用户，可以通过 XYX.GetLaunchOption 获取到

XYX.PopFirendInviteSuccessMsg

    /// <summary>
    /// 邀请人拉取自身的邀请成功事件，有 60 秒的内置间隔，避免业务反复拉取
    /// </summary>
    /// <param name="receiveUid"></param>
    /// <param name="callback"></param>
public static void PopFirendInviteSuccessMsg(XYXCommon.ServerEvent.ServerEventAPI.PopCallback callback)
......
public delegate void PopCallback(PopCallbackCode code, string[] data);
......
        public enum PopCallbackCode
        {
            Success = 0,
            Fail = 1,
            IntervalTooShort = 2,
        }

拉取服务器中关于拉取好友成功数据的接口

code 表明本次请求结果的状态。接口内置 60 秒 cd，如果cd没到就调用 code 会为 IntervalTooShort ，并且 data 为空
data 邀请好友成功的数据，数组中的一条对应一个邀请成功的对象。字符串具体的值取决于 XYX.PushInviteSuccessMsg 传入的参数。每次拉取后，服务器会清空数据，data 对应的是上次拉取到本次拉取直接的时间内，邀请好友成功的数据，不是所有拉取成功的数据

XYX.TryGetInviterNickName

       /// <summary>
    /// 获取是否被邀请
    /// </summary>
    /// <param name="inviterNickName">邀请人的昵称,可能为空</param>
    /// <returns>返回是否被邀请，有邀请返回 true，没有邀请返回 false</returns>
    public static bool TryGetInviterNickName(out string inviterNickName)

获取当前邀请人A的昵称

返回值对应当前是否是通过带邀请功能的分享进入游戏的
inviterNickName 对应邀请人A的昵称，需要在邀请人A调用 XYX.ShareAppFirendInvite 是传入昵称参数才能获取到。inviterNickName 是否为空不影响返回值

XYX.PushInviteSuccessMsg

        /// <summary>
    /// 发送好友邀请成功消息
    /// </summary>
    /// <param name="customData">业务自定义数据，长度限制 128 字节</param>
    /// <param name="expiredAt">过期时间，单位秒，0表示服务器默认的 7 天</param>
    /// <param name="callback">回调</param>
    public static void PushInviteSuccessMsg(string appendData, int expiredAt = 0, Action<XYXCommon.ServerEvent.ServerEventPushBackMsg> callback = null)
    ......
    public class ServerEventPushBackMsg
    {
        public string msg;
        public int code;
    }

被邀请人B给邀请人A推送邀请成功消息，如果当前不是通过带邀请功能的分享进入游戏时，调用该接口会直接返回失败

appendData 研发自定义数据，传入后，在邀请人A调用 XYX.PopFirendInviteSuccessMsg 时，可以通过 data 获取。限制长度为 128，如果超过会自动截短
expiredAt 失效时间，不填默认7天失效
callback 推送消息完成回调
- code为-2时，同一个用户不能重复推送邀请成功消息
- code为-1时，邀请人昵称获取失败
- code为0时，推送数据成功
- 其他值为服务器返回，具体情况取决于 msg 参数

自测

确认域名白名单是否正确添加
确认分享附带数据是否正确

日志搜索 "ShareAppMessageOption: " 确认邀请功能相关参数是否正常

inviter_nick_name=&inviter_user_id=ojlX063CBYVBivOHtttnycNTXRUY

确认拉取邀请成功信息接口调用是否正常

后续功能需要联系测试，分别测试新用户和老用户从带邀请功能的分享进入游戏，会不会给邀请人A推送邀请成功事件

常见问题

可能遇到的问题/QA文档

简介 ​

需求来源 ​

功能简介 ​

各种别称 ​

对应功能截图 ​

前置条件 ​

接入 ​

接入流程 ​

基础功能 ​

邀请人A相关功能 ​

被邀请人B相关功能 ​

分享中带昵称 ​

显示分享好友的头像 ​

API ​

XYX.SetServerEventURL ​

XYX.ShareAppFirendInvite ​

XYX.PopFirendInviteSuccessMsg ​

XYX.TryGetInviterNickName ​

XYX.PushInviteSuccessMsg ​

自测 ​

常见问题 ​

简介