11/08/2024 16:35:54

Email & Phone 渠道说明

一、产品介绍

邮箱&手机模块是MSDK自建账号能力，当前邮箱&手机合并为一个渠道，接入后支持使用邮箱/手机号注册并登陆游戏，并提供配套的重置密码、修改邮箱/手机号、添加邮箱/手机号等能力，同时也支持与其他社交渠道相互绑定。

功能介绍：

1. 注册：支持使用邮箱/手机号注册，注册时生成验证码并发送到注册的邮箱/手机上，用户输入验证码并设置登录密码后完成注册；
2. 登录：支持使用注册过的邮箱/手机号进行登录，提供2种登录方式：账号+密码登录、账号+验证码登录；
3. 重置密码：支持修改邮箱/手机的登录密码；
4. 添加邮箱/手机号：支持在已有的邮箱账号下添加未注册过的手机号、或在已有的手机账号下添加未注册过的邮箱，添加后可支持使用邮箱/手机任一方式登录，密码共用一套；
5. 渠道互绑：邮箱&手机作为一个独立渠道，支持与其他社交渠道（Facebook、twitter等）相互绑定，绑定后可支持用户选择任一渠道登录同一个账号。

二、接入流程

2.1 申请接入

需要联系 MSDK助手 邮件申请。

2.2 配置信息

MSDK回复邮件分配应用ID、应用密钥，业务在飞鹰管理端进行联调环境的登录渠道配置。

进入飞鹰系统，选择游戏管理-全部游戏，找到自己的游戏，进入游戏详情页-登录信息，联调环境勾选Email&Phone渠道，填入应用ID、应用密钥，点击发布至联调环境即可：

2.3 申请发送主体、邮箱/短信模板

根据上一步的邮件附件《邮箱和手机接入配置指引》，到腾讯云（短信）申请发送主体及对应模板，并于计划联调时间前1周回复邮件提供发送主体账号和模板信息，注意提供的时间需要早于联调时间，否则会影响联调！

2.4 接入联调：相关功能接口联调

2.5 上线前准备：业务配置检查

1. 业务侧限制规则对齐：包含短信、邮件发送间隔、密码错误次数限制、token有效期、验证码有效期等。

2. 填写正式环境登录渠道配置、容量预估信息:

   • 进入飞鹰系统，选择游戏管理-全部游戏，找到自己的游戏，进入游戏详情页-登录信息，正式环境选择发行区域、勾选Email&Phone渠道，填入应用ID、应用密钥（与联调环境一致）

   • 填写容量预估，点击发布正式环境，进入审核流程，审核通过后正式生效

2.6 发布上线

三、工程配置

Android: 在工程中找到 assets/MSDKConfig.ini 文件

iOS: 在工程中找到 MSDKAppSetting.bundle/MSDKConfig.ini 文件

MSDK_URL = https://hktest.itop.qq.com
[MSKD 自建账号配置]
# 游戏在上线时需要将 MSDK_ACCOUNT_URL 环境切换为正式服，此处环境需要与MSDK_URL对应，即同为联调服或正式服
MSDK_ACCOUNT_URL = https://cotest.msdkpass.com  
MSDK_ACCOUNT_SDK_KEY = {MSDK_ACCOUNT_SDK_KEY}
MSDK_ACCOUNT_APP_ID = {MSDK_ACCOUNT_APP_ID}
# 开启 MSDK 默认密码校验规则，默认开启，假如有自己的校验需求，请将其置零，在调用接口前自己先做密码校验
MSDK_ACCOUNT_PASSWORD_VALIDATION = 1

[info] MSDK_ACCOUNT_URL 可选如下URL值：

• 联调服: https://cotest.msdkpass.com
• 正式服: https://us.msdkpass.com

需要将 {MSDK_ACCOUNT_SDK_KEY} 替换为业务自己的 Account 模块的 SDK KEY

需要将 {MSDK_ACCOUNT_APP_ID} 替换为业务自己的 Account 模块的 APP ID

四、接口说明

4.1 回调

Login登录相关的回调：

Login登录的回调可以参考 MSDKLogin 登录模块 的注册回调部分

Account接口的回调：

public static event OnMSDKRetEventHandler<MSDKAccountRet> AccountEvent;

