# Unity 软件包的奖励广告服务集成

> 通过初始化 SDK、在初始化后创建广告对象以及实现监听器来处理广告事件来集成奖励视频广告单元，通过app内奖励来提高用户参与度。

Unity LevelPlay 奖励广告是由用户发起的广告单元，为用户提供了参与全屏广告服务以换取 app 内奖励的机会，从而在提高参与度的同时保持积极的用户体验。

> **Note:**
>
> 本文档与 SDK 8.5.0+ 相关。

## 先决条件##prerequisites

* 确保已将 LevelPlay Unity 软件包确集成到应用程序中。[此处](/grow/levelplay/sdk/unity/package-integration.md)概述了集成。
* 确保使用 LevelPlay Initialization API 初始化 SDK。
* 在 LevelPlay 后台中找到 AdUnitID。

## 创建奖励广告对象##create-rewarded-ad-object

奖励广告对象的创建必须在收到 **OnInitSuccess** 回调后执行。

该对象是可重用的实例，可以处理多个加载并在整个会话中显示。创建后，应使用 来加载和展示同一广告单元的广告服务。

对于更高级的实现，如有必要，您可以创建多个奖励广告对象。

您可以通过调用以下函数来创建广告对象：

```csharp
// Create Rewarded Ad object 
LevelPlayRewardedAd rewardedAd = new LevelPlayRewardedAd(rewardedAdUnitId);
```

> **Note:**
>
> `LevelPlayRewardedAd` 构造函数还支持可选的 `Config` 参数：
>
> ```csharp
> // 使用可选的 Config 参数
> LevelPlayRewardedAd(string adUnitId, Config config = null)
> ```
>
> 如果不需要特殊设置，可以省略 `Config` 参数，仅通道 `adUnitId`。

### 使用价格地面创建##creating-with-a-price-floor

