Ad API

自 v0.2.0 起，激励视频、横幅、分享统一为单一的奖励槽位模型。查询活跃槽位列表进行渲染，用户点击时通过一次 ShowRewardedAd(slot) 调用执行。若不使用槽位、只展示激励视频，可直接使用下方的 ShowRewardedAd(adUnitId, ...)。

统一奖励槽位

每个槽位的结构如下。

RewardedAdSlot:

字段	类型	说明
`slotId`	`string`	槽位标识符（执行时指定）
`action`	`string`	动作类型 (`"REWARD_VIDEO"` / `"BANNER"` / `"SHARE"`)
`slotData`	`RewardSlotData`	游戏渲染用数据（可选 — 见下方说明）

RewardSlotData:

字段	类型	说明
`imageUrl`	`string`	槽位图片 URL（游戏自行渲染）
`title`	`string`	槽位标题
`expiresAt`	`long`	过期时间（Unix 毫秒，0 表示未设置）

slotData 在默认的激励视频·分享槽位中可能为空（无需渲染的视觉元素）。横幅槽位通常包含 slotData.imageUrl。由于 JsonUtility 的特性，slotData 可能以空对象传入，请在使用前确认 imageUrl 等字段是否为空。

`GetRewardedAdSlots(onSuccess, onFail)`

查询全部活跃奖励槽位列表。

参数:

参数	类型	必须	说明
`onSuccess`	`Action<GetRewardedAdSlotsResult>`	-	成功回调 (`slots`)
`onFail`	`Action<string>`	-	失败回调

成功响应 (GetRewardedAdSlotsResult):

字段	类型	说明
`slots`	`RewardedAdSlot[]`	活跃槽位列表

TudadaSDK.Instance.GetRewardedAdSlots(
    onSuccess: (res) => {
        if (res.slots.Length == 0) return;
        foreach (var slot in res.slots)
            Debug.Log($"{slot.slotId} / {slot.action}");
    },
    onFail: (err) => Debug.LogWarning("槽位查询失败: " + err)
);

`GetRewardedAdSlot(slotId, onSuccess, onFail)`

按 slotId 查询单个槽位。若槽位不存在，将调用 onFail。

参数:

参数	类型	必须	说明
`slotId`	`string`	✅	要查询的槽位 ID
`onSuccess`	`Action<GetRewardedAdSlotResult>`	-	成功回调 (`slot`)
`onFail`	`Action<string>`	-	失败回调（包括槽位不存在）

`ShowRewardedAd(slot, onSuccess, onFail)`（推荐）

执行槽位。平台会根据槽位的 action（视频/横幅/分享）自动分发。加载·展示·失败时的重试与提示均由平台自动处理。

参数:

参数	类型	必须	说明
`slot`	`RewardedAdSlot`	✅	从 `GetRewardedAdSlots` / `GetRewardedAdSlot` 获取的槽位
`onSuccess`	`Action<ShowRewardedAdResult>`	-	成功回调 (`isEnded`)
`onFail`	`Action<string>`	-	失败回调

TudadaSDK.Instance.GetRewardedAdSlots(
    onSuccess: (res) => {
        if (res.slots.Length == 0) return;
        var slot = res.slots[0];
        TudadaSDK.Instance.ShowRewardedAd(slot,
            onSuccess: (r) => { if (r.isEnded) GiveReward(); }, // 奖励发放由游戏自行处理
            onFail: (err) => Debug.LogError("奖励执行失败: " + err)
        );
    });

奖励发放由游戏自行处理

当 isEnded 为 true 时即为奖励发放对象，实际奖励发放由游戏自行执行。加载失败时平台会自动重试，最终失败时会显示提示弹窗，因此游戏无需另行实现错误 UI。

`ShowRewardedAd(adUnitId, onSuccess, onFail)`（激励视频）

不使用槽位，仅通过一次调用展示激励视频广告。广告加载、展示、失败重试及提示均由平台自动处理。

参数:

参数	类型	必须	说明
`adUnitId`	`string`	✅	广告单元 ID
`onSuccess`	`Action<ShowRewardedAdResult>`	-	成功回调
`onFail`	`Action<string>`	-	失败回调

成功响应 (ShowRewardedAdResult):

字段	类型	说明
`isEnded`	`bool`	广告观看完成与否

TudadaSDK.Instance.ShowRewardedAd("ad-unit-id",
    onSuccess: (result) => {
        if (result.isEnded)
        {
            Debug.Log("发放奖励!");
            GiveReward();
        }
    },
    onFail: (err) => {
        Debug.LogError("广告展示失败: " + err);
    }
);

参考: 广告加载失败时，平台会自动重试，最终失败时会显示提示弹窗。游戏中无需单独实现错误处理 UI。

`CreateRewardedVideoAd(adUnitId)`（旧版）

创建激励视频广告实例。

即将停止支持: 此旧版实例 API 已由统一的 ShowRewardedAd() 替代，将在下一版本中移除（[System.Obsolete] 特性 — 使用时产生编译警告）。

参数:

参数	类型	必须	说明
`adUnitId`	`string`	✅	广告单元 ID

实例成员 (TudadaRewardedVideoAd):

成员	类型	说明
`Load(onSuccess?, onFail?)`	方法	加载广告
`Show(onSuccess?, onFail?)`	方法	展示广告
`Destroy()`	方法	销毁实例
`IsLoaded`	`bool`	是否加载完成
`IsDestroyed`	`bool`	是否已销毁
`AdUnitId`	`string`	广告单元 ID
`OnLoad`	事件	加载完成
`OnError`	事件	发生错误
`OnClose`	事件	关闭（包含 `isEnded`）