public void OnAccountEvent(MSDKAccountRet accountRet)
{
    Debug.Log("OnAccountNotify in Login");
    string methodTag = "";
    if (accountRet.MethodNameId == (int)MSDKMethodNameID.MSDK_ACCOUNT_VERIFY_CODE)
    {
        methodTag = "SendVerifyCode";
    }
    else if (accountRet.MethodNameId == (int)MSDKMethodNameID.MSDK_ACCOUNT_RESET_PASSWORD)
    {
        methodTag = "ResetPassword";
    }
    else if (accountRet.MethodNameId == (int) MSDKMethodNameID.MSDK_ACCOUNT_MODIFY)
    {
        methodTag = "Modify";
    }
    else if (accountRet.MethodNameId == (int) MSDKMethodNameID.MSDK_ACCOUNT_REGISTER_STATUS)
    {
        methodTag = "GetRegisterStatus";
    }
    mCurrentTestMgr.ShowLogInNewLine(methodTag + Tools.Instance.GetRetString(accountRet));
}

MSDKAccount.AccountEvent += mAccountCallBack.OnAccountEvent;

class MyAccountObserver : public MSDKAccountObserver {
public:
    void OnAccountNotify(const MSDKAccountRet &accountRet) {
        // 处理 accountRet 回调信息
    }
}
MSDKAccount::SetAccountObserver(new MyAccountObserver());

4.2 注册登录

接口：

MSDKLogin.Login(string channel, 
            string permissions = "", 
            string subChannel = "", 
            string extraJson = "")

void MSDKLogin::Login(const String &channel, 
            const String &permissions, 
            const String &subChannel, 
            const String &extraJson)

描述：

要使用自建账号的邮箱或手机号注册登录功能，可以通过调用 MSDKLogin.Login 接口，向 extraJson 中以 json 格式传入参数，具体参数说明如下：

channel     - 【必填】渠道名称，"Self" 为自建账号渠道
permissions - 权限，此处填空 ""
subChannel  - 子渠道，此处填空 ""
extraJson   - 扩展字段，注册登录功能参数示例如下：
    {
        "type": "register",            // 类型 - 使用注册功能
        "account": "150xxxxxx87",    // 账号
        "password": "123456678",    // 密码
        "verifyCode": 12323,        // 验证码
        "extraJson": "",            // 注册时使用的扩展字段，此处为空
        "accountType": 2,            // 账号类型，1-邮箱，2-手机号
        "langType": "zh_CN",        // 语言类型，指定发送消息的语言
        "areaCode": "86"            // 区号，如果输入的手机号，区号为必填，若输入的是邮箱，则区号可不填
                                    // 对于手机区号 areaCode 字段，业务在做 UI 页面设计的时候，建议让用户做选择，而不是手动输入
    }

4.3 账密登录

接口：

MSDKLogin.Login(string channel, 
            string permissions = "", 
            string subChannel = "", 
            string extraJson = "")

void MSDKLogin::Login(const String &channel, 
            const String &permissions, 
            const String &subChannel, 
            const String &extraJson)

描述：

要使用邮箱或手机号账密登录功能，可以通过调用 MSDKLogin.Login 接口，向 extraJson 中以 json 格式传入参数，具体参数说明如下：

channel     - 【必填】渠道名称，"Self" 为自建账号渠道
permissions - 权限，此处填空 ""
subChannel  - 子渠道，此处填空 ""
extraJson   - 扩展字段，注册登录功能参数示例如下：
    {
        "type": "login",            // 类型 - 使用账密登录功能            
        "account": "150xxxxxx87",    // 账号
        "password": "msdk2020",        // 密码
        "accountType": 2,            // 账号类型，1-邮箱，2-手机号
        "langType": "zh_CN",        // 语言类型，用于指定发送消息的语言
        "areaCode":"852"               // 手机区号，账号为手机类型时必填
                                    // 对于手机区号 areaCode 字段，业务在做 UI 页面设计的时候，建议让用户做选择，而不是手动输入
    }

4.4 验证码登录

接口：

MSDKLogin.Login(string channel, 
            string permissions = "", 
            string subChannel = "", 
            string extraJson = "")

void MSDKLogin::Login(const String &channel, 
            const String &permissions, 
            const String &subChannel, 
            const String &extraJson)

描述：

要使用邮箱或手机号验证码登录功能，需要先通过发送验证码接口获取验证码，再通过调用 MSDKLogin.Login 接口，向 extraJson 中以 json 格式传入参数，具体参数说明如下：

