> ## 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アプリでポップアップ広告を実装する方法をご案内します。

## 概要

ポップアップ広告は、特定のタイミングで画面に表示される広告フォーマットです。アプリ起動時、コンテンツ読み込み完了後、特定イベント時などに表示できます。ユーザーは閉じるボタンをタップするか、「今日は表示しない」を選択して閉じることができます。

### 特徴

* 画面の中央または下部に表示されるポップアップ形式
* 画像・動画広告のサポート
* 閉じる、ディム（背景）クリック、「今日は表示しない」オプション
* 背景色、テキスト色などのカスタマイズ可能
* 非侵入的でありながら効果的な広告体験

<Note>
  開発時はテストユニットIDを使用してください。[テストユニットID](#テストユニットid)セクションを参照してください。
</Note>

***

## 実装手順

ポップアップ広告は4つのステップで実装します：

1. **初期化** - AdropPopupAdインスタンスを作成
2. **リスナー設定** - 広告イベントを受け取るリスナーを設定
3. **広告ロード** - 広告をリクエストして受信
4. **広告表示** - 画面に広告を表示

***

## 基本実装

### AdropPopupAdクラス

`AdropPopupAd`はポップアップ広告を管理するメインクラスです。

```typescript theme={null}
import { AdropPopupAd, type AdropPopupAdColors } from 'adrop-ads-react-native';

const popupAd = new AdropPopupAd(
  unitId: string,
  colors?: AdropPopupAdColors,
  useCustomClick?: boolean
);
```

#### コンストラクタパラメータ

<ParamField path="unitId" type="string" required>
  ポップアップ広告ユニットID。広告管理コンソールで作成したユニットIDを使用してください。
</ParamField>

<ParamField path="colors" type="AdropPopupAdColors">
  ポップアップ広告の色をカスタマイズするオプション。

  * `closeTextColor`: 閉じるボタンのテキスト色
  * `hideForTodayTextColor`: 「今日は表示しない」のテキスト色
  * `backgroundColor`: ポップアップの背景（ディム）色
</ParamField>

<ParamField path="useCustomClick" type="boolean" default="false">
  カスタムクリック処理を使用するかどうか。`true`に設定すると、広告クリック時にデフォルトブラウザを開かずに`onAdClicked`コールバックのみが呼び出されます。
</ParamField>

### 基本的な使用方法

```typescript theme={null}
import React, { useEffect, useState, useMemo } from 'react';
import { Button, View } from 'react-native';
import { AdropPopupAd, type AdropListener } from 'adrop-ads-react-native';

const App: React.FC = () => {
  const [popupAd, setPopupAd] = useState<AdropPopupAd>();
  const [isLoaded, setIsLoaded] = useState(false);

  const listener: AdropListener = useMemo(() => ({
    onAdReceived: (ad: AdropPopupAd) => {
      console.log('ポップアップ広告を受信しました');
      setIsLoaded(true);
    },
    onAdFailedToReceive: (_: AdropPopupAd, errorCode: any) => {
      console.log('ポップアップ広告の受信に失敗しました:', errorCode);
    },
    onAdClicked: (ad: AdropPopupAd) => {
      console.log('ポップアップ広告がクリックされました');
      // クリック時にポップアップを閉じる
      ad.close();
    },
  }), []);

  useEffect(() => {
    // 1. ポップアップ広告を作成
    const ad = new AdropPopupAd('YOUR_POPUP_UNIT_ID');
    ad.listener = listener;
    setPopupAd(ad);

    // 2. 広告をロード
    ad.load();

    // アンマウント時にクリーンアップ
    return () => {
      ad.destroy();
    };
  }, [listener]);

  // 3. 広告を表示
  const showAd = () => {
    if (popupAd && isLoaded) {
      popupAd.show();
    }
  };

  return (
    <View>
      <Button
        title="ポップアップ広告を表示"
        onPress={showAd}
        disabled={!isLoaded}
      />
    </View>
  );
};

export default App;
```

***

## AdropListenerインターフェース

ポップアップ広告のイベントを受け取るリスナーインターフェースです。

### 推奨コールバック

<ParamField path="onAdReceived" type="(ad: AdropPopupAd) => void">
  広告の受信に成功した時に呼び出されます。この時点で`show()`を呼び出すことができます。
</ParamField>

<ParamField path="onAdFailedToReceive" type="(ad: AdropPopupAd, errorCode?: any) => void">
  広告の受信に失敗した時に呼び出されます。エラーコードで失敗の理由を確認できます。
</ParamField>

### オプションコールバック

<ParamField path="onAdImpression" type="(ad: AdropPopupAd) => void">
  広告のインプレッションが記録された時に呼び出されます。
</ParamField>

<ParamField path="onAdClicked" type="(ad: AdropPopupAd) => void">
  ユーザーが広告をクリックした時に呼び出されます。このコールバック内で`ad.close()`を呼び出してポップアップを閉じることができます。
</ParamField>

<ParamField path="onAdWillPresentFullScreen" type="(ad: AdropPopupAd) => void">
  ポップアップ広告が表示される直前に呼び出されます。
</ParamField>

<ParamField path="onAdDidPresentFullScreen" type="(ad: AdropPopupAd) => void">
  ポップアップ広告が表示された直後に呼び出されます。
</ParamField>

<ParamField path="onAdWillDismissFullScreen" type="(ad: AdropPopupAd) => void">
  ポップアップ広告が閉じられる直前に呼び出されます。
</ParamField>

<ParamField path="onAdDidDismissFullScreen" type="(ad: AdropPopupAd) => void">
  ポップアップ広告が閉じられた直後に呼び出されます。次の広告をプリロードするのに適したタイミングです。
</ParamField>

<ParamField path="onAdFailedToShowFullScreen" type="(ad: AdropPopupAd, errorCode?: any) => void">
  広告の表示に失敗した時に呼び出されます。エラーコードで失敗の理由を確認できます。
</ParamField>

<ParamField path="onAdBackButtonPressed" type="(ad: AdropPopupAd) => void">
  広告表示中にユーザーが戻るボタンを押したときに呼び出されます。**Androidのみ。**
</ParamField>

<ParamField path="onAdVideoStart" type="(ad: AdropPopupAd) => void">
  動画広告の再生が開始されたときに呼び出されます。
</ParamField>

<ParamField path="onAdVideoEnd" type="(ad: AdropPopupAd) => void">
  動画広告の再生が終了したときに呼び出されます。
</ParamField>

### リスナー実装例

```typescript theme={null}
const listener: AdropListener = useMemo(() => ({
  // 広告受信成功
  onAdReceived: (ad: AdropPopupAd) => {
    console.log('ポップアップ広告を受信しました');
    console.log('クリエイティブID:', ad.creativeId);
    console.log('キャンペーンID:', ad.campaignId);
    // 広告の準備ができたら自動表示
    ad.show();
  },

  // 広告受信失敗
  onAdFailedToReceive: (ad: AdropPopupAd, errorCode?: any) => {
    console.log('ポップアップ広告の受信に失敗しました:', errorCode);
  },

  // 広告インプレッション
  onAdImpression: (ad: AdropPopupAd) => {
    console.log('ポップアップ広告のインプレッション');
    console.log('TX ID:', ad.txId);
    console.log('遷移先URL:', ad.destinationURL);
  },

  // 広告クリック
  onAdClicked: (ad: AdropPopupAd) => {
    console.log('ポップアップ広告がクリックされました:', ad.destinationURL);
    // クリック時にポップアップを閉じる
    ad.close();
  },

  // ポップアップ表示直前
  onAdWillPresentFullScreen: (ad: AdropPopupAd) => {
    console.log('ポップアップ広告を表示します');
  },

  // ポップアップ表示完了
  onAdDidPresentFullScreen: (ad: AdropPopupAd) => {
    console.log('ポップアップ広告が表示されました');
  },

  // ポップアップ閉じる直前
  onAdWillDismissFullScreen: (ad: AdropPopupAd) => {
    console.log('ポップアップ広告を閉じます');
  },

  // ポップアップ閉じる完了
  onAdDidDismissFullScreen: (ad: AdropPopupAd) => {
    console.log('ポップアップ広告が閉じられました');
    // 次の広告をプリロード
    loadNextAd();
  },

  // ポップアップ表示失敗
  onAdFailedToShowFullScreen: (ad: AdropPopupAd, errorCode?: any) => {
    console.log('ポップアップ広告の表示に失敗しました:', errorCode);
  },

  // 動画広告再生開始
  onAdVideoStart: (ad: AdropPopupAd) => {
    console.log('動画広告の再生が開始されました:', ad.creativeId);
  },

  // 動画広告再生終了
  onAdVideoEnd: (ad: AdropPopupAd) => {
    console.log('動画広告の再生が終了しました:', ad.creativeId);
  },
}), []);
```

***

## メソッド

### load()

広告をリクエストしてロードします。

```typescript theme={null}
popupAd.load();
```

### show()

ロードされた広告を表示します。`onAdReceived`コールバックが呼び出された後にのみ呼び出すことができます。

```typescript theme={null}
popupAd.show();
```

<Warning>
  広告がロードされている場合（`isLoaded === true`）にのみ`show()`を呼び出してください。
</Warning>

### close()

現在表示されているポップアップ広告を閉じます。主に`onAdClicked`コールバック内で使用されます。

```typescript theme={null}
popupAd.close();
```

### destroy()

広告インスタンスをクリーンアップし、リソースを解放します。コンポーネントのアンマウント時に必ず呼び出してください。

```typescript theme={null}
useEffect(() => {
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  setPopupAd(ad);

  return () => {
    ad.destroy();
  };
}, []);
```

***

## 広告プロパティ

ポップアップ広告オブジェクトで使用可能なプロパティ：

<ParamField path="unitId" type="string">
  広告ユニットID
</ParamField>

<ParamField path="isLoaded" type="boolean">
  広告がロードされているかどうか
</ParamField>

<ParamField path="creativeId" type="string">
  現在表示されている広告のクリエイティブID
</ParamField>

<ParamField path="destinationURL" type="string">
  広告クリック時の遷移先URL
</ParamField>

<ParamField path="txId" type="string">
  トランザクションID（広告インプレッション追跡用）
</ParamField>

<ParamField path="campaignId" type="string">
  キャンペーンID
</ParamField>

<ParamField path="browserTarget" type="BrowserTarget">
  広告クリック時のブラウザターゲット。`BrowserTarget.EXTERNAL` (0)はシステムブラウザ、`BrowserTarget.INTERNAL` (1)はアプリ内ブラウザで開きます。
</ParamField>

***

## カスタマイズ

### 色設定

`AdropPopupAdColors`タイプを使用してポップアップ広告の色をカスタマイズできます。

```typescript theme={null}
import { AdropPopupAd, type AdropPopupAdColors } from 'adrop-ads-react-native';

// 色オプションを定義
const customColors: AdropPopupAdColors = {
  closeTextColor: '#FFFFFF',                    // 閉じるボタンの色
  hideForTodayTextColor: '#456789',             // 「今日は表示しない」の色
  backgroundColor: 'rgba(53, 255, 63, 0.3)',    // 背景（ディム）色
};

// ポップアップ広告作成時に色を適用
const popupAd = new AdropPopupAd(
  'YOUR_POPUP_UNIT_ID',
  customColors
);
```

#### AdropPopupAdColorsタイプ

<ParamField path="closeTextColor" type="string">
  閉じるボタンのテキスト色。HEXカラーコードまたはRGBA形式をサポート。
</ParamField>

<ParamField path="hideForTodayTextColor" type="string">
  「今日は表示しない」のテキスト色。HEXカラーコードまたはRGBA形式をサポート。
</ParamField>

<ParamField path="backgroundColor" type="string">
  ポップアップの背景（ディム）色。HEXカラーコードまたはRGBA形式をサポート。透明度を調整できます。
</ParamField>

### カスタムクリック処理

広告クリック時にデフォルトブラウザを開く代わりにカスタム処理を行うには、`useCustomClick`パラメータを使用します。

```typescript theme={null}
const listener: AdropListener = useMemo(() => ({
  onAdReceived: (ad: AdropPopupAd) => {
    ad.show();
  },
  onAdFailedToReceive: (_: AdropPopupAd, errorCode: any) => {
    console.log('広告の受信に失敗しました:', errorCode);
  },
  onAdClicked: (ad: AdropPopupAd) => {
    // カスタムクリック処理
    console.log('広告がクリックされました:', ad.destinationURL);

    // URLを希望どおりに処理
    // 例：アプリ内ブラウザで開く
    openInAppBrowser(ad.destinationURL);

    // ポップアップを閉じる
    ad.close();
  },
}), []);

// useCustomClickをtrueに設定
const popupAd = new AdropPopupAd(
  'YOUR_POPUP_UNIT_ID',
  undefined,  // colors
  true        // useCustomClick
);
popupAd.listener = listener;
```

***

## テストユニットID

開発およびテスト中は以下のテストユニットIDを使用してください。

| 広告タイプ            | テストユニットID                                     |
| ---------------- | --------------------------------------------- |
| ポップアップ（下部画像）     | `PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM`            |
| ポップアップ（中央画像）     | `PUBLIC_TEST_UNIT_ID_POPUP_CENTER`            |
| ポップアップ動画（下部16:9） | `PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM_VIDEO_16_9` |
| ポップアップ動画（下部9:16） | `PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM_VIDEO_9_16` |
| ポップアップ動画（中央16:9） | `PUBLIC_TEST_UNIT_ID_POPUP_CENTER_VIDEO_16_9` |
| ポップアップ動画（中央9:16） | `PUBLIC_TEST_UNIT_ID_POPUP_CENTER_VIDEO_9_16` |

### テスト広告の使用例

```typescript theme={null}
// 開発環境と本番環境を分離
const POPUP_UNIT_ID = __DEV__
  ? 'PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM'  // テストユニットID
  : 'YOUR_PRODUCTION_UNIT_ID';           // 本番ユニットID

const popupAd = new AdropPopupAd(POPUP_UNIT_ID);
```

<Warning>
  本番リリース時は、広告管理コンソールで作成した実際のユニットIDを使用してください。
</Warning>

***

## エラー処理

広告のロードまたは表示の失敗時にエラーコードを確認して適切に対処してください。

```typescript theme={null}
const listener: AdropListener = {
  onAdFailedToReceive: (ad: AdropPopupAd, errorCode?: any) => {
    console.error('広告の受信に失敗しました:', errorCode);

    switch (errorCode) {
      case AdropErrorCode.network:
        // ネットワークエラーを処理
        console.log('ネットワーク接続を確認してください');
        break;
      case AdropErrorCode.adNoFill:
        // 広告在庫不足
        console.log('表示可能な広告がありません');
        break;
      case AdropErrorCode.invalidUnit:
        // 無効なユニットID
        console.log('広告ユニットIDを確認してください');
        break;
      default:
        console.log('広告をロードできません');
    }
  },

  onAdFailedToShowFullScreen: (ad: AdropPopupAd, errorCode?: any) => {
    console.error('広告の表示に失敗しました:', errorCode);

    // 後でリトライ
    setTimeout(() => {
      ad.load();
    }, 30000); // 30秒後にリトライ
  },
};
```

***

## ベストプラクティス

### 1. 適切な表示タイミング

ポップアップ広告は以下のタイミングで最も効果的です：

```typescript theme={null}
// 良い例：アプリ起動時
useEffect(() => {
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  ad.listener = {
    onAdReceived: (ad) => ad.show(),
    onAdFailedToReceive: (_, error) => console.log(error),
  };
  ad.load();

  return () => ad.destroy();
}, []);

// 良い例：コンテンツ読み込み完了後
const onContentLoaded = () => {
  if (shouldShowPopupAd()) {
    popupAd?.show();
  }
};

// 良い例：特定イベント完了時
const onAchievementUnlocked = () => {
  popupAd?.show();
};

// 悪い例：ユーザーの作業中
const onUserTyping = () => {
  popupAd?.show(); // ユーザー体験を損なう
};
```

### 2. 頻度制限

ポップアップ広告を頻繁に表示しすぎないようにしてください。

```typescript theme={null}
import AsyncStorage from '@react-native-async-storage/async-storage';

const LAST_SHOWN_KEY = 'popup_ad_last_shown';
const MINIMUM_INTERVAL = 3600000; // 1時間（ミリ秒）

// 広告を表示できるかチェック
const canShowAd = async (): Promise<boolean> => {
  try {
    const lastShown = await AsyncStorage.getItem(LAST_SHOWN_KEY);
    if (!lastShown) return true;

    const currentTime = Date.now();
    const lastShownTime = parseInt(lastShown, 10);

    return currentTime - lastShownTime >= MINIMUM_INTERVAL;
  } catch (error) {
    return true;
  }
};

// 広告表示を記録
const recordAdShown = async () => {
  try {
    await AsyncStorage.setItem(LAST_SHOWN_KEY, Date.now().toString());
  } catch (error) {
    console.error('広告表示の記録エラー:', error);
  }
};

// 使用方法
const showAdIfAllowed = async () => {
  if (await canShowAd()) {
    popupAd?.show();
    await recordAdShown();
  }
};
```

### 3. 広告のプリロード

より良いユーザー体験のために広告をプリロードしてください。

```typescript theme={null}
const [isAdReady, setIsAdReady] = useState(false);

useEffect(() => {
  // アプリ起動時にプリロード
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  ad.listener = {
    onAdReceived: () => setIsAdReady(true),
    onAdFailedToReceive: (_, error) => console.log(error),
  };
  ad.load();

  setPopupAd(ad);
  return () => ad.destroy();
}, []);

// 希望のタイミングで即座に表示
const showPopupNow = () => {
  if (isAdReady) {
    popupAd?.show();
  }
};
```

### 4. メモリ管理

コンポーネントのアンマウント時に必ず広告をクリーンアップしてください。

```typescript theme={null}
useEffect(() => {
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  setPopupAd(ad);

  // クリーンアップ関数
  return () => {
    ad.destroy();
  };
}, []);
```

### 5. クリック時にポップアップを閉じる

より良いユーザー体験のために、広告クリック時にポップアップを閉じてください。

```typescript theme={null}
const listener: AdropListener = {
  onAdClicked: (ad: AdropPopupAd) => {
    console.log('広告がクリックされました:', ad.destinationURL);
    // クリック時に自動的にポップアップを閉じる
    ad.close();
  },
};
```

***

## トラブルシューティング

### 広告が表示されない

<AccordionGroup>
  <Accordion title="onAdReceivedが呼び出されない">
    * SDKが初期化されているか確認
    * ユニットIDが正しいか確認
    * ネットワーク接続を確認
    * テスト環境ではテストユニットIDを使用
  </Accordion>

  <Accordion title="onAdFailedToReceiveが呼び出される">
    * エラーコードを確認して原因を特定
    * 広告在庫が不足している場合は後でリトライ
    * ネイティブSDKが正しく統合されているか確認
  </Accordion>

  <Accordion title="show()呼び出し後に何も起きない">
    * `onAdReceived`コールバックの後に`show()`が呼び出されているか確認
    * `isLoaded`プロパティで広告がロードされているか確認
    * ネイティブモジュールが正しく接続されているか確認
  </Accordion>
</AccordionGroup>

### メモリリーク

```typescript theme={null}
// 良い例：クリーンアップ関数を使用
useEffect(() => {
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  setPopupAd(ad);

  return () => {
    ad.destroy();  // 必ず呼び出す
  };
}, []);

// 悪い例：クリーンアップなし
useEffect(() => {
  const ad = new AdropPopupAd('YOUR_UNIT_ID');
  setPopupAd(ad);
  // destroy()を呼び出さない - メモリリーク！
}, []);
```

***

## 関連ドキュメント

<CardGroup cols={2}>
  <Card title="はじめに" href="/ja/sdk/react-native">
    SDKのインストールと初期化
  </Card>

  <Card title="インタースティシャル広告" href="/ja/sdk/react-native/interstitial">
    インタースティシャル広告の実装
  </Card>

  <Card title="リワード広告" href="/ja/sdk/react-native/rewarded">
    リワード広告の実装
  </Card>

  <Card title="バナー広告" href="/ja/sdk/react-native/banner">
    バナー広告の実装
  </Card>
</CardGroup>