跳到主要内容

开发指南

检查游戏公告​

游戏侧可通过该 API 获取当前场景下是否存在新的游戏公告，以此设置游戏公告 UI 入口的红点提醒，提示用户查看公告。

支持平台​

Android iOS Windows HarmonyOS WebGL

方法签名​

public static void CheckAnnouncements(CheckAnnouncementsOptions opts, Action<Result<CheckAnnouncementsResult>> callback);

代码示例​

Show Code 
var opts = new CheckAnnouncementsOptions
{
    Profile = "User ID",
    Level = 1
};

ComboSDK.CheckAnnouncements(opts, r =>
{
    if (r.IsSuccess)
    {
        var result = r.Data;
        if (result.newAnnouncementsAvailable) 
        {
            //TODO: 存在新公告处理
        }
    }
    else
    {
        var error = r.Error;
        Debug.LogError("检查游戏公告失败：" + error.DetailMessage)
    }
});

方法参数​

ParametersRequiredTypeDescription
optsTrueCheckAnnouncementsOptions检查是否存在新公告所需传入的参数集
callbackTrueAction<Result<CheckAnnouncementsResult>>检查是否存在新公告完成后的回调方法

CheckAnnouncementsOptions​

ParametersRequiredTypeDescription
ProfileFalsestring当前登录的游戏数据的唯一标识，通常为游戏角色 ID
LevelFalseint世游与游戏规定的用于限制公告可见性的指标，通常为游戏角色/账号等级，不传则当成 0 来处理
提示

游戏侧可以根据产品本身的特点选择 Profile 的取值。通常选择游戏角色 ID 即可，但如果游戏本身分区服，且游戏角色 ID 不是全局唯一，则可以用游戏服务器 ID + 游戏角色 ID 得到 Profile。

CheckAnnouncementsResult​

PropertiesSupported PlatformsTypeDescription
newAnnouncementsAvailableAndroid iOS Windowsbool是否有新公告
- true: 有新公告
- false: 没有新公告

Error​

CodeSupported PlatformsDescription
NETWORK_ERRORAndroid iOS Windows网络错误
SERVER_ERRORAndroid iOS Windows服务端错误
UNKNOWN_ERRORAndroid iOS Windows未知错误
提示

错误处理请参阅。

打开游戏公告​

支持平台​

Android iOS Windows HarmonyOS

方法签名​

public static void OpenAnnouncements(OpenAnnouncementsOptions opts, Action<Result<OpenAnnouncementsResult>> callback);

代码示例​

Show Code 
var opts = new OpenAnnouncementsOptions
{
    Profile = "User ID",
    Level = 1,
    Width = 70,
    Height = 90
};

ComboSDK.OpenAnnouncements(opts, r =>
{
    if (r.IsSuccess)
    {
        var result = r.Data;
        //TODO: 用户关闭游戏公告页面后的处理（如隐藏提示小红点 UI）
    }
    else
    {
        var error = r.Error;
        Debug.LogError("打开游戏公告失败：" + error.DetailMessage)
    }
});

方法参数​

ParametersRequiredTypeDescription
optsTrueOpenAnnouncementsOptions打开游戏公告所需传入的参数集
callbackTrueAction<Result<OpenAnnouncementsResult>>打开游戏公告完成后的回调方法，当游戏公告成功打开时，会在用户关闭游戏公告页面时返回

OpenAnnouncementsOptions​

ParametersRequiredTypeDescription
ProfileFalsestring当前登录的游戏数据的唯一标识，通常为游戏角色 ID
LevelFalseint世游与游戏规定的用于限制公告可见性的指标，通常为游戏角色/账号等级，不传则当成 0 来处理
WidthFalseint公告页面宽度占屏幕宽度的百分比，取值范围为 (0,100]
HeightFalseint公告页面高度占屏幕高度的百分比，取值范围为 (0,100]
提示
  • 游戏侧可以根据产品本身的特点选择 Profile 的取值。通常选择游戏角色 ID 即可，但如果游戏本身分区服，且游戏角色 ID 不是全局唯一，则可以用游戏服务器 ID + 游戏角色 ID 得到 Profile。
  • Width 和 Height 若不在取值范围内，则使用 SDK 内部的默认显示策略。

OpenAnnouncementsResult​

PropertiesSupported PlatformsTypeDescription
提示