channel     - 【必填】渠道名称，"Self" 为自建账号渠道
permissions - 权限，此处填空 ""
subChannel  - 子渠道，此处填空 ""
extraJson   - 扩展字段，验证码登录功能参数示例如下：
    {
        "type": "loginWithCode",    // 类型 - 使用账密登录功能
        "account": "150xxxxxx87",    // 账号
        "verifyCode": 25496,        // 验证码
        "accountType": 2,            // 账号类型，1-邮箱，2-手机号
        "langType": "zh_CN",        // 语言类型，用于指定发送消息的语言
        "areaCode":"852"               // 手机区号，账号为手机类型时必填
                                    // 对于手机区号 areaCode 字段，业务在做 UI 页面设计的时候，建议让用户做选择，而不是手动输入
    }

4.5 发送验证码

接口：

MSDKAccount.RequestVerifyCode(string channel, 
            string account, 
            int codeType, 
            int accountType,
            string langType, 
            string areaCode = "86", 
            string extraJson = "")

MSDKAccount::RequestVerifyCode(const String& channel, 
            const String& account, 
            int codeType, 
            int accountType, 
            const String& langType, 
            const String& areaCode = "86", 
            const String& extraJson = "");

描述：

要使用向邮箱或手机号发送验证码的功能，需要调用此接口，传入指定参数，例如要获取验证码用于登录，那么 codeType 需要传入 2，具体参数说明如下：

/**
 * 发送校验码接口
 * @param channel           【必填】渠道名称，"Self" 为自建账号渠道
 * @param account           【必填】注册的账号
 * @param codeType          【必填】生成的验证码类型，0-注册,1-修改密码,2-验证码登录,3-修改账号信息
 * @param accountType       【必填】账号类型，1-邮箱，2-手机号
 * @param areaCode          【选填】手机区号，账号为手机类型时必填，邮箱渠道可直接填""，对于手机区号 areaCode 字段，业务在做 UI 页面设计的时候，建议让用户做选择，而不是手动输入
 * @param langType          【必填】指定发送给用户的验证码短信或邮件所用语言
 * @param extraJson         【选填】扩展字段，默认为空，会透传到后台
 */

4.6 修改密码

接口：

MSDKAccount.ResetPassword(string channel, 
            int verifyType, 
            string account, 
            string password, 
            string oldPassword, 
            int accountType, 
            int verifyCode, 
            string langType, 
            string areaCode = "86", 
            string extraJson = "");

MSDKAccount::ResetPassword(const String& channel,
            int verifyType,
            const String& account,
            const String& password,
            const String& oldPassword,
            int accountType,
            int verifyCode,
            const String& langType,
            const String& areaCode,
            const String& extraJson);

描述：

• 支持通过验证码形式修改密码，verifyType 传 1

要使用修改密码功能，需要调用此接口，传入指定参数，调用前需要先通过发送验证码接口获取修改密码的验证码，具体参数详情如下：

/**
 * 修改密码接口
 * @param channel           【必填】"Self"-自建账号
 * @param verifyType        【必填】验证方式，1：使用验证码
 * @param account           【必填】注册的账号
 * @param password          【必填】登录密码
 * @param accountType       【必填】支持"1- Email"，"2 - SMS"
 * @param verifyCode        【选填】验证码
 * @param areaCode          【选填】手机渠道时为国际区号，邮箱渠道可直接填""，对于手机区号 areaCode 字段，业务在做 UI 页面设计的时候，建议让用户做选择，而不是手动输入
 * @param extraJson         【选填】扩展字段，默认为空，会透传到后台
 */

4.7 查询用户注册状态

接口：

MSDKAccount.GetRegisterStatus(string channel, 
            string account, 
            int accountType, 
            string langType, 
            string areaCode, 
            string extraJson)

MSDKAccount::GetRegisterStatus(const String &channel, 
            const String &account, 
            int accountType, 
            const String &langType, 
            const String &areaCode, 
            const String &extraJson)

描述：

要使用查询用户注册状态功能，需要传入如下参数：