要为广告请求设置可选的价格地面，请在创建`LevelPlayRewardedAd`时通过 `Config` 对象进行通道（[此处](/grow/levelplay/sdk/unity/advanced-settings.md#price-floor-configuration)包含更多信息）：

```csharp
// Create Rewarded Ad object with Price Floor in config.
var configBuilder = new LevelPlayRewardedAd.Config.Builder();
configBuilder.SetBidFloor(1.0); // 最低出价（美元）
var rvConfig = configBuilder.Build();

LevelPlayRewardedAd RewardedAd = new LevelPlayRewardedAd(RewardedAdUnitId, rvConfig);
```

## 注册到奖励事件##register-to-rewarded-events

在代码中实现 **LevelPlayRewardedAdListener** 以获取广告投放信息。

* 建议在加载奖励广告之前设置监听器。
* 每个奖励广告都应有自己的监听器实现。
* 回调在主线程上运行。

```csharp
// Register to Rewarded events
RewardedAd.OnAdLoaded += RewardedOnAdLoadedEvent;
RewardedAd.OnAdLoadFailed += RewardedOnAdLoadFailedEvent;
RewardedAd.OnAdDisplayed += RewardedOnAdDisplayedEvent;
RewardedAd.OnAdDisplayFailed += RewardedOnAdDisplayFailedEvent;
RewardedAd.OnAdRewarded += RewardedOnAdRewardedEvent;
RewardedAd.OnAdClosed += RewardedOnAdClosedEvent;
// Optional
RewardedAd.OnAdClicked += RewardedOnAdClickedEvent;
RewardedAd.OnAdInfoChanged += RewardedOnAdInfoChangedEvent;

// Implement the events
void RewardedOnAdLoadedEvent(LevelPlayAdInfo adInfo) {}
void RewardedOnAdLoadFailedEvent(LevelPlayAdError error) {}
void RewardedOnAdDisplayedEvent(LevelPlayAdInfo adInfo) {}
void RewardedOnAdDisplayFailedEvent(LevelPlayAdInfo adInfo, LevelPlayAdError error) {}
void RewardedOnAdRewardedEvent(LevelPlayAdInfo adInfo, LevelPlayReward adReward) {}
void RewardedOnAdClosedEvent(LevelPlayAdInfo adInfo) {}
void RewardedOnAdClickedEvent(LevelPlayAdInfo adInfo) {}
void RewardedOnAdInfoChangedEvent(LevelPlayAdInfo adInfo) {}
```

### LevelPlay 广告信息##levelplay-ad-info

**LevelPlayAdInfo** 参数包含有关加载的广告的信息。

在[此处](/grow/levelplay/sdk/unity/levelplay-listener-adinfo-integration.md)了解有关其实现和可用字段的更多信息。

## 获取奖励广告详细信息##get-rewarded-ad-details

使用 getReward API 可以访问您在 LevelPlay 后台中设置的奖励数据。与其他聚合 API 不同，这是一个独立调用，在初始化后返回存储在 SDK 本地的数据。这使您能够构建动态、数据驱动的 UI，在用户参与广告之前告知他们潜在的奖励，从而无需在app中硬编码奖励值。

### 先决条件##prerequisites

在实现 getReward API 之前，请确保项目满足以下技术要求：

* **SDK 初始化**：调用 initSDK 并等待 onInitializationSuccess 回调以确保奖励数据已缓存。
* **广告对象实例**：在调用 API 之前，使用有效的 Ad Unit ID 实例化奖励广告对象。
* **最低 SDK 版本**：使用 LevelPlay SDK 8.1.0 或更高版本（原生或 Unity 软件包）。

### 最佳实践##best-practices

遵循这些建议可确保稳定且可预测的集成。

* **初始化成功时调用**：调用 getReward 的最佳时间是初始化成功监听器器内部。这样可以确保 UI 在用户进入屏幕时就绪。
* **检查空状态**：在更新 UI 之前，请始终验证该数量> 0。如果在初始化期间发生网络报错，这将确保平滑的用户体验。
* **放置/位置精度**：确保在 getReward("placementName") 中使用的字符串与 LevelPlay 后台中定义的名称完全匹配。

### API 结构##api-structure

getReward 方法允许您从 LevelPlay 后台访问同步的奖励数据。使用此方法可以查询本地 SDK 缓存中指定的广告放置/位置或全局广告单元默认值。

#### getReward##getreward

```csharp
public LevelPlayReward getReward(String placementName)
```

获取指定的广告放置/位置或默认广告单元的奖励名称和金额。没有其他参数可以使用。

| 参数            | 描述                                                    |
| ------------- | ----------------------------------------------------- |
| placementName | 在 LevelPlay 后台中定义的放置/位置的唯一标识符。通道`null`，用于获取广告单元的默认奖励。 |

返回一个 LevelPlayReward 对象，其中包含名称（字符串）和金额（int）。

### 初始设置##initial-setup

getReward API 充当 LevelPlay SDK 的核心组件，在如下逻辑下运行以确保数据无延迟可用：

* **集成功能**：由于奖励数据是在初始 SDK 设置期间获取的，因此 API 调用是即时的，不需要网络请求。
* **编辑器配置**：将 app 与 LevelPlay SDK 集成后，API 可以立即使用。测试此功能不需要额外的资源或插件。

### 了解奖励选择逻辑##understand-reward-selection-logic

API 根据指定的层级视图返回 LevelPlayReward 对象。了解此逻辑有助于排除出现指定的奖励的原因。

* **放置/位置级别**：如果在调用中提供了有效的广告放置/位置称，SDK 将返回控制面板中为该广告位放置/位置的指定的奖励。
* **广告单元级别**：如果广告放置/位置名称为 null 或未找到，SDK 将回退到为广告单元定义的默认奖励。
* **回退状态**：如果在初始化完成之前调用 API，则返回一个字符串名称为空且值为 0 的奖励对象。

### 动态更新 UI##update-your-ui-dynamically

使用 getReward API 可将静态按钮变换为高意图的行动调用。例如：您可以显示“Watch to earn 50 Gold”，而不是通用的“Watch Video”按钮。

* **有效金额**：在更新 UI 组件之前，请务必验证 reward.amount > 0。
* **事件驱动更新**：在初始化成功监听器器中调用 API 以确保 UI 在用户进入屏幕时准确无误。
* **区分大小写**：确保代码中的放置/位置名称字符串与 LevelPlay 后台完全匹配；不匹配的字符串将触发器广告单元回退。

### 获取奖励数据示例##retrieve-reward-data-examples

以下示例展示了如何调用 Unity 的奖励 API：

```csharp
/// <summary> 
/// Retrieves the reward associated with the ad.
/// Use this method to obtain the reward configured for the ad unit or placement.The 
/// placement-specific reward takes precedence over the ad unit reward when a valid placement name 
/// is provided.
/// </summary> 
/// <param name="placement">The placement name to retrieve the reward for, or null to use the ad unit's reward.</param> 
/// <returns>A <see cref="LevelPlayReward"/> object.失败时返回空奖励（名称： "" 和金额：0).</returns> 
LevelPlayReward reward = rewardedAd.getReward("battle_screen");

// Update UI dynamically
if (reward.Amount > 0 && !string.IsNullOrEmpty(reward.Name)) {
    rewardButton.text = $"Click to get {reward.Amount} {reward.Name}";
} else {
    rewardButton.text = "Watch for Rewards";
}
```

### getReward API 实现故障排除##troubleshooting-getreward-api-implementation

* **奖励金额返回 0**：如果在 onInitializationSuccess 回调之前调用 API，通常会发生这种情况。在查询奖励之前，请确保 SDK 完全准备就绪。
* **显示错误奖励类型**：检查是否有多个广告位。如果放置/位置名称拼写错误，SDK 默认认为主广告单元奖励，而不是指定的广告放置/位置奖励。

## 加载奖励广告##load-rewarded-ad

要加载奖励广告，请使用 **LoadAd**。

```csharp
// Load rewarded ad
RewardedAd.LoadAd();
```

## 显示奖励广告##show-rewarded-ad

使用 **LevelPlayRewardedAdListener** API 收到 **OnAdLoaded** 回调后显示奖励广告。

* 如果使用放置，请在 **ShowAd** API 中通道放置/位置名称，如下文 Placements 部分所示。
* 广告已成功向用户显示后，可以通过重复加载步骤加载另一个广告。

```csharp
// Show ad without placement
RewardedAd.ShowAd();
// Show ad with placement
RewardedAd.ShowAd(placementName: "placementName");
```

### 检查 Ad is Ready##check-ad-is-ready

为了避免展示失败，并确保广告可以正确展示，建议在调用 **ShowAd** API 之前使用以下 API。

**IsAdReady** – 如果广告已成功加载并且广告单元未设置上限，则返回 true，否则返回 false。

**IsPlacementCapped** – 有效放置/位置被限制时返回 true。如果放置/位置无效或未设置上限，此 API 将返回 false。

```csharp
// Check that ad is ready and that the placement is not capped
if (RewardedAd.IsAdReady() && !LevelPlayRewardedAd.IsPlacementCapped(placementName))
{
    RewardedAd.ShowAd(placementName);
}
```

### 广告位##placements

我们支持 LevelPlay 后台上奖励广告的[广告位](/grow/levelplay/platform/settings/placements.md)节奏和封顶。

如果为奖励广告服务设置了放置位置，请调用 **ShowAd** 方法为指定的放置/位置提供广告。

```csharp
// Check that ad is ready and that the placement is not capped
if (RewardedAd.IsAdReady() && !LevelPlayRewardedAd.IsPlacementCapped(placementName))
{
    RewardedAd.ShowAd(placementName);
}
```

### 动态 UserId##dynamic-userid

动态 UserID 是一个参数，用于验证可在整个会话中更改的 AdRewarded 交易。您将通过[服务器到服务器](/grow/levelplay/platform/settings/server-to-server-callback.md)的广告奖励回调收到此参数，必须在调用 ShowAd 之前设置此参数。

* 字字符串必须包含 1-64 个字母数字角色。
* 您将在回调网址中收到一个 `dynamicUserId` 参数以及奖励详细信息。

```csharp
LevelPlay.SetDynamicUserId("userId");
```

## 奖励用户##reward-the-user

LevelPlay SDK 将在用户每次成功完成视频时触发 **OnAdRewarded**。

**OnAdRewarded** 和 **OnAdClosed** 是异步的。确保设置监听器以提供奖励，即使 **OnAdRewarded** 在 **OnAdClosed** 之后被触发也是如此。

```csharp
// Subscribe to the OnAdRewarded event
RewardedAd.OnAdRewarded += (adInfo, adReward) =>
{
    // Grant the reward to the user
    Debug.Log($"Ad Completed: {adInfo.PlacementName}, Reward: {adReward.Name} - {adReward.Amount}");
    GrantReward(adReward.Name, adReward.Amount);
};
// Example method to process the reward
private void GrantReward(string rewardName, int rewardAmount)
{
    // TODO:实现向用户授予奖励的逻辑
    Debug.Log($"Granting reward: {rewardName} with amount: {rewardAmount}");
}
```

## 奖励广告服务的完整实现示例##full-implementation-example-of-rewarded-ads

```csharp
public class RewardedAdSample {
    private LevelPlayRewardedAd RewardedAd;
    void CreateRewardedAd() {
        // Create RewardedAd instance
        RewardedAd = new LevelPlayRewardedAd("RewardedAdUnitId");

        // Subscribe RewardedAd events
        RewardedAd.OnAdLoaded += RewardedOnAdLoadedEvent;
        RewardedAd.OnAdLoadFailed += RewardedOnAdLoadFailedEvent;
        RewardedAd.OnAdDisplayed += RewardedOnAdDisplayedEvent;
        RewardedAd.OnAdDisplayFailed += RewardedOnAdDisplayFailedEvent;
        RewardedAd.OnAdClicked += RewardedOnAdClickedEvent;
        RewardedAd.OnAdClosed += RewardedOnAdClosedEvent;
        RewardedAd.OnAdRewarded += RewardedOnAdRewardedEvent;
        RewardedAd.OnAdInfoChanged += RewardedOnAdInfoChangedEvent;
    }
    void LoadRewardedAd() {
        // Load or reload RewardedAd
        RewardedAd.LoadAd();
    }
    void ShowRewardedAd() {
        // Show RewardedAd, check if the ad is ready before showing
        if (RewardedAd.IsAdReady()) {
            RewardedAd.ShowAd();
        }
    }
    // Implement RewardedAd events
    void RewardedOnAdLoadedEvent(LevelPlayAdInfo adInfo) { }
    void RewardedOnAdLoadFailedEvent(LevelPlayAdError error) { }
    void RewardedOnAdClickedEvent(LevelPlayAdInfo adInfo) { }
    void RewardedOnAdDisplayedEvent(LevelPlayAdInfo adInfo) { }
    void RewardedOnAdDisplayFailedEvent(LevelPlayAdInfo adInfo, LevelPlayAdError error) { }
    void RewardedOnAdClosedEvent(LevelPlayAdInfo adInfo) { }
    void RewardedOnAdRewardedEvent(LevelPlayAdInfo adInfo, LevelPlayReward adReward) { }
    void RewardedOnAdInfoChangedEvent(LevelPlayAdInfo adInfo) { }
}
```

## LevelPlay Mediation 演示应用程序##levelplay-mediation-demo-app

Integration Demo 应用程序演示如何在 app 中集成奖励广告单元 API。

[下载 Unity Demo 应用程序](https://github.com/ironsource-mobile/Mediation-Demo-Apps)

验证您与我们的[集成测试套件](/grow/levelplay/sdk/unity/integration-test-suite.md)的集成。

## 后续步骤##next-steps

请遵循我们的集成指南来集成其他奖励广告网络或配置其他广告格式：

* [添加聚合网络](/grow/levelplay/sdk/unity/mediation-networks.md)
* [插页式广告](/grow/levelplay/sdk/unity/interstitial-integration.md)
* [横幅广告服务](/grow/levelplay/sdk/unity/banner-integration.md)