04/29/2024 11:54:53

公告模块

一、概述

公告模块是 MSDK 为游戏提供的信息通知系统。公告系统只提供数据，具体 UI 样式需要业务自己定制，通过 飞鹰系统 -> 左侧菜单 MSDK 接入->公告管理处配置下发文本、图片以及网址等信息。公告模块不是独立的渠道或功能，是在 MSDKCore 中包含的功能。
下图是简单的公告展示：

二、接入向导

2.1 设置监听回调

1）功能描述

MSDK 公告模块的回调，游戏需要注册回调函数进行处理。

2）接口声明

public static event OnMSDKRetEventHandler<MSDKNoticeRet>  NoticeRetEvent;

public static void SetNoticeObserver(MSDKNoticeObserver *noticeObserver)
class MSDKNoticeObserver
{
public:
// Notice的回调接口
    virtual void OnLoadNoticeData(const MSDKNoticeRet &noticeRet) {};
};

3）示例代码

MSDKNotice.NoticeRetEvent += OnNoticeRetEvent;

public void OnNoticeRetEvent(MSDKNoticeRet noticeRet)
{
	string methodTag = "";
	if (noticeRet.MethodNameId == (int)MSDKMethodNameID.MSDK_NOTICE_LOAD_DATA) {
		methodTag = "LoadNotice";
	}

	SampleInstance.showRetDialog(methodTag, noticeRet);
}

//销毁的时候需要移除监听
private void OnDestroy()
{
	MSDKNotice.NoticeRetEvent -= OnNoticeRetEvent;
}

MSDKNotice::SetNoticeObserver(new MyNoticeObserver());

class MyNoticeObserver : public MSDKNoticeObserver {
public:
    void OnLoadNoticeData(const MSDKNoticeRet &noticeRet) {
        UMSDKDemoBase::showNormalAlert(noticeRet);
    }
};

4）数据结构

MSDKNoticeRet 详解
继承自 MSDKBaseRet，包含基础的信息

MSDKNoticeInfo 详解
公告的结构体，包含各种公告信息

说明：MSDKNoticeRet 中的 extraJson 会返回入参的数值，包含：noticeGroup，language，region，partition 字段。 这些参数可以在多次拉取公告且其中某次公告内容为空时，用来区分出是哪一次的拉取为空。

MSDKNoticeTextInfo 公告文字信息详解

2.2 获取公告数据

1）功能描述

获取已经配置的公告信息。该接口返回请求id，回调中带回获取到的公告信息以及请求id等。

2）接口声明

public static string LoadNoticeData(string noticeGroup, string language, int region, string partition,string extra)；

public static std::string LoadNoticeData(const string &noticeGroup, const string &language, int region,
                               const string &partition, const string &extra)

3）入参说明

4）调用示例

string reqid = MSDKNotice.LoadNoticeData("1", "zh-CN", "1", "0" );

std::string reqid = MSDKNotice::LoadNoticeData("1", "zh-CN", "1", "0", "");

三、配置公告

[info] 公告管理端地址：http://dev.ied.com/ 在左侧菜单 MSDK接入->公告管理

3.1 配置管理端公告

[info] 发布的公告要注意是测试环境还是正式环境

管理端选择公告语种后，公告语种框内容显示“已选择，见公告内容tab栏”，选中的公告语种会在公告内容框顶部显示。

[info]
字段当地时区需正确设置，否则会影响公告的下发时间
对公告设置白名单，可以设置公告对指定用户的可见性
如果设置的是自定义参数，后台不会根据自定义参数进行过滤，而是在拉取公告的时候将其返回给游戏

自定义参数配置和拉取返回示例如下所示：

四、公告过滤字段规则

4.1 概述

公告过滤字段规则是由 MSDK 后台逻辑控制的，后台根据飞鹰配置公告透传过来的过滤字段进行过滤下发；客户端获取公告数据时，只能获取符合过滤规则的公告数据。业务自行选择是否要配置过滤字段。

使用此功能需满足相关合规要求，包括但不限于个性化推荐、自动化决策等。具体以业务侧接口法务评估结论为准。

4.2 过滤字段类型

1）固定过滤字段

固定过滤字段包括操作系统、渠道、openid、设备id、版本号、大区(Partition)，其中除大区(Partition)需要在获取公告数据时通过 partition 参数透传以外，其他固定过滤字段都是自动拼接到后台请求中，无需业务传参。