/**
 * 用户账号是否注册查询接口
 * @param channel           【必填】渠道名称，"Self" 为自建账号渠道
 * @param account           【必填】注册的账号
 * @param accountType       【必填】账号类型，1-邮箱，2-手机号
 * @param langType          【必填】指定发送给用户的验证码短信或邮件所有语言
 * @param areaCode          【选填】手机区号，账号为手机类型时必填，邮箱渠道可直接填""，对于手机区号 areaCode 字段，业务在做 UI 页面设计的时候，建议让用户做选择，而不是手动输入
 * @param extraJson         【选填】扩展字段，默认为空，会透传到后台
 */

在返回的回调中可获取如下值：

isRegister        // 表明该账号是否已注册，1 - 已注册， 0 - 未注册
isSetPassword   // 表明该账号是否已设置密码，1 - 已设置，0 - 未设置

4.8 修改账号信息

接口：

MSDKAccount.Modify(string channel, 
            int verifyType, 
            string account, 
            int accountType, 
            int verifyCode, 
            int verifyCodeModify, 
            string password, 
            string accountModify, 
            int accountTypeModify, 
            string areaCodeModify, 
            string langType, 
            string areaCode, 
            string extraJson);

MSDKAccount::Modify(const String &channel,
            int verifyType,
            const String &account,
            int accountType,
            int verifyCode,
            int verifyCodeModify,
            const String &password,
            const String &accountModify,
            int accountTypeModify,
            const String &areaCodeModify,
            const String &langType,
            const String &areaCode,
            const String &extraJson);

描述：

• 支持通过验证码形式修改账号信息，verifyType 传 1

调用此接口使用修改账号信息的功能，需要传入如下参数：

/**
 * 修改账号信息接口
 * @param channel           【必填】支持"Passport"-统一账号，"EGame"-企鹅电竞, "Self"-自建账号三个渠道
 * @param verifyType        【必填】验证方式，1：使用验证码
 * @param account           【必填】注册的账号
 * @param accountType       【必填】支持"1- Email"，"2 - SMS"
 * @param verifyCode        【必填】验证码, 修改账号验证码（code_type=3）
 * @param verifyCodeModify  【必填】被修改账号的验证码，修改账号验证码（code_type=3）
 * @param accountModify     【必填】要修改的账号
 * @param accountTypeModify 【必填】要修改的账号类似1email,2phone
 * @param areaCodeModify    【选填】 要修改的账号是手机时为必填参数， 这里填写的是手机区号字段，对于手机区号 areaCode 字段，业务在做 UI 页面设计的时候，建议让用户做选择，而不是手动输入
 * @param areaCode          【选填】 手机登录时为必填参数， 这里填写的是手机区号字段，对于手机区号 areaCode 字段，业务在做 UI 页面设计的时候，建议让用户做选择，而不是手动输入
 * @param extraJson         【选填】扩展字段，默认为空，会透传到后台
 */

4.9 查询验证码有效期

接口：

MSDKAccount.GetVerifyCodeStatus(string channel, 
            string account, 
            int accountType, 
            int verifyCode, 
            int codeType, 
            string langType, 
            string areaCode, 
            string extraJson)

MSDKAccount::GetVerifyCodeStatus(const String& channel, 
            const String& account, 
            int accountType, 
            int verifyCode, 
            int codeType, 
            const String& langType, 
            const String& areaCode, 
            const String& extraJson)

描述：调用此接口来查询验证码的有效期，需要传入如下参数：

/**
 * 验证码有效期查询接口
 * @param channel           【必填】渠道名称，"Self" 为自建账号渠道
 * @param account           【必填】注册的账号
 * @param accountType       【必填】账号类型，1-邮箱，2-手机号
 * @param verifyCode        【必填】验证码
 * @param codeType          【必填】生成的验证码类型，0注册,1修改密码,2登录并注册,3修改主体注册账号
 * @param langType          【必填】指定发送给用户的验证码短信或邮件所有语言
 * @param areaCode          【选填】手机登录时为必填参数， 这里填写的是手机区号字段，对于手机区号 areaCode 字段，业务在做 UI 页面设计的时候，建议让用户做选择，而不是手动输入
 * @param extraJson         【选填】扩展字段，默认为空，会透传到后台
 */

在返回的回调中可获取如下值：

verifyCodeExpireTime                    // 表明该验证码的有效期，单位为 s（秒）

五、语言 langType 列表

六、常见问题

1、Q：手机号登录时，输入验证码后提示“incorrect code”

A：检查发送验证码时选择的区号和登录时选择的是否一致，如果不一致，相当于登录的是另一个账号，验证码无法匹配