激励视频完播回调

本接口为回调接口，由 Game SVR 实现并在 SUD OP 后台配置回调地址，SUD OP SVR 在 APP 广告平台完播验证通过后调用此接口，通知 Game SVR 发放奖励。

接口说明

接口英文名 ad.rewardNotify

功能描述 激励视频完播回调。SUD OP SVR 在 APP 广告平台完播验证通过后，主动调用 Game SVR 配置的回调地址，通知 Game SVR 发放奖励。

注意：本接口强制要求服务通信二次加密和签名：回调请求必须验签并解密后才能处理业务，可有效防止数据篡改与泄露。

接口信息

项	值
调用方	SUD OP SVR
提供方	Game SVR
触发时机	APP 广告平台完播验证通过后

调用方式

HTTPS 调用

POST <Game 自定义回调地址>

回调地址由 Game 在 SUD OP 后台配置，请使用 HTTPS 地址。

请求参数 - Body

属性	类型	默认值	必填	说明
id	string		是	回调通知 ID
create_time	number		是	回调通知创建时间（秒级时间戳）
event	string		是	事件类型，固定为 ad_reward_notify
payload	object		是	事件数据，详见下方说明

payload 字段说明

激励视频完播通知：ad_reward_notify

属性	类型	默认值	必填	说明
transaction_id	string		是	SUD OP 生成的事务 ID，作为幂等键，防止重复发奖
user_id	string		是	用户标识，由客户端 setServerSideVerificationData 传入
reward_item	string		是	奖励品类名称，如 金币，由客户端 setServerSideVerificationData 传入
reward_amount	number		是	奖励数量，由客户端 setServerSideVerificationData 传入
custom_data	string		否	开发者自定义数据，由客户端 setServerSideVerificationData 传入
ad_unit_id	string		是	SUD OP 广告位 ID

安全提示：reward_item、reward_amount、custom_data 均由客户端通过 setServerSideVerificationData 传入，存在被篡改的风险。Game SVR 必须根据服务端配置（如 ad_unit_id 对应的奖励规格表）确定真实的奖励品类与数量，严禁直接信任 payload 中的 reward_amount 进行发奖。user_id/custom_data 同样需要在服务端核对其合法性。

返回值

返回的 JSON 数据包

属性	类型	说明
errcode	int32	错误码，0 表示协议层处理成功（验签、解密、字段解析均通过）
errmsg	string	错误信息
is_valid	boolean	业务层奖励发放结果。true：奖励已发放；false：业务校验未通过或本次未发放（如奖励配置缺失、用户不合法、命中幂等已处理等）

返回值语义约定

场景	推荐返回
验签 / 解密失败	直接拒绝请求，返回非 200 HTTP 状态码（如 401 / 403），不要进入业务层返回 is_valid: false。SUD OP 会据此重试或告警
协议正常，奖励发放成功	errcode: 0 + is_valid: true
协议正常，命中幂等（同一 transaction_id 已处理）	errcode: 0 + is_valid: true（视作已发放，但不重复发放）
协议正常，业务校验未通过（如用户不存在、奖励配置缺失）	errcode: 0 + is_valid: false
Game SVR 内部异常，期望 SUD OP 重试	返回非 200 HTTP 状态码或非 0 errcode

调用示例

请求数据示例

{
  "id": "notify_20260429_abc123",
  "create_time": 1745929600,
  "event": "ad_reward_notify",
  "payload": {
    "transaction_id": "sudtx_20260423_abc123xyz",
    "user_id": "user-001",
    "reward_item": "金币",
    "reward_amount": 10,
    "custom_data": "level=5",
    "ad_unit_id": "sud_ad_unit_abc123"
  }
}

返回数据示例

成功发奖：

{
  "errcode": 0,
  "errmsg": "ok",
  "is_valid": true
}

校验失败：

{
  "errcode": 0,
  "errmsg": "ok",
  "is_valid": false
}

上例代表协议层校验通过、但业务层未发奖（如 user_id 不存在、ad_unit_id 未配置奖励规格等）。验签失败请按上文"返回值语义约定"直接拒绝请求，不要走此返回。

幂等说明

• Game SVR 以 payload.transaction_id 为幂等键，保证同一笔完播事务仅发放一次奖励。
• SUD OP SVR 因超时重试发送相同 transaction_id 时，Game SVR 应返回 is_valid: true，但不重复发放奖励。

超时与重试

项	要求
Game 响应超时阈值	≤ 5 s
触发重试的条件	Game SVR 未在超时阈值内响应、返回非 200 HTTP 状态码、或返回非 0 errcode
总重试次数	最多 15 次
重试间隔（秒）	15, 15, 30, 180, 600, 1200, 1800, 1800, 1800, 3600, 10800, 10800, 10800, 21600, 21600（累计约 24 小时）

返回 errcode: 0 + is_valid: false 视为业务层主动拒绝发奖，不会触发重试。如需 SUD OP 重试，请返回非 0 errcode 或非 200 状态码。

鉴权说明

SUD OP 调用本接口时，强制携带加密和签名信息，不存在明文回调模式。Game SVR 必须对请求进行验签和解密，以确认请求来源合法后才能处理发奖逻辑。

注意事项

1. transaction_id 须做幂等校验，防止 SUD OP SVR 重试时重复发放奖励。
2. Game SVR 必须验签。验签失败应直接拒绝请求（返回非 200 HTTP 状态码），不要进入业务返回流程，避免伪造请求触发发奖。
3. reward_item / reward_amount 等客户端透传字段不可信，发奖前必须在服务端根据 ad_unit_id 等服务端配置核对真实奖励规格。
4. create_time 与服务器当前时间差超过 5 分钟的请求应直接拒绝，防止重放攻击。
5. SUD OP SVR 在 APP 完播验证通过后才会调用此接口，Game SVR 无需再向 APP 平台二次验证。