# Unityパッケージのリワード広告インテグレーション

> SDKの初期化、初期化後の広告オブジェクトの作成、広告イベントをハンドルするリスナーの実装によって動画リワード広告単位を統合し、アプリ内報酬を通じてユーザーエンゲージメントを強化します。

Unity LevelPlayリワード型広告は、ユーザーが開始する広告単位です。アプリケーション内でのゲーム内報酬と引き換えに全画面の広告を表示する機会をユーザーに提供し、ポジティブなユーザー エクスペリエンスを維持しながらエンゲージメントを強化します。

> **Note:**
>
> このドキュメントは SDK 8.5.0 以降に関連するものです。

## 前提条件##prerequisites

* LevelPlay Unity パッケージがアプリケーションに正しく統合されていることを確認します。インテグレーションの概要は[こちら](/grow/levelplay/sdk/unity/package-integration.md)です。
* LevelPlay 初期化 API を使用して SDK を初期化していることを確認します。
* LevelPlay ダッシュボードで AdUnitID を見つけます。

## Rewarded Adオブジェクトの作成##create-rewarded-ad-object

リワード広告オブジェクトの作成は、**OnInitSuccess** コールバックを受信した後に実行する必要があります。

オブジェクトは、セッションを通じて複数のロードと表示をハンドルできる再利用可能なインスタンスです。作成後、同じ広告単位の広告をロードおよび表示するために使用します。

より高度な実装では、必要に応じて複数のリワード広告オブジェクトを作成できます。

広告オブジェクトを作成するには、以下を呼び出します。

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

> **Note:**
>
> `LevelPlayRewardedAd` コンストラクターは、任意の `Config` パラメーターもサポートします。
>
> ```csharp
> // 任意設定パラメーターを使用
> 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); // Minimum bid price in USD
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 をビルドできるため、アプリケーション内で報酬値をハードコードする必要がなくなります。

### 前提条件##prerequisites

getReward API を実装する前に、プロジェクトが以下の技術要件を満たしていることを確認してください。

* **SDK 初期化**：initSDK を呼び出し、onInitializationSuccess コールバックが報酬データがキャッシュされていることを確認します。
* **広告オブジェクトインスタンス**：API を呼び出す前に、有効な広告単位 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`を渡して、広告単位のデフォルトの報酬を取得します。 |

名前 (文字列) と金額 (int) を含む LevelPlayReward オブジェクトを返します。

### 初期設定##initial-setup

getReward API は、LevelPlay SDK のコア コンポーネントとして機能し、以下のロジックで動作して待ち時間なしでデータを利用できるようにします。

* **統合特徴**:報酬データはSDKの初期設定中に取得されるため、API呼び出しは瞬時に行われ、ネットワークリクエストを必要としません。
* **エディター設定**:アプリケーションを LevelPlay SDK と統合すると、API はすぐに使用できます。この機能をテストするために追加のアセットやプラグインは必要ありません。

### 報酬選択ロジックについて##understand-reward-selection-logic

API は、特定の階層に基づく LevelPlayReward オブジェクトを返します。このロジックを理解することで、特定の報酬が表示される理由のトラブルシューティングに役立ちます。

* **配置レベル**:呼び出しで有効な配置名が指定されている場合、SDKはダッシュボードでその配置に設定された特定の報酬を返します。
* **広告単位レベル**：配置名が null の場合、または見つからない場合は、SDK は広告単位に定義されたデフォルトの報酬にフォールバックします。
* **フォールバック状態**:初期化が完了する前に API が呼び出された場合は、空の文字列列名と金額 0 の報酬オブジェクトが返されます。

### UIの動的更新##update-your-ui-dynamically

getReward API を使用して、静的ボタンを意図的なアクション喚起に Transform します。例えば、ジェネリックのWatch Videoボタンの代わりに、Watch to Earned 50 Goldとディスプレイできます。

* **検証量**:UI コンポーネントを更新する前に、reward.amount が 0 を超えていることを常に確認してください。
* **イベント主導型更新**:初期化成功リスナー内で API を呼び出して、ユーザーが画面に入った瞬間に UI が正確であることを確認します。
* 大文字と小文字の**区別**:コード内の配置名の文字文字列が LevelPlay ダッシュボードと正確に一致していることを確認します。文字列が一致しないと、広告単位のフォールフォールバックがトリガーされます。

### 報酬データ例の取得##retrieve-reward-data-examples

以下の例は、Reward API for Unity の呼び出し方法を示しています。

```csharp
/// <summary> 
/// Retrieves the reward associated with the ad.
/// Use this method to obtain the reward configured for the ad unit or placement.ザ 
/// 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.失敗した場合、空の報酬を返します (name: "" と amount:0).</returns> 
LevelPlayReward reward = rewardedAd.getReward("battle_screen");

// Update UI dynamically
if (reward.Amount > 0 && !string.IsNullOrEmpty(reward.Name)) {
    rewardButton.text = $"クリックして {reward.Amount} を取得 {reward.Name}";
} else {
    rewardButton.text = "Watch for Rewards";
}
```

### getReward API 実装のトラブルシューティング##troubleshooting-getreward-api-implementation

* **Reward amount は 0 を返し**ます。これは通常、onInitializationSuccess コールバックの前に API が呼び出された場合に発生します。ゲーム内報酬のクエリを実行する前に、SDKの準備が完全にできていることを確認します。
* **間違った報酬タイプ**:複数のプレースメントがあるかどうかを確認します。配置名のスペルに誤りがある場合、SDKはデフォルトで特定の配置報酬ではなくプライマリ広告単位の報酬を使用します。

## リワード型広告のロード##load-rewarded-ad

リワード広告をロードするには、**LoadAd** を使用します。

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

## リワード広告の表示##show-rewarded-ad

**LevelPlayRewardedAdListener** API を使用し**て OnAdLoaded** コールバックを受け取った後にリワード広告を表示します。

* プレースメントを使用している場合は、後述のプレースメントのセクションで示すように、**ShowAd** APIで配置名を渡します。
* 広告がユーザーに正常に表示されたら、ロードステップを繰り返して別の広告をロードできます。

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

### 広告の準備ができているか確認##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##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);
}
```

### Dynamic UserId##dynamic-userid

動的ユーザー ID は、AdRewarded トランザクションを検証するために使用されるパラメーターで、セッションを通じて変更できます。このパラメーターは、[サーバー間](/grow/levelplay/platform/settings/server-to-server-callback.md)の広告リワード型コールバックを通じて受け取ります。ShowAd を呼び出す前に設定する必要があります。

* 文字列 値は 1 \~ 64 文字の英数字でなければなりません。
* コールバックURLで報酬の詳細とともに`dynamicUserId`パラメーターを受け取ります。

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

## ユーザーの報酬##reward-the-user

LevelPlay SDK は、ユーザーがビデオを正常に視聴するたびに **OnAdRewarded** を起動します。

**OnAdRewarded** と **OnAdClosed** は非同期です。**OnAdClosed** 後に **OnAdRewarded** が起動された場合でもゲーム内報酬を付与するようにリスナーを設定してください。

```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(文字列 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

インテグレーション Demo (インテグレーションデモ) アプリケーションでは、リワード型広告単位 API をアプリケーションに統合する方法を示します。

[Unityデモ アプリケーションのダウンロード](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)