[info] 版本号获取说明
Android 读取的是 AndroidManifest.xml 中的 versionCode 和 versionName；ios 是 info.plist 中的 CFBundleVersionKey(即 versionCode) 和 CFBundleShortVersionString（即 versionName）

2）自定义(Extra)过滤字段

自定义(Extra)过滤字段最多支持 10 个，可以是数字或英文字符，由游戏自定义配置。配置了自定义(Extra)过滤字段的公告，客户端获取时必须在 extra 中以 json 格式传入，否则无法拉取对应公告。channel、os、version、partition、trade_mark、apn 为固定过滤字段名，自定义时不要使用，避免冲突。

[warning] 自定义(Extra)过滤字段特别说明
如果飞鹰配置了自定义(Extra)过滤字段
1、业务客户端获取时必须在 extra 中以 json 格式传入对应数据，会获取到符合自定义(Extra)过滤字段和其他所有未配置自定义(Extra)过滤字段的公告（若配置了其他过滤字段，则还需要满足其他过滤字段规则）。
2、业务客户端获取时，如果没有传 extra，那么只能获取到没有配置自定义(Extra)过滤字段的公告。

4.3 过滤规则示例

1）配置操作系统过滤

1、配置过滤字段-操作系统为 Android，公告配置界面如下图所示：

2、业务客户端获取公告数据时，无需透传操作系统参数，MSDK 会自行拼接，只有操作系统为Android，即 os=1时才能获取到对应公告。后台请求示例如下所示：

request url : https://hktest.itop.qq.com/v2/notice/get_notice?channelid=2&gameid=12&os=1&seq=11-a17cf5be-978a-4019-a4a8-855b694b3c14-1656575977-11&ts=1656575977&version=5.25.000&sig=6bbe6bb6e74f63aec2a80eaa46951fea with postBody : {"language":"zh-CN","device_info":{"uuid":"29700a7a-662f-4f1a-a2ea-d4e8ee404b5b","device_language":"zh","app_version":"4.1.4637(1)","screen_dpi":3.0,"resolution":"1080*2376","trade_mark":"vivo","manufacturer":"vivo","model":"V2001A","apn":"","ram_info":"7810994176","rom_info":"245090955264","cpu_info":"4800"},"region":1,"partition":"","last_time":0,"extra_info":{"versionCode":"1","versionName":"4.1.4637"},"token":"D3BFB3DB7634A3131DFFB8B700E6499C","openid":"16862533134614867973"} opt:3 reqSeq:10007, reqTime:0

2）配置 openid 过滤字段

1、配置过滤字段-openid，上传 TXT 文件，公告配置界面如下图所示：

2、业务客户端获取公告数据时，无需透传 openid 参数，但是需要有登录态 MSDK 才会把 openid 拼接上去，只有 openid 与飞鹰配置的 openid 匹配才能获取都对应公告。后台请求示例如下所示：

request url : https://hktest.itop.qq.com/v2/notice/get_notice?channelid=2&gameid=12&os=1&seq=11-a17cf5be-978a-4019-a4a8-855b694b3c14-1656576711-16&ts=1656576711&version=5.25.000&sig=4427ba35269bbe05c095a957827e47fa with postBody : {"language":"zh-CN","device_info":{"uuid":"29700a7a-662f-4f1a-a2ea-d4e8ee404b5b","device_language":"zh","app_version":"4.1.4637(1)","screen_dpi":3.0,"resolution":"1080*2376","trade_mark":"vivo","manufacturer":"vivo","model":"V2001A","apn":"","ram_info":"7810994176","rom_info":"245090955264","cpu_info":"4800"},"region":1,"partition":"","last_time":0,"extra_info":{"versionCode":"1","versionName":"4.1.4637"},"token":"D3BFB3DB7634A3131DFFB8B700E6499C","openid":"16862533134614867973"} opt:3 reqSeq:10013, reqTime:0

3）配置过滤字段-自定义(Extra)字段

1、配置过滤字段-自定义(Extra)字段为 myExtra1，公告配置界面如下图所示：

2、业务客户端获取公告数据时，必须在 extra 中以 json 格式传入 {"myExtra1":"myValue1"}，才能获取到对应公告。客户端传参示例如下所示：

