跳到主要内容
版本：v3

公告指南

提示

接入 TDS 公告服务 SDK 之前，请参考《功能介绍》文档完成服务开通、域名配置。

SDK 配置​

可以在 下载页 获得 TapSDK，引入公告模块。

Unity 模块是通过引入 iOS 和 Android 模块后增加桥接文件打包出的 .unitypackage，方便以 Unity 开发的游戏直接引入。其他引擎/平台的游戏可以通过 iOS/Android 原生的方式接入，详见 iOS/Android 接入文档。

Unity 开发环境要求：Unity 2019.4 或更高版本

支持版本：

  • Android：最低支持 5.0
  • iOS：最低支持 iOS 10.0
"dependencies":{
    "com.taptap.tds.billboard": "https://github.com/TapTap/TapBillboard-Unity.git#3.18.2",
    "com.taptap.tds.common": "https://github.com/TapTap/TapCommon-Unity.git#3.18.2",
}

初始化​

信息

以下两种初始化方式任选其一。

TapSDK 初始化​

如果你已经参考快速开始完成了初始化，这里只需要引入公告模块，然后添加下面初始化代码中高亮的部分到项目中即可。

注意：公告配置中 ServerUrl 必须为完整的包含 https:// 的链接地址，不能只设置域名。

using TapTap.Common;
using TapTap.Bootstrap;
using TapTap.Billboard;

var dimensionSet = new HashSet<KeyValuePair<string, string>>();
KeyValuePair<string, string> platformPair = new KeyValuePair<string, string>("platform", "TapTap");
KeyValuePair<string, string> locationPair = new KeyValuePair<string, string>("location", "CN");
dimensionSet.Add(platformPair);
dimensionSet.Add(locationPair);
var templateType = "navigate"; // 可选
var billboardServerUrl = "https://your-billboard-server-url"; // 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 > 域名配置 > 公告 ， 这里必须包含 https:// 

var config = new TapConfig.Builder()
    .ClientID("your_client_id") // 必须，开发者中心对应 Client ID
    .ClientToken("your_client_token") // 必须，开发者中心对应 Client Token
    .ServerURL("https://your_server_url") // 必须，开发者中心 > 你的游戏 > 游戏服务 > 基本信息 > 域名配置 > 云服务 API
    .RegionType(RegionType.CN) // 可选项，CN 表示中国大陆，IO 表示其他国家或地区
    .TapBillboardConfig(dimensionSet, templateType, billboardServerUrl)
    .ConfigBuilder();
TapBootstrap.Init(config);

公告系统单独初始化​

如果游戏不通过上面提供的 TapBootstrap 方法初始化 TapSDK，仅希望初始化公告系统，可以这么做：

  • 复制上面提供的第一种初始化方式代码。
  • 修改最后一行为：
TapBillboard.Init(config);

参数说明​

  • 初始化需要两个域名，分别是 API 域名和公告域名。参考文档关于域名的说明，在 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 > 域名配置 处完成配置之后填入。

  • dimensionSet 参考公告系统维度配置，这里使用了两个预设维度：渠道（platform）和地区（location）。

  • client_id、client_token、RegionType 信息可在 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 查看。

打开公告​

TapBillboard.OpenPanel((any, error) =>
{
    if (error != null)
    {
        // 打开公告失败，可以根据 error.code 和 error.errorDescription 来判断错误原因
    } else
    {
        // 打开公告成功
    }
}, () => {
        // 公告已关闭
});

打开开屏公告​

开屏公告用户无法主动关闭，当时间到达开发者配置的关闭时间时会自动关闭，或者开发者可调用关闭开屏公告接口主动关闭。

 TapBillboard.OpenSplashPanel(async (result, err) => {
            if (result) {
                Debug.Log("打开开屏公告成功");
             } else {
                Debug.Log($"打开开屏公告失败: {err.code}, {err.errorDescription}");
            }
        }, () => {
            Debug.Log("关闭开屏公告");
        });

关闭开屏公告​

当开屏公告展示时，开发者可调用该接口主动关闭。

TapBillboard.CloseSplashPanel();

获取小红点​

可以用来获取是否有新的公告信息。SDK 内部对小红点信息进行了缓存，如果两次请求间隔小于 5 分钟，会直接返回上一次成功结果。

