跳转到主要内容
本主题提供设置用户在线 Presence 状态的示例代码。XBOX 服务 Rich Presence 提供了向其他玩家通告玩家当前活动的功能。 有关详细信息,请参阅 Rich Presence 概述。

更新用户的在线 Presence 状态

此示例代码设置用户的在线 Presence 状态。 以下示例使用扁平 C API。
有关详细信息,请参阅以下内容:

更新 Rich Presence 状态

以下示例为用户设置 playingMap Rich Presence 字符串。在此示例中,playingMap 配置为不含令牌的静态字符串。xboxLiveContext 是该用户的 XblContextHandle,queue 是游戏的任务队列;若要使用进程默认任务队列,请传入 nullptr。
如果配置的在线状态字符串需要显式替换字符串,请按占位符顺序将 presenceTokenIds 设置为其配置的字符串 ID,并将 presenceTokenIdsCount 设置为数组长度。 如果 scid 或 presenceId 成员为空,则请求仅包含活动或非活动状态,不包含 Rich Presence 字符串。 有关详细信息,请参阅以下内容:

速率限制和认证

Presence 服务允许每个用户和游戏每 15 秒写入 3 次,每 300 秒写入 30 次。请在玩家活动发生更改时更新 Rich Presence,并将快速连续的更改合并为一次更新。如果你还会定期刷新 Rich Presence,请将合并后的速率控制在这两项限制之内。 如果调用失败并返回 HTTP_E_STATUS_429_TOO_MANY_REQUESTS (XblErrorCondition::Http429TooManyRequests),请不要循环重试。服务响应包含 Retry-After 标头,XSAPI 会遵循该标头。 如果游戏的请求速率达到或超过持续限制的 10 倍(即每 300 秒 300 次 Presence 写入),则认证测试 XR-132 会判定该游戏失败。此阈值并非安全的运行余量。有关详细信息,请参阅细粒度速率限制。
最后修改于 2026年10月30日