// 创建广告实例
TudadaRewardedVideoAd rewardedAd = TudadaSDK.Instance.CreateRewardedVideoAd("ad-unit-id");

// 注册事件
rewardedAd.OnLoad += () => {
    Debug.Log("广告加载完成");
};

rewardedAd.OnError += (err) => {
    Debug.LogError("广告错误: " + err.errMsg);
};

rewardedAd.OnClose += (result) => {
    if (result.isEnded)
    {
        // 用户观看完整广告 → 发放奖励
        Debug.Log("发放奖励!");
        GiveReward();
    }
    else
    {
        // 中途关闭
        Debug.Log("广告中途关闭");
    }

    // 为下一个广告重新加载
    rewardedAd.Load();
};

// 加载广告
rewardedAd.Load(
    onSuccess: (result) => Debug.Log("加载成功"),
    onFail: (err) => Debug.LogError("加载失败: " + err)
);

展示广告:

// 加载完成后展示
if (rewardedAd.IsLoaded)
{
    rewardedAd.Show(
        onSuccess: (result) => Debug.Log("广告已展示"),
        onFail: (err) => Debug.LogError("展示失败: " + err)
    );
}

重要: 使用完毕的广告实例请调用 Destroy() 进行清理。

v0.2.0 推荐改用统一奖励槽位（action: "BANNER"）。下方的横幅 API 为兼容而保留。

横幅广告采用槽位模型：游戏在屏幕上定义槽位（如 "main_menu_top"），由游戏自行渲染广告图片。SDK 仅负责图片 URL 的传递与动作处理。

bannerId 兼作槽位名称的横幅标识符。
用户点击横幅时，游戏调用 RunBannerAction(bannerId)。
响应只携带 success / fail 信号，奖励发放在游戏内部完成。

`GetAvailableBannerIds(onSuccess, onFail)`

获取当前活跃的横幅槽位 ID 列表。

参数：

参数	类型	必填	说明
`onSuccess`	`Action<GetAvailableBannerIdsResult>`	-	成功回调
`onFail`	`Action<string>`	-	失败回调

TudadaSDK.Instance.GetAvailableBannerIds(
    onSuccess: (result) => {
        foreach (var slotName in result.bannerIds)
        {
            Debug.Log("活跃槽位: " + slotName);
        }
    },
    onFail: (err) => Debug.LogWarning("查询失败: " + err)
);

`GetBanner(bannerId, onSuccess, onFail)`

按槽位名称获取匹配的横幅数据。如果槽位未匹配到广告，将调用 onFail。

参数：

参数	类型	必填	说明
`bannerId`	`string`	✅	兼作槽位名称的横幅 ID
`onSuccess`	`Action<GetBannerResult>`	-	成功回调
`onFail`	`Action<string>`	-	失败回调（包括"无匹配"）

成功响应（GetBannerResult.banner）：

字段	类型	说明
`bannerId`	`string`	兼作槽位名称的横幅 ID
`imageUrl`	`string`	图片 URL（游戏自行渲染）
`expiresAt`	`long`	过期时间（Unix 毫秒，0 表示未设置）

TudadaSDK.Instance.GetBanner("main_menu_top",
    onSuccess: (result) => {
        // 将 result.banner.imageUrl 下载为纹理并显示在 UI 中
        StartCoroutine(LoadBannerTexture(result.banner.imageUrl));
    },
    onFail: (err) => Debug.LogWarning("该槽位无可用广告: " + err)
);

`RunBannerAction(bannerId, onSuccess, onFail)`

用户点击横幅时由游戏调用。SDK 处理动作并仅通知 success / fail 信号。

奖励发放在游戏内部完成。

参数：

参数	类型	必填	说明
`bannerId`	`string`	✅	兼作槽位名称的横幅 ID
`onSuccess`	`Action`	-	成功回调 — 游戏发放奖励等
`onFail`	`Action<string>`	-	失败回调

// 用户点击横幅时调用
bannerButton.onClick.AddListener(() => {
    TudadaSDK.Instance.RunBannerAction("main_menu_top",
        onSuccess: () => GrantReward(),
        onFail: (err) => Debug.LogError("处理失败: " + err)
    );
});

Ad API​

统一奖励槽位​

GetRewardedAdSlots(onSuccess, onFail)​

GetRewardedAdSlot(slotId, onSuccess, onFail)​

ShowRewardedAd(slot, onSuccess, onFail)（推荐）​

ShowRewardedAd(adUnitId, onSuccess, onFail)（激励视频）​

CreateRewardedVideoAd(adUnitId)（旧版）​

横幅广告（槽位模型）​

GetAvailableBannerIds(onSuccess, onFail)​

GetBanner(bannerId, onSuccess, onFail)​

RunBannerAction(bannerId, onSuccess, onFail)​

Ad API

统一奖励槽位

`GetRewardedAdSlots(onSuccess, onFail)`

`GetRewardedAdSlot(slotId, onSuccess, onFail)`

`ShowRewardedAd(slot, onSuccess, onFail)`（推荐）

`ShowRewardedAd(adUnitId, onSuccess, onFail)`（激励视频）

`CreateRewardedVideoAd(adUnitId)`（旧版）

横幅广告（槽位模型）

`GetAvailableBannerIds(onSuccess, onFail)`

`GetBanner(bannerId, onSuccess, onFail)`

`RunBannerAction(bannerId, onSuccess, onFail)`