# Reactネイティブ向けリワード広告インテグレーション

> SDK の初期化、広告ユニットの作成、広告ライフサイクルイベントをハンドルするイベントリスナーの設定によって、動画リワード広告を React ネイティブ アプリケーションに統合します。

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

## 前提条件##prerequisites

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

## リワード型の作成とイベントへの登録##create-rewarded-and-register-to-events

**onInitSuccess** コールバックを受信した後で、LevelPlay プラットフォームで定義されているように、関連する広告単位 ID を使用して広告単位を作成できます（LevelPlay SDK ステップの初期化）。

作成したリワード型広告単位にリワード型リスナーを設定して、広告配信に関する情報を取得します。

```js
import {
    LevelPlayRewardedAd,
    type LevelPlayRewardedAdListener,
    type LevelPlayAdInfo,
    type LevelPlayAdError,
    type LevelPlayReward
} 'unity-levelplay-mediation' から

const [rewardedAd, setRewardedAd] = useState<LevelPlayRewardedAd>(new LevelPlayRewardedAd('YOUR_AD_UNIT_ID'))
useEffect(() => {
    const listener:LevelPlayRewardedAdListener = {
        onAdLoaded: (adInfo:LevelPlayAdInfo) => {
            // Provided when the ad is successfully loaded
        },
        onAdLoadFailed: (error:LevelPlayAdError) => {
            // Provided when the ad fails to load.広告単位情報が含まれている
        },
        onAdInfoChanged: (adInfo:LevelPlayAdInfo) => {
            // Provided when the ad info is updated.別の広告がロードされ、CPM/レートが高い場合に利用可能
        },
        onAdDisplayed: (adInfo:LevelPlayAdInfo) => {
            // Provided when the ad is displayed
        },
        onAdDisplayFailed: (error:LevelPlayAdError、adInfo：LevelPlayAdInfo) => {
            // Provided when the ad fails to be displayed
        },
        onAdClicked: (adInfo:LevelPlayAdInfo) => {
            // Provided when the user clicks on the ad
        },
        onAdClosed: (adInfo:LevelPlayAdInfo) => {
            // Provided when the ad is closed
        },
        onAdRewarded: (reward:LevelPlayReward, adInfo:LevelPlayAdInfo) => {
            // Provided when the ad is rewarded.広告単位情報と報酬情報が含まれます。
        }
    };
    rewardedAd.setListener(listener);
}, [rewardedAd]);
```

### LevelPlay リワード広告コールバック##levelplay-rewarded-ad-callbacks

**onAdLoaded** – 広告が正常にロードされたときに提供されます。

**onAdLoadFailed** – 広告のロードに失敗したときに提供されます。広告単位情報が含まれている

**onAdDisplayed** – 広告が表示されるときに提供されます。これはインプレッションに相当します

**onAdDisplayFailed**（任意） – 広告の表示に失敗したときに提供されます。

**onAdRewarded** – 広告に報酬が支払われるときに提供されます。広告単位情報と報酬情報が含まれます。

**onAdClicked**（任意）：ユーザーが広告をクリックしたときに提供されます。

**onAdClosed** – 広告が閉じられたときに提供されます。

**onAdInfoChanged** （任意） – 広告情報が更新されたときに提供されます。別の広告がロードされ、CPM/レートが高い場合に利用可能

## リワード広告の詳細を取得する##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

特定の配置またはデフォルトの広告単位の報酬の名前と金額を取得します。その他に使用するパラメーターはありません。

| パラメーター        | 説明                                                                  |
| ------------- | ------------------------------------------------------------------- |
| 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 ダッシュボードと正確に一致していることを確認します。文字列が一致しないと、広告単位のフォールフォールバックがトリガーされます。

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

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

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

**onInitSuccess** コールバックを受信したら、リワード広告をロードする準備ができます。これは、 メソッドを使用して行う必要があります。

```js
rewardedAd.loadAd();
```

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

showAd API を使用して、onAdLoaded コールバックの受信後にリワード広告を表示できます。

[プレースメント](/grow/levelplay/platform/settings/placements.md)を使用している場合は、次に示すように、プレースメントの名前を API の一部として共有します。

```js
// Show ad without placement
rewardedAd.showAd();
// Show ad with placement
rewardedAd.showAd('YOUR_PLACEMENT');
```

### 広告の準備ができていることを確認##check-ad-ready

表示の失敗を避け、広告が正しく表示されるようにするために、showAd() API を呼び出す前に以下の API を使用することをお勧めします。

**isAdReady** – 広告のロードが成功し、広告単位に上限が設定されていない場合は true、それ以外の場合は false に解決する Promise を返します。

**isPlacementCapped** – 有効な配置に上限がある場合に、Promise の解決を true に返す静的メソッド。配置が有効でないか、上限がない場合、false を返します。

```js
// Check that ad is ready and that the placement is not capped (both APIs are async)
const isReady = await rewardedAd.isAdReady();
const isPlacementCapped = await LevelPlayRewardedAd.isPlacementCapped('YOUR_PLACEMENT');
if (isReady && !isPlacementCapped) {
  await rewardedAd.showAd('YOUR_PLACEMENT');
}
```

広告がプレイヤーに正常に表示されたら、Rewarded Ad のロード ステップを繰り返して、別の広告をロードできます。一度に 1 つの広告をロードするときに、新しい広告エンティティを作成する必要はありません。

### Dynamic UserId##dynamic-userid

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

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

```js
LevelPlay.setDynamicUserId("userId");
```

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

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

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

```js
onAdRewarded: (reward:LevelPlayReward, adInfo:LevelPlayAdInfo) => {
    // Provided when the ad is rewarded.広告単位情報と報酬情報が含まれる
}

```

## 複数の広告単位リワード型API##multiple-ad-unit-rewarded-apis

|     | **古い機能**                       | **広告単位(新規)**        |
| --- | ------------------------------ | ------------------- |
| クラス | IronSource                     | LevelPlayRewardedAd |
| API | loadRewardedVideo              | loadAd              |
|     | showRewardedVideo              | showAd              |
|     | isRewardedVideoPlacementCapped | isPlacementCapped   |
|     | isRewardedVideoAvailable       | isAdReady           |
|     | placement.getRewardName        | reward.name         |
|     | placement.getRewardAmount      | reward.amount       |

## リワード広告の完全な実装例##full-implementation-example-of-rewarded-ad

```js
import {
    LevelPlayRewardedAd,
    type LevelPlayRewardedAdListener,
    type LevelPlayAdInfo,
    type LevelPlayAdError,
    type LevelPlayReward
} 'unity-levelplay-mediation' から

const [rewardedAd, setRewardedAd] = useState<LevelPlayRewardedAd>(new LevelPlayRewardedAd('YOUR_AD_UNIT_ID'))
const listener:LevelPlayRewardedAdListener = {
    onAdLoaded: (adInfo:LevelPlayAdInfo) => {
        // Implement your logic here, for example showing the ad
        rewardedAd.showAd()
    },
    onAdLoadFailed: (error:LevelPlayAdError) => {
        // Implement your logic here...
    },
    onAdInfoChanged: (adInfo:LevelPlayAdInfo) => {
        // Implement your logic here...
    },
    onAdDisplayed: (adInfo:LevelPlayAdInfo) => {
        // Implement your logic here...
    },
    onAdDisplayFailed: (error:LevelPlayAdError、adInfo：LevelPlayAdInfo) => {
        // Implement your logic here...
    },
    onAdClicked: (adInfo:LevelPlayAdInfo) => {
        // Implement your logic here...
    },
    onAdClosed: (adInfo:LevelPlayAdInfo) => {
        // Implement your logic here...
    },
    onAdRewarded: (reward:LevelPlayReward, adInfo:LevelPlayAdInfo) => {
        // Implement your logic here...
    }
};
useEffect(() => {
    rewardedAd.setListener(listener)
    rewardedAd.loadAd()
}, []);
// Rest of component ...
// End of component ...
```

## LevelPlay Mediation デモアプリケーション##levelplay-mediation-demo-app

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

[React ネイティブデモアプリケーションのダウンロード](https://github.com/ironsource-mobile/react-native-SDK/tree/master/example)

[インテグレーションテストスイート](/grow/levelplay/sdk/react/integration-test-suite.md)とのインテグレーションを確認します。

## 次のステップ##next-steps

インテグレーション ガイドに従って、追加のリワード型広告ネットワークを統合したり、追加の広告フォーマットを設定したりできます。

* [メディエーションネットワークの追加](/grow/levelplay/sdk/react/mediation-networks.md)
* [バナー広告](/grow/levelplay/sdk/react/banner-integration.md)
* [インタースティシャル広告](/grow/levelplay/sdk/react/interstitial-integration.md)
* [ネイティブ広告](/grow/levelplay/sdk/react/native-ads-integration.md)