当游戏公告成功打开时，会在用户关闭游戏公告页面时返回，可在此时进行游戏公告页面关闭后的处理，如隐藏新公告提示小红点 UI 等。

Error​

CodeSupported PlatformsDescription
INVALID_ANNOUNCEMENTS_URLAndroid iOS Windows HarmonyOS公告页面地址错误
NETWORK_ERRORAndroid iOS Windows HarmonyOS网络错误
SERVER_ERRORAndroid iOS Windows HarmonyOS服务端错误
UNKNOWN_ERRORAndroid iOS Windows HarmonyOS未知错误
提示

错误处理请参阅。

获取公告数据​

获取当前发行版本下所有有效公告的完整信息，包括公告正文内容。游戏侧可基于返回的数据自行渲染公告 UI。

调用时机说明

此 API 会同时更新本次公告查看的时间戳与等级（等同于一次 OpenAnnouncements），游戏侧应在用户打开公告界面时调用，不要在启动时预加载。若提前调用，会导致公告被立即标记为已读，使 CheckAnnouncements 无法正确返回新公告提示。

支持平台​

Android iOS Windows HarmonyOS WebGL

方法签名​

public static void GetAnnouncements(GetAnnouncementsOptions opts, Action<Result<GetAnnouncementsResult>> callback);

代码示例​

Show Code 
var opts = new GetAnnouncementsOptions
{
    Profile = "Profile",
    Level = 1
};

ComboSDK.GetAnnouncements(opts, r =>
{
    if (r.IsSuccess)
    {
        var result = r.Data;
        foreach (var announcement in result.Announcements)
        {
            //TODO: 根据 announcement.Format 渲染公告内容
        }
    }
    else
    {
        var error = r.Error;
        Debug.LogError("获取公告数据失败：" + error.DetailMessage)
    }
});

方法参数​

ParametersRequiredTypeDescription
optsTrueGetAnnouncementsOptions获取公告数据所需传入的参数集
callbackTrueAction<Result<GetAnnouncementsResult>>获取公告数据完成后的回调方法

GetAnnouncementsOptions​

ParametersRequiredTypeDescription
ProfileFalsestring当前登录的游戏数据的唯一标识，通常为游戏角色 ID。未登录的状态下可不传
LevelFalseint游戏内等级。多角色的游戏传当前角色等级。未登录的状态下 Level 传 0，不传则当成 0 来处理
提示

游戏侧可以根据产品本身的特点选择 Profile 的取值。通常选择游戏角色 ID 即可，但如果游戏本身分区服，且游戏角色 ID 不是全局唯一，则可以用游戏服务器 ID + 游戏角色 ID 得到 Profile。

GetAnnouncementsResult​

PropertiesSupported PlatformsTypeDescription
AnnouncementsAndroid iOS Windows HarmonyOS WebGLList<Announcement>公告列表，每个元素是一个 Announcement
提示

Announcements 是一个有序集合，优先级越高的公告排在前面，优先级相同时按创建时间倒序排列，游戏侧需按数组顺序展示公告。 若无公告则返回空列表。

Announcement​

PropertiesTypeDescription
Idstring公告 ID
Titlestring公告标题
Subtitlestring公告子标题。如果无值则可使用 Title
Contentstring公告正文内容
Formatstring内容格式，当前支持 html（HTML 格式的富文本）和 plaintext（普通文本）
Langstring公告的本地化语言，遵循 IETF BCP 47 语言标签规范。如果无值则说明使用的是公告的默认内容
PublishedAtint公告的发布时间，Unix timestamp in seconds
提示
  • 游戏侧需要与世游侧提前约定公告内容的 Format 及具体格式规范。
  • Format 为 plaintext 时，公告内容不包含 HTML 标签的纯文本，游戏侧需按照约定的内容格式自行完成解析与渲染。
  • Format 为 html 时，公告内容为 HTML 富文本，游戏侧需自行处理对应的 HTML 解析与渲染逻辑。

Error​

CodeSupported PlatformsDescription
SERVER_ERRORAndroid iOS Windows HarmonyOS WebGL服务端错误
NETWORK_ERRORAndroid iOS Windows HarmonyOS WebGL网络错误
SYSTEM_ERRORAndroid iOS Windows HarmonyOS WebGL系统错误
提示

错误处理请参阅。

最后于 更新