TapBillboard.QueryBadgeDetails((badgeDetails, error) =>
{
    if (error != null)
    {
        // 获取小红点信息失败，可以根据 error.code 和 error.errorDescription 来判断错误原因
    }
    else
    {
        // 获取小红点信息成功
        if (badgeDetails.showRedDot == 1) {
            // 有新的公告信息
        } else {
            // 没有新的公告信息
        }
    }
});

注册自定义事件监听​

当游戏发布的公告配置的跳转链接为「游戏内模块」，或者游戏正文添加了链接并且链接类型为「游戏内模块」的时候，可以通过监听自定义事件来获取消息，并做相应处理。

TapBillboard.RegisterCustomLinkListener(url =>
{
    // 这里返回的 url 地址和游戏在公告系统内配置的地址是一致的
});

解除已注册的自定义事件监听​

如果不想再接收公告的自定义事件监听可以调用下面的接口：

// 已注册的回调对象需要游戏保存，取消注册的时候要把对象传给 SDK
TapBillboard.UnRegisterCustomLinkListener(registerdListener);

展示跑马灯数据​

开始获取跑马灯数据，当请求到内容时，会按照开发者配置的位置及样式进行展示。内部请求采用轮询方式，每 5 分钟发起一次请求。

TapBillboard.StartFetchMarqueeData();

停止获取跑马灯数据​

停止轮询获取跑马灯数据，参数为当展示时是否立刻关闭跑马灯窗口。

TapBillboard.StopFetchMarqueeData(closeNow);

注册公告内容输出状态监听​

当公告展示时输出及关闭音频时，通过该回调通知开发者。

TapBillboard.RegisterOutputStateListener(new OutputStateListener {
    OnPlayVoice = () => {
        Debug.Log("公告页面播放声音");
    },
    OnStopVoice = () => {
        Debug.Log("公告页面关闭声音");
    }
});

解除公告内容输出状态监听​

TapBillboard.UnRegisterOutputStateListener();

国际化​

公告支持设置语言：

TapCommon.SetLanguage(TapLanguage.AUTO);

支持如下语言：

namespace TapTap.Common
{
    public enum TapLanguage
    {
        AUTO = 0, // 自动
        ZH_HANS = 1, // 简体中文
        EN = 2, // 英文
        ZH_HANT = 3, // 繁体中文
        JA = 4, // 日文
        KO = 5, // 韩文
        TH = 6, // 泰文
        ID = 7, // 印尼语
    }
}

「自动」会尝试根据系统语言设置语言，如果系统语言不在上述支持的语言之中，那么会根据 SDK 初始化时配置的区域设置语言。 区域为中国大陆时会设置为简体中文，否则会设置为英文。

错误码​

code场景
400初始化参数错误
403用户无权限访问该服务，需检查开发者中心是否开通了公告服务
50x服务端内部错误，错误内容可以参考 description
19999其它错误，内容可以参考 description

REST API​

下面我们介绍公告系统相关的 REST API 接口。

请求格式​

对于 POST 和 PUT 请求，请求的主体必须是 JSON 格式，而且 HTTP Header 的 Content-Type 需要设置为 application/json。

请求的鉴权是通过 HTTP Header 里面包含的键值对来进行的，参数如下表：

KeyValue含义来源
X-LC-Id{{appid}}当前应用的 App Id（即 Client Id）可在控制台查看
X-LC-Sign{{appSign}}由 sign,timestamp 组成的字符串。其中 timestamp 为客户端产生本次请求的 unix 时间戳（UTC），精确到毫秒。sign 是 timestamp 拼接 App Key（即 Client Token）组成的字符串，再对它做 MD5 签名后的结果。参考下方的计算方式

使用 App Key 来计算 appSign：

md5( timestamp + App Key )
= md5(1453014943466UtOCzqb67d3sN12Kts4URwy8)
= d5bcbb897e19b2f6633c716dfdfaf9be

-H "X-LC-Sign: d5bcbb897e19b2f6633c716dfdfaf9be,1453014943466"

除了在 X-LC-Id 这个 HTTP Header 中传入 Client Id 外，还需要在 URL 中指定 Client Id，两者的值需要一致。

异常时返回 400 （HTTP 状态码）错误，例如：

{
    "success": false,
    "data": {
        "code": 0,
        "error": "invalid_request",
        "msg": "invalid params",
        "error_description": ""
    },
    "now": 1659084246
}