3、后台请求示例如下所示：

request url : https://hktest.itop.qq.com/v2/notice/get_notice?channelid=2&gameid=12&os=1&seq=11-a17cf5be-978a-4019-a4a8-855b694b3c14-1656577012-17&ts=1656577012&version=5.25.000&sig=148747b4627ecec51fa74d7cdfa5714e with postBody : {"language":"zh-CN","device_info":{"uuid":"29700a7a-662f-4f1a-a2ea-d4e8ee404b5b","device_language":"zh","app_version":"4.1.4637(1)","screen_dpi":3.0,"resolution":"1080*2376","trade_mark":"vivo","manufacturer":"vivo","model":"V2001A","apn":"","ram_info":"7810994176","rom_info":"245090955264","cpu_info":"4800"},"region":1,"partition":"","last_time":0,"extra_info":{"versionCode":"1","versionName":"4.1.4637","myExtra1":"myValue1"},"token":"D3BFB3DB7634A3131DFFB8B700E6499C","openid":"16862533134614867973"} opt:3 reqSeq:10015, reqTime:0

4）配置多个过滤规则示例

配置多个过滤规则时，业务客户端获取公告数据需要满足所有过滤规则才可以拉取到对应公告，固定过滤字段和自定义(Extra)的过滤规则是一样的，可以混合使用。

1、同时配置过滤字段-操作系统+openid时，业务客户端获取时操作系统必须是 Android 且 openid 与飞鹰配置匹配才能获取到对应公告。飞鹰配置与后台请求如下所示：

request url : https://hktest.itop.qq.com/v2/notice/get_notice?channelid=2&gameid=12&os=1&seq=11-a17cf5be-978a-4019-a4a8-855b694b3c14-1656577012-17&ts=1656577012&version=5.25.000&sig=148747b4627ecec51fa74d7cdfa5714e with postBody : {"language":"zh-CN","device_info":{"uuid":"29700a7a-662f-4f1a-a2ea-d4e8ee404b5b","device_language":"zh","app_version":"4.1.4637(1)","screen_dpi":3.0,"resolution":"1080*2376","trade_mark":"vivo","manufacturer":"vivo","model":"V2001A","apn":"","ram_info":"7810994176","rom_info":"245090955264","cpu_info":"4800"},"region":1,"partition":"","last_time":0,"extra_info":{"versionCode":"1","versionName":"4.1.4637","myExtra1":"myValue1"},"token":"D3BFB3DB7634A3131DFFB8B700E6499C","openid":"16862533134614867973"} opt:3 reqSeq:10015, reqTime:0

2、同时配置两个过滤字段-自定义(Extra)时，飞鹰配置如下图所示：

业务客户端获取公告数据时，必须在 extra 中以 json 格式传入 {"myExtra1":"myValue1","myExtra2":"myValue2"}.客户端传参示例如下所示：

后台请求如下所示：

request url : https://hktest.itop.qq.com/v2/notice/get_notice?channelid=2&gameid=12&os=1&seq=11-a17cf5be-978a-4019-a4a8-855b694b3c14-1656577381-19&ts=1656577381&version=5.25.000&sig=891dd97aea92933cb3f2bed34e53af21 with postBody : {"language":"zh-CN","device_info":{"uuid":"29700a7a-662f-4f1a-a2ea-d4e8ee404b5b","device_language":"zh","app_version":"4.1.4637(1)","screen_dpi":3.0,"resolution":"1080*2376","trade_mark":"vivo","manufacturer":"vivo","model":"V2001A","apn":"","ram_info":"7810994176","rom_info":"245090955264","cpu_info":"4800"},"region":1,"partition":"","last_time":0,"extra_info":{"versionCode":"1","versionName":"4.1.4637","myExtra1":"myValue1","myExtra2":"myValue2"},"token":"D3BFB3DB7634A3131DFFB8B700E6499C","openid":"16862533134614867973"} opt:3 reqSeq:10017, reqTime:0

[warning] 特别说明：
业务客户端获取公告数据时， extra 中以 json 格式传入 {"myExtra1":"myValue1","myExtra2":"myValue2"}，可以获取到单独配置了 myExtra1 或 myExtra2的公告。固定过滤字段也适用该规则。

五、其他

5.1 部分地区简码（region）

5.2 部分语种简码（language）