广告系统

GameCore.AdvertisingSystem.Ads 提供服务端激励视频广告入口，适合“观看广告后领取奖励、刷新次数、复活、领取双倍收益”等场景。广告请求由服务端发起并等待平台结果，项目代码只在服务端确认结果后发放奖励，避免客户端单方面伪造奖励。

使用边界

• 仅服务端可用。调用代码应放在 #if SERVER 内。
• 当前真实广告播放链路仅可在线上正式环境测试。外网测试环境、Windows 编辑器、本地调试和缺少平台广告能力的环境不应作为广告播放成功验证环境。
• 在线上正式环境中，只在 Android 和 iOS 客户端上发起真实平台广告。
• 编辑器调试模式（Game.IsDebugTestMode）不会提前拦截广告请求；当底层广告能力明确返回失败时，会额外写入 warning 日志并返回 RewardedVideoAdStatus.RequestFailed。
• 不要用通用 ServerChannel 自行拼接广告验证频道。广告验证通道由框架和 Host 层按平台规则单独处理。

基础流程

服务端                       客户端平台 SDK                    平台验证
  │                              │                              │
  │ Ads.ShowRewardedVideoAsync() │                              │
  │ ───────────────────────────→ │ 拉起激励视频广告              │
  │                              │                              │
  │                              │ Android 等待 TapADN 验证 ───→│
  │                              │←────────────── 验证结果 ─────│
  │←────────────── RewardedVideoAdResult ───────────────────────│
  │ IsCompleted == true 时发放奖励                              │

项目侧不需要自己生成广告请求 ID，也不需要管理订阅/取消订阅。框架会为每次请求生成内部验证标识，并在请求结束、失败、取消或超时后清理等待状态。

服务端调用示例

#if SERVER
using GameCore.AdvertisingSystem;

public static async Task TryGrantRewardedAdBonusAsync(Player player)
{
    var result = await Ads.ShowRewardedVideoAsync(player);
    if (!result.IsCompleted)
    {
        Game.Logger.LogWarning(
            "Rewarded ad was not completed. Player={Player}, Status={Status}, Message={Message}",
            player, result.Status, result.Message);
        return;
    }

    await GrantRewardAsync(player);
}

private static Task GrantRewardAsync(Player player)
{
    // 在这里执行项目自己的奖励逻辑，例如发放货币、复活、刷新次数或领取双倍收益。
    return Task.CompletedTask;
}
#endif

如果某个玩法需要更短或更长的等待时间，可以传入自定义 TimeSpan：

#if SERVER
var result = await Ads.ShowRewardedVideoAsync(
    player,
    timeout: TimeSpan.FromSeconds(90));
#endif

结果状态

状态	含义	推荐处理
Completed	已达到项目可发放奖励的条件。	发放奖励，并按项目需要记录日志或刷新 UI。
RequestFailed	广告请求未能成功发起，或客户端明确失败；如果此时处于调试模式，会额外写入 warning 日志。	不发奖励；提示玩家稍后重试或在调试环境中忽略该流程。
Timeout	请求已发出，但在超时时间内没有等到平台结果。	不发奖励；提示网络或广告服务暂时不可用。
Canceled	调用方传入的 CancellationToken 取消了本次等待。	按项目自己的取消流程处理，通常不发奖励。

RewardedVideoAdResult.IsCompleted 是最推荐的发奖判断入口。不要只根据请求是否发出、客户端是否打开了广告页面、或 Message 文本判断奖励条件。

平台语义

平台/环境	完成条件
Android	客户端成功发起广告后，服务端等待 TapADN 验证回调；收到匹配的验证结果后返回 Completed。
iOS	按内嵌平台 SDK 的本地结果处理；SDK 成功发起播放后返回 Completed，明确失败时返回 RequestFailed。
外网测试环境	目前不作为真实广告播放测试环境；不要用它验证广告成功播放或发奖链路。
编辑器调试模式	不因调试模式提前失败；如果底层广告能力明确失败，会写 warning 日志并返回 RequestFailed。
其他缺少平台广告能力的环境	不应依赖真实广告播放；通常会以 RequestFailed 结束。

Android 的结果由服务端平台验证确认，适合严格的奖励发放链路。iOS 按当前平台接入约定处理本地完成结果，项目代码不需要额外标记为“不可信”或分平台写奖励逻辑；统一检查 IsCompleted 即可。

常见错误

在客户端代码里调用广告 API

Ads.ShowRewardedVideoAsync 是服务端 API。客户端按钮点击后，应通过项目自己的双端事件、类型化消息或已有业务请求通知服务端，由服务端调用广告 API 并决定是否发奖励。

请求发出后立即发奖

不要把“广告请求已发出”当成“广告已完成”。应等待 await Ads.ShowRewardedVideoAsync(...) 返回，并只在 result.IsCompleted 为 true 时发奖。

在编辑器调试时期待真实广告弹窗

编辑器调试模式通常没有真实平台广告播放环境。框架不会因为 Game.IsDebugTestMode 提前拦截请求；如果底层广告能力明确失败，会写 warning 并返回 RequestFailed，便于发现代码路径已经走到广告逻辑。需要测试真实广告链路时，请使用线上正式环境中的 Android 或 iOS 客户端。

在外网测试环境验证广告成功

当前真实广告播放功能仅可在线上正式环境测试。外网测试环境可以用于检查项目代码是否已接入服务端广告 API、按钮和发奖分支是否能编译通过，但不要把外网测试环境的广告结果作为真实播放成功或收益统计验证依据。