Base URL​

REST API 请求的 Base URL（下文 curl 示例中用 {{host}} 表示）即应用的 API 自定义域名，可以在控制台绑定、查看。详见文档关于域名的说明。

获取模版​

参数约束说明
client_id必须开发者中心后台游戏服务 > 应用配置 中的 Client ID
template必须公告模版类型，目前仅支持导航模版。可填写：导航模版-navigate、图片模版-image。
curl -X GET
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Sign: {{appSign}}' \
  https://{{host}}/billboard/rest-api/v1/pattern/detail?client_id={{appid}}&template={{template}}

返回的主体是一个 JSON 对象，包含创建模版时传入的所有参数：

{
    "success": true,
    "data": {
        "empty_img": {
            "url": "https://tds-billboard.tds1.tapfiles.cn/20220727/aWkG63mpT2WeFrtT0Dxojj4QLfabWHh3.png"
        },
        "highlight_text_color": "#15C5CE",
        ...
    },
    "now": 1659085552
}

获取公告列表​

参数约束说明
client_id必须开发者中心后台游戏服务 > 应用配置 中的 Client ID
lang必须详见语言代码列表
template必须公告模版类型，目前仅支持导航模版。可填写：导航模版-navigate、图片模版-image、开屏模版-splash、跑马灯模版-marquee。
dimension_list可选[{"维度参数":"维度字段参数"},...]，示例：[{"platform":"ios"},{"location":"CN"}]
type必须公告类型。可填写：活动公告-activity、其他统称游戏公告-game。
uuid选填设备唯一 id 字符串，用于支持数据分析。示例："4e4105c7-781e-45c0-92ea-d595c75a3c2c"
curl -X POST
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Sign: {{appSign}}' \
  -H 'Content-Type: application/json' \
  -d '{
        "lang":{{lang}},
        "template":{{template}},
        "type":{{type}},
        "dimension_list":{{dimension_list}}
     }' \
  https://{{host}}/billboard/rest-api/v1/announcement/list?client_id={{appid}}&uuid={{uuid}}

返回的 JSON 对象包含公告列表 list 和最新发布的一条公告详情 lastest。

参数说明
id公告 id
type公告类型：更新公告-update、维护公告-maintenance、上新公告-new、活动公告-activity、玩法公告-play_method、测试公告-test、停服公告-discontinued
expire_time过期时间：秒级时间戳，0-表示不过期
short_title短标题
jump_location跳转位置：content-正文、link-跳转链接、game-游戏内模块
jump_link跳转位置选择「跳转链接」时为对应的链接，选择「游戏内模块」时为对应的模块参数
publish_time发布时间：秒级时间戳
{
    "success": true,
    "data": {
        "list": [
            {
                "id": 2,
                "type": "activity",
                "expire_time": 0,
                "short_title": "公告跳转链接地址",
                "jump_location": "link",
                "jump_link": "https://www.taptap.cn",
                "publish_time": 1659077524
            },
            ...
        ],
        "lastest": {
            "id": 2,
            "content": "正文",
            "short_title": "公告跳转链接地址",
            "long_title": "测试情报｜「起着测试」4月14日开启"
        }
    },
    "now": 1659085756
}

获取公告详情​

参数约束说明
client_id必须开发者中心后台游戏服务 > 应用配置 中的 Client ID
lang必须详见语言代码列表
id必须公告 id
uuid选填设备唯一 id 字符串，用于支持数据分析。示例："4e4105c7-781e-45c0-92ea-d595c75a3c2c"
curl -X GET
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Sign: {{appSign}}' \
  https://{{host}}/billboard/rest-api/v1/announcement/detail?client_id={{appid}}&lang={{lang}}&id={{id}}&uuid={{uuid}}

返回的 JSON 对象

参数说明
id公告 id
content正文
long_title长标题
short_title短标题
{
    "success": true,
    "data": {
        "id": 82,
        "content": "正文",
        "short_title": "短标题",
        "long_title": "长标题"
    },
    "now": 1659087990
}

获取小红点​

参数约束说明
client_id必须开发者中心后台游戏服务 > 应用配置 中的 Client ID
uuid必须设备唯一 id 字符串，示例："4e4105c7-781e-45c0-92ea-d595c75a3c2c"
template必须公告模版类型，目前仅支持导航模版。可填写：导航模版-navigate、图片模版-image。
dimension_list可选[{"维度参数":"维度字段参数"},...]，示例：[{"platform":"ios"},{"location":"CN"}]
curl -X POST \
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Sign: {{appSign}}' \
  -H 'Content-Type: application/json' \
  -d '{
        "uuid": {{uuid}},
        "template":{{template}},
        "dimension_list":{{dimension_list}}
      }' \
  'https://{{host}}/billboard/rest-api/v1/dot/read?client_id={{client_id}}'

返回的 JSON 对象

参数说明
show_red_dot是否展示小红点：0-不展示 1-展示
close_button_img从导航接口中得到的关闭按钮 URL
{
    "success": true,
    "data": {
        "show_red_dot": 0,
        "close_button_img": "https://tds-billboard.tds1.tapfiles.cn/20220727/aMHoqDTHT4zrXYPNprkZjXkdLK6vFg8E.png"
    },
    "now": 1658896487
}

提交小红点​

参数约束说明
client_id必须开发者中心后台游戏服务 > 应用配置 中的 Client ID
uuid必须设备唯一id字符串，示例："4e4105c7-781e-45c0-92ea-d595c75a3c2c"
read_all必须标记公告全部已读：true-是,false-否
curl -X POST \
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Sign: {{appSign}}' \
  -H 'Content-Type: application/json' \
  -d '{
      "uuid": {{uuid}},
      "read_all":{{read_all}}
  }' \
  'https://{{host}}/billboard/rest-api/v1/dot/submit?client_id={{client_id}}'

返回的 JSON 对象

{
    "success": true,
    "data": {
        "msg": "ok"
    },
    "now": 1658895192
}

批量查询公告详情​

参数约束说明
client_id必须开发者中心后台游戏服务 > 应用配置 中的 Client ID
uuid必须设备唯一id字符串，示例："4e4105c7-781e-45c0-92ea-d595c75a3c2c"
ids必须公告唯一id字符串，用逗号分隔。示例："1,2"
lang必须语言。示例："zh_CN"
curl -X GET \
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Sign: {{appSign}}' \
  'https://{{host}}/billboard/rest-api/v1/announcement/detail/multi?client_id={{client_id}}&ids={ids}&uuid={uuid}&lang={lang}'

返回的 JSON 对象

参数说明
id公告 id
content公告正文
type公告类型：更新公告-update、维护公告-maintenance、上新公告-new、活动公告-activity、玩法公告-play_method、测试公告-test、停服公告-discontinued
template公告模版类型
short_title短标题
long_title长标题
jump_location跳转位置：content-正文、link-跳转链接、game-游戏内模块
jump_link跳转位置选择「跳转链接」时为对应的链接，选择「游戏内模块」时为对应的模块参数
publish_time发布时间：秒级时间戳，0-表示不存在
expire_time过期时间：秒级时间戳，0-表示不过期
{
    "success": true,
    "data": {
        "list": [
            {
                "id": 1,
                "content": "[{\"type\":\"paragraph\",\"children\":[{\"text\":\"测试公告排序哈哈哈哈 \"}]},{\"type\":\"block-link\",\"info\":{\"url\":\"test://action\",\"type\":\"game\",\"noLinkTitle\":false},\"children\":[{\"text\":\"测试内部跳转1\"}]},{\"type\":\"paragraph\",\"children\":[{\"text\":\"\"}]},{\"type\":\"block-link\",\"info\":{\"url\":\"test://action2\",\"type\":\"game\",\"noLinkTitle\":false},\"children\":[{\"text\":\"测试内部跳转2\"}]}]",
                "type": "",
                "template": "",
                "short_title": "测试公告排序",
                "long_title": "测试公告排序",
                "jump_location": "",
                "jump_link": "",
                "publish_time": 0,
                "expire_time": 0
            },
            {
                "id": 2,
                "content": "",
                "type": "",
                "template": "",
                "short_title": "",
                "long_title": "",
                "jump_location": "",
                "jump_link": "",
                "publish_time": 0,
                "expire_time": 0
            }
        ]
    },
    "now": 1676010120
}

未读公告-设备维度​

参数约束说明
client_id必须开发者中心后台游戏服务 > 应用配置 中的 Client ID
uuid必须设备唯一id字符串，示例："4e4105c7-781e-45c0-92ea-d595c75a3c2c"
template必须公告模版类型，目前仅支持导航模版。可填写：开屏模版-splash、跑马灯模版-marquee。
dimension_list可选[{"维度参数":"维度字段参数"},...]，示例：[{"platform":"ios"},{"location":"CN"}]
curl -X POST \
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Sign: {{appSign}}' \
  -H 'Content-Type: application/json' \
  -d '{
        "uuid": {{uuid}},
        "template":{{template}},
        "dimension_list":{{dimension_list}}
      }' \
  'https://{{host}}/billboard/rest-api/v1/announcement/unread?client_id={clientId}'

返回的 JSON 对象

参数说明
id公告 id
publish_time发布时间：秒级时间戳，0-表示不存在
expire_time过期时间：秒级时间戳，0-表示不过期
{
    "success": true,
    "data": {
        "list": [
            {
              "id":1,
              "publish_time": 1669203905,
              "expire_time": 1670672278
            },
            {
              "id":2,
              "publish_time": 1669203905,
              "expire_time": 1670672278
            }
        ]
    },
    "now": 1666853298
}

标记已读-设备维度​

注：该设备中，未读公告接口中不在返回已标记的公告id。ids当前仅限跑马灯类型的公告，否则返回异常信息

参数约束说明
client_id必须开发者中心后台游戏服务 > 应用配置 中的 Client ID
uuid必须设备唯一id字符串，示例："4e4105c7-781e-45c0-92ea-d595c75a3c2c"
ids必须公告唯一id数组。示例：[1,3]
curl -X POST \
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Sign: {{appSign}}' \
  -H 'Content-Type: application/json' \
  -d '{
        "uuid": {{uuid}},
        "ids":{{ids}}
      }' \
  'https://{{host}}/billboard/rest-api/v1/announcement/mark?client_id={clientId}'

返回的 JSON 对象

{
    "success": true,
    "data": {
        "msg": "ok"
    },
    "now": 1670318366
}

取消已读标记-设备维度​

注：该设备中，维度公告接口中再次返回取消标记的公告id

参数约束说明
client_id必须开发者中心后台游戏服务 > 应用配置 中的 Client ID
uuid必须设备唯一id字符串，示例："4e4105c7-781e-45c0-92ea-d595c75a3c2c"
curl -X POST \
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Sign: {{appSign}}' \
  -H 'Content-Type: application/json' \
  -d '{
        "uuid": {{uuid}},
      }' \
  'https://{{host}}/billboard/rest-api/v1/announcement/unmark?client_id={clientId}'

返回的 JSON 对象

{
    "success": true,
    "data": {
        "msg": "ok"
    },
    "now": 1670318366
}

语言代码列表​

使用 ISO 639-1 中定义的双小写字母语言代码（例如，en 表示英语，jp 表示日语），但：

  1. ISO 639-1 中未包括的语言，使用 ISO 632-2 中定义的三小写字母语言代码（例如，fil 表示菲律宾语）
  2. 仅使用语言代码无法表示所需语言时，附加 ISO 3166-1 中定义的地区代码（例如，zh_CN 表示简体中文）

当前 REST API 支持的语言代码如下：

代码语言
zh_CN简体中文
zh_TW繁体中文
en_US英语（美国）
ja_JP日文
ko_KR韩文
pt_PT葡萄牙语
vi_VN越南语
hi_IN印度语
id_ID印尼语
ms_MY马来语
th_TH泰语
es_ES西班牙语
af南非荷兰语
am阿姆哈拉语
bg保加利亚语
ca加泰罗尼亚语
hr克罗地亚语
cs捷克语
da丹麦语
nl荷兰语
et爱沙尼亚语
fil菲律宾语
fi芬兰语
fr法语
de德语
el希腊语
he希伯来语
hu匈牙利语
is冰岛语
it意大利语
lv拉脱维亚语
lt立陶宛语
no挪威语
pl波兰语
ro罗马尼亚语
ru俄语
sr塞尔维亚语
sk斯洛伐克语
sl斯洛文尼亚语
sw斯瓦希里语
sv瑞典语
tr土耳其语
uk乌克兰语
zu祖鲁语

注意，上表中的部分语言虽然 REST API 支持，但客户端 SDK 并没有支持。