> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.
# インタースティシャル広告
> React Nativeアプリでインタースティシャル広告を実装する方法をご案内します。
## 概要
インタースティシャル広告（Interstitial Ad）はアプリの画面全体を覆う形式で表示される広告です。ゲームのレベル切り替え、コンテンツページ切り替えなど、アプリの自然な遷移タイミングで表示するのに適しています。
### 特徴
* 全画面を覆う没入型広告
* ユーザーが明示的に閉じるまで維持
* 画像および動画広告対応
* 高い視覚的注目度
開発環境ではテストユニットIDを使用してください：`PUBLIC_TEST_UNIT_ID_INTERSTITIAL`
***
## 実装方式
Adrop React Native SDKはインタースティシャル広告を実装する2つの方式を提供します：
1. **クラス方式** - AdropInterstitialAdクラスを直接使用
2. **Hook方式** - useAdropInterstitialAd Hookを使用（推奨）
***
## AdropInterstitialAdクラス
### コンストラクタ
AdropInterstitialAdインスタンスを生成します。
```typescript theme={null}
import { AdropInterstitialAd } from 'adrop-ads-react-native'
const interstitialAd = new AdropInterstitialAd(unitId)
```
広告ユニットID（コンソールで発行）
### プロパティ
広告がロードされているかどうかを返します。
```typescript theme={null}
if (interstitialAd.isLoaded) {
// 広告表示可能
}
```
広告ユニットIDを返します。
```typescript theme={null}
const unitId = interstitialAd.unitId
```
現在ロードされた広告のクリエイティブIDを返します。
```typescript theme={null}
const creativeId = interstitialAd.creativeId
```
現在ロードされた広告のトランザクションIDを返します。
```typescript theme={null}
const txId = interstitialAd.txId
```
現在ロードされた広告のキャンペーンIDを返します。
```typescript theme={null}
const campaignId = interstitialAd.campaignId
```
現在ロードされた広告のリンク先URLを返します。
```typescript theme={null}
const destinationURL = interstitialAd.destinationURL
```
現在ロードされた広告のブラウザターゲット設定を返します（`BrowserTarget.EXTERNAL`または`BrowserTarget.INTERNAL`）。
```typescript theme={null}
const browserTarget = interstitialAd.browserTarget
```
広告イベントを受信するリスナーを設定します。
```typescript theme={null}
interstitialAd.listener = {
onAdReceived: (ad) => console.log('広告受信'),
onAdFailedToReceive: (ad, errorCode) => console.log('受信失敗', errorCode),
// ... その他のコールバック
}
```
### メソッド
広告をリクエストしてロードします。
```typescript theme={null}
interstitialAd.load()
```
ロードされた広告を表示します。`isLoaded`が`true`のときに呼び出す必要があります。
```typescript theme={null}
if (interstitialAd.isLoaded) {
interstitialAd.show()
}
```
現在表示中の広告を閉じます。Androidで戻るボタンの処理時に便利です。
```typescript theme={null}
interstitialAd.close()
```
広告インスタンスを破棄してリソースを解放します。コンポーネントアンマウント時に必ず呼び出す必要があります。
```typescript theme={null}
useEffect(() => {
return () => {
interstitialAd?.destroy()
}
}, [interstitialAd])
```
***
## AdropListenerインターフェース
広告イベントを受信するためのコールバックインターフェースです。
### 推奨コールバック
広告受信成功時に呼び出されます。この時点で`show()`を呼び出して広告を表示できます。
```typescript theme={null}
onAdReceived: (ad) => {
console.log('広告受信完了:', ad.unitId)
// 広告表示準備完了
}
```
広告受信失敗時に呼び出されます。エラーコードで失敗原因を確認できます。
```typescript theme={null}
onAdFailedToReceive: (ad, errorCode) => {
console.log('広告受信失敗:', errorCode)
}
```
### オプションコールバック
広告インプレッションが記録されたときに呼び出されます。
```typescript theme={null}
onAdImpression: (ad) => {
console.log('広告インプレッション記録')
}
```
ユーザーが広告をクリックしたときに呼び出されます。
```typescript theme={null}
onAdClicked: (ad) => {
console.log('広告クリック')
}
```
全画面広告が表示される直前に呼び出されます。ゲーム一時停止などの処理を実行できます。
```typescript theme={null}
onAdWillPresentFullScreen: (ad) => {
console.log('広告表示直前')
// ゲーム一時停止、音楽停止など
}
```
全画面広告が画面に表示された直後に呼び出されます。
```typescript theme={null}
onAdDidPresentFullScreen: (ad) => {
console.log('広告表示完了')
}
```
全画面広告が閉じられる直前に呼び出されます。
```typescript theme={null}
onAdWillDismissFullScreen: (ad) => {
console.log('広告閉じる直前')
}
```
全画面広告が閉じられた直後に呼び出されます。次の広告を事前ロードするのに適したタイミングです。
```typescript theme={null}
onAdDidDismissFullScreen: (ad) => {
console.log('広告閉じる')
// ゲーム再開、次の広告ロードなど
}
```
広告表示失敗時に呼び出されます。エラーコードで失敗原因を確認できます。
```typescript theme={null}
onAdFailedToShowFullScreen: (ad, errorCode) => {
console.log('広告表示失敗:', errorCode)
}
```
広告表示中にユーザーが戻るボタンを押したときに呼び出されます。**Androidのみ。**
```typescript theme={null}
onAdBackButtonPressed: (ad) => {
console.log('戻るボタン押下')
}
```
***
## クラス方式実装例
AdropInterstitialAdクラスを直接使用する方式です。
```typescript theme={null}
import React, { useCallback, useEffect, useMemo, useState } from 'react'
import { Button, StyleSheet, Text, View } from 'react-native'
import { AdropInterstitialAd, type AdropListener } from 'adrop-ads-react-native'
const InterstitialAdScreen: React.FC = () => {
const [interstitialAd, setInterstitialAd] = useState()
const [isLoaded, setIsLoaded] = useState(false)
const [errorCode, setErrorCode] = useState('')
// 広告イベントリスナー設定
const listener: AdropListener = useMemo(() => ({
onAdReceived: (ad) => {
console.log('インタースティシャル広告受信完了:', ad.unitId)
setIsLoaded(true)
setErrorCode('')
},
onAdFailedToReceive: (ad, error) => {
console.log('インタースティシャル広告受信失敗:', error)
setErrorCode(error || 'Unknown error')
setIsLoaded(false)
},
onAdClicked: (ad) => {
console.log('インタースティシャル広告クリック')
},
onAdImpression: (ad) => {
console.log('インタースティシャル広告表示')
},
onAdWillPresentFullScreen: (ad) => {
console.log('インタースティシャル広告表示直前')
// ゲーム一時停止、音楽停止など
},
onAdDidPresentFullScreen: (ad) => {
console.log('インタースティシャル広告表示完了')
},
onAdWillDismissFullScreen: (ad) => {
console.log('インタースティシャル広告閉じる直前')
},
onAdDidDismissFullScreen: (ad) => {
console.log('インタースティシャル広告閉じる')
setIsLoaded(false)
// ゲーム再開、次の広告事前ロードなど
},
onAdFailedToShowFullScreen: (ad, error) => {
console.log('インタースティシャル広告表示失敗:', error)
setErrorCode(error || 'Unknown error')
setIsLoaded(false)
},
onAdBackButtonPressed: (ad) => {
console.log('戻るボタン押下')
ad.close() // 戻るボタンで広告を閉じる（Androidのみ）
},
}), [])
// 広告インスタンス初期化
useEffect(() => {
const ad = new AdropInterstitialAd('YOUR_UNIT_ID')
ad.listener = listener
setInterstitialAd(ad)
// コンポーネントアンマウント時にクリーンアップ
return () => {
ad.destroy()
}
}, [listener])
// 広告ロード
const loadAd = useCallback(() => {
interstitialAd?.load()
}, [interstitialAd])
// 広告表示
const showAd = useCallback(() => {
if (interstitialAd?.isLoaded) {
interstitialAd.show()
} else {
console.log('広告がまだロードされていません')
}
}, [interstitialAd])
return (
{errorCode && (
エラー: {errorCode}
)}
)
}
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
gap: 16,
},
error: {
color: 'red',
marginTop: 16,
},
})
export default InterstitialAdScreen
```
***
## useAdropInterstitialAd Hook
React Hookを使用してインタースティシャル広告をより簡単に実装できます。
### Hook使用法
```typescript theme={null}
import { useAdropInterstitialAd } from 'adrop-ads-react-native'
const { load, show, reset, isLoaded, isOpened, isClosed, isClicked, errorCode, isReady } =
useAdropInterstitialAd(unitId)
```
広告ユニットID。`null`を渡すと広告が解放されます。
### 戻り値
広告をロードします。`isReady`が`true`のときのみ動作します。
```typescript theme={null}
const handleLoad = () => {
if (isReady) {
load()
}
}
```
ロードされた広告を表示します。
```typescript theme={null}
const handleShow = () => {
if (isLoaded) {
show()
}
}
```
広告状態を初期化して新しいインスタンスを生成します。
```typescript theme={null}
const handleReset = () => {
reset()
}
```
広告インスタンスが準備されているかどうかです。
広告が正常にロードされたかどうかです。
広告が画面に表示されたかどうかです。
広告が閉じられたかどうかです。
広告がクリックされたかどうかです。
広告ロードまたは表示中に発生したエラーコードです。
広告表示中に戻るボタンが押されたかどうかです。**Androidのみ。**
ロードされた広告のブラウザターゲット設定です（`BrowserTarget.EXTERNAL`または`BrowserTarget.INTERNAL`）。
***
## Hook方式実装例
useAdropInterstitialAd Hookを使用する方式です（推奨）。
```typescript theme={null}
import React, { useCallback, useMemo } from 'react'
import { Button, StyleSheet, Text, View } from 'react-native'
import { useAdropInterstitialAd } from 'adrop-ads-react-native'
const InterstitialAdScreen: React.FC = () => {
const unitId = 'YOUR_UNIT_ID'
const {
load,
show,
reset,
isLoaded,
isOpened,
isClosed,
isClicked,
errorCode,
isReady
} = useAdropInterstitialAd(unitId)
// 広告ロード
const handleLoad = useCallback(() => {
if (isReady) {
load()
}
}, [isReady, load])
// 広告表示
const handleShow = useCallback(() => {
if (isLoaded) {
show()
}
}, [isLoaded, show])
// 広告リセット
const handleReset = useCallback(() => {
reset()
}, [reset])
return (
{/* 状態表示 */}
準備完了: {isReady ? 'はい' : 'いいえ'}
ロード済み: {isLoaded ? 'はい' : 'いいえ'}
表示済み: {isOpened ? 'はい' : 'いいえ'}
閉じた: {isClosed ? 'はい' : 'いいえ'}
クリック済み: {isClicked ? 'はい' : 'いいえ'}
{errorCode && (
エラー: {errorCode}
)}
)
}
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
gap: 16,
},
statusContainer: {
marginTop: 24,
padding: 16,
backgroundColor: '#f0f0f0',
borderRadius: 8,
},
error: {
color: 'red',
marginTop: 16,
},
})
export default InterstitialAdScreen
```
***
## テストユニットID
開発およびテスト環境では必ずテストユニットIDを使用してください。
```typescript theme={null}
// テスト用
const TEST_UNIT_ID = 'PUBLIC_TEST_UNIT_ID_INTERSTITIAL'
// 開発/プロダクション環境分離
const unitId = __DEV__
? 'PUBLIC_TEST_UNIT_ID_INTERSTITIAL'
: 'YOUR_PRODUCTION_UNIT_ID'
```
プロダクションビルドでは必ず実際のユニットIDを使用する必要があります。テストユニットIDで発生した収益は精算されません。
***
## エラー処理
広告のロードおよび表示中に発生する可能性のあるエラーを適切に処理する必要があります。
### エラーコード
| エラーコード | 説明 | 対応方法 |
| ---------------------------- | ---------- | ---------------- |
| `AdropErrorCode.network` | ネットワークエラー | ネットワーク接続を確認して再試行 |
| `AdropErrorCode.internal` | 内部エラー | 再試行またはサポートに問い合わせ |
| `AdropErrorCode.initialize` | SDK初期化失敗 | SDK初期化コードを確認 |
| `AdropErrorCode.invalidUnit` | 無効なユニットID | ユニットIDを確認 |
| `AdropErrorCode.adNoFill` | 広告インベントリ不足 | 正常、後で再試行 |
| `AdropErrorCode.adLoading` | 既にロード中 | ロード完了後に再試行 |
| `AdropErrorCode.adEmpty` | ロード済み広告なし | 広告ロード後に表示 |
| `AdropErrorCode.adShown` | 既に表示された広告 | 新しい広告のロードが必要 |
### エラー処理例
```typescript theme={null}
const { load, show, errorCode, isLoaded } = useAdropInterstitialAd(unitId)
useEffect(() => {
if (errorCode) {
switch (errorCode) {
case AdropErrorCode.network:
console.log('ネットワークエラー: 接続を確認してください')
// 30秒後に再試行
setTimeout(() => load(), 30000)
break
case AdropErrorCode.adNoFill:
console.log('表示可能な広告がありません')
// 広告なしで続行
break
case AdropErrorCode.invalidUnit:
console.error('無効なユニットID')
break
default:
console.log('広告エラー:', errorCode)
break
}
}
}, [errorCode, load])
```
***
## ベストプラクティス
### 1. 適切な表示タイミング
アプリの自然な遷移タイミングで広告を表示してください。
```typescript theme={null}
// ✅ 良い例: ゲームレベル遷移
const handleLevelComplete = () => {
saveProgress()
if (isLoaded) {
show() // 自然な遷移タイミング
}
navigateToNextLevel()
}
// ✅ 良い例: コンテンツ読了後
const handleArticleFinished = () => {
if (isLoaded) {
show()
}
}
// ❌ 悪い例: ユーザーアクション中
const handleButtonClick = () => {
show() // ユーザー体験を阻害
performAction()
}
```
### 2. 事前ロード
広告を事前にロードしてユーザーの待ち時間を最小限にしてください。
```typescript theme={null}
const InterstitialAdScreen: React.FC = () => {
const { load, show, isLoaded, isClosed } = useAdropInterstitialAd(unitId)
// コンポーネントマウント時に広告を事前ロード
useEffect(() => {
load()
}, [load])
// 広告が閉じた後に次の広告を事前ロード
useEffect(() => {
if (isClosed) {
load()
}
}, [isClosed, load])
return (
// ...
)
}
```
### 3. 頻度制限
広告の表示頻度を制限してください。
```typescript theme={null}
const InterstitialAdScreen: React.FC = () => {
const { show, isLoaded } = useAdropInterstitialAd(unitId)
const [lastShownTime, setLastShownTime] = useState(0)
const MIN_INTERVAL = 3 * 60 * 1000 // 3分
const showAdWithFrequencyLimit = useCallback(() => {
const now = Date.now()
if (now - lastShownTime < MIN_INTERVAL) {
console.log('広告表示間隔が短すぎます')
return
}
if (isLoaded) {
show()
setLastShownTime(now)
}
}, [isLoaded, show, lastShownTime])
return (
// ...
)
}
```
### 4. ゲーム一時停止処理
クラス方式でリスナーを使用してゲーム状態を管理してください。
```typescript theme={null}
const listener: AdropListener = useMemo(() => ({
onAdWillPresentFullScreen: (ad) => {
// ゲーム一時停止
pauseGame()
pauseBackgroundMusic()
},
onAdDidDismissFullScreen: (ad) => {
// ゲーム再開
resumeGame()
resumeBackgroundMusic()
},
}), [])
```
### 5. メモリ管理
コンポーネントアンマウント時に必ずリソースを解放してください。
```typescript theme={null}
// Hook方式 - 自動管理
const { load, show } = useAdropInterstitialAd(unitId)
// クラス方式 - 手動クリーンアップが必要
useEffect(() => {
const ad = new AdropInterstitialAd(unitId)
setInterstitialAd(ad)
return () => {
ad.destroy() // 必須！
}
}, [unitId])
```
***
## プラットフォーム別の考慮事項
### iOS
* iOSではアプリがバックグラウンドに移行する際、広告は自動的に閉じられます
* `onAdDidDismissFullScreen`コールバックが呼び出されます
### Android
* Androidの戻るボタンで広告を閉じることができます
* ハードウェアアクセラレーションが必要な場合があります
***
## バックフィル広告
バックフィル広告を使用するには、ネイティブプラットフォーム(Android/iOS)にバックフィル依存関係が追加されている必要があります。
バックフィル広告が有効な場合、直接広告が利用できないときにSDKが自動的にバックフィル広告にフォールバックします。リスナーでバックフィル関連のエラーコードを処理できます。
```tsx theme={null}
interstitialAd.listener = {
onAdReceived: (ad) => {
console.log('広告ロード完了:', ad.creativeId)
},
onAdFailedToReceive: (ad, errorCode) => {
switch (errorCode) {
case AdropErrorCode.adNoFill:
console.log('直接広告なし、バックフィル広告をリクエスト中...')
break
case AdropErrorCode.backfillNoFill:
console.log('バックフィル広告もありません')
break
default:
console.log('広告ロード失敗:', errorCode)
}
},
}
```
***
## 次のステップ
リワード広告でユーザーエンゲージメント向上
バナー広告を実装する
ネイティブ広告で自然な広告体験を提供
ポップアップ広告を実装する