> ## 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.

# ポップアップ広告

> iOSアプリでポップアップ広告を実装する方法を案内します。

## 概要

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

### 特徴

* 画面中央または下部に表示されるポップアップ形式
* 画像および動画広告に対応
* 閉じる、Dim(背景)クリック、「今日は表示しない」オプションを提供
* 背景色、テキストカラーなどのカスタマイズ可能
* ユーザーの邪魔にならず効果的な広告体験

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

***

## 実装手順

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

1. **初期化** - AdropPopupAdインスタンスの生成
2. **デリゲートの設定** - 広告および閉じるイベント受信のためのデリゲート設定
3. **広告の読み込み** - 広告リクエストと受信
4. **広告の表示** - 画面への広告表示

***

## UIKit実装

### 基本実装

<CodeGroup>
  ```swift Swift theme={null}
  import AdropAds

  class ViewController: UIViewController {
      private var popupAd: AdropPopupAd?

      override func viewDidLoad() {
          super.viewDidLoad()
          loadPopupAd()
      }

      // 1. 広告の初期化と読み込み
      private func loadPopupAd() {
          popupAd = AdropPopupAd(unitId: "YOUR_POPUP_UNIT_ID")
          popupAd?.delegate = self
          popupAd?.closeDelegate = self
          popupAd?.load()
      }

      // 2. 広告の表示
      private func showPopupAd() {
          guard let popupAd = popupAd,
                popupAd.isLoaded else { return }
          popupAd.show(fromRootViewController: self)
      }
  }
  ```

  ```objc Objective-C theme={null}
  @import AdropAds;

  @interface ViewController () <AdropPopupAdDelegate, AdropPopupAdCloseDelegate>
  @property (nonatomic, strong) AdropPopupAd *popupAd;
  @end

  @implementation ViewController

  - (void)viewDidLoad {
      [super viewDidLoad];
      [self loadPopupAd];
  }

  // 1. 広告の初期化と読み込み
  - (void)loadPopupAd {
      self.popupAd = [[AdropPopupAd alloc] initWithUnitId:@"YOUR_POPUP_UNIT_ID"];
      self.popupAd.delegate = self;
      self.popupAd.closeDelegate = self;
      [self.popupAd load];
  }

  // 2. 広告の表示
  - (void)showPopupAd {
      if (self.popupAd && self.popupAd.isLoaded) {
          [self.popupAd showFromRootViewController:self];
      }
  }

  @end
  ```
</CodeGroup>

### デリゲートの実装

<CodeGroup>
  ```swift Swift theme={null}
  // 広告デリゲートの実装
  extension ViewController: AdropPopupAdDelegate {
      // 広告受信成功 (必須)
      func onAdReceived(_ ad: AdropPopupAd) {
          print("ポップアップ広告受信完了")
          // 広告が準備できたら表示
          showPopupAd()
      }

      // 広告受信失敗 (必須)
      func onAdFailedToReceive(_ ad: AdropPopupAd, _ errorCode: AdropErrorCode) {
          print("ポップアップ広告受信失敗: \(errorCode)")
      }

      // 広告表示 (オプション)
      func onAdImpression(_ ad: AdropPopupAd) {
          print("ポップアップ広告表示")
      }

      // 広告クリック (オプション)
      func onAdClicked(_ ad: AdropPopupAd) {
          print("ポップアップ広告クリック")
      }

      // ポップアップ広告表示直前 (オプション)
      func onAdWillPresentFullScreen(_ ad: AdropPopupAd) {
          print("ポップアップ広告表示直前")
      }

      // ポップアップ広告表示直後 (オプション)
      func onAdDidPresentFullScreen(_ ad: AdropPopupAd) {
          print("ポップアップ広告表示完了")
      }

      // ポップアップ広告を閉じる直前 (オプション)
      func onAdWillDismissFullScreen(_ ad: AdropPopupAd) {
          print("ポップアップ広告を閉じる直前")
      }

      // ポップアップ広告が閉じた直後 (オプション)
      func onAdDidDismissFullScreen(_ ad: AdropPopupAd) {
          print("ポップアップ広告を閉じた")
          // 次の広告を事前読み込み
          loadPopupAd()
      }

      // ポップアップ広告表示失敗 (オプション)
      func onAdFailedToShowFullScreen(_ ad: AdropPopupAd, _ errorCode: AdropErrorCode) {
          print("ポップアップ広告表示失敗: \(errorCode)")
      }
  }

  // 閉じるデリゲートの実装
  extension ViewController: AdropPopupAdCloseDelegate {
      // 閉じるボタンクリック (オプション)
      func onClosed(_ ad: AdropPopupAd) {
          print("ポップアップ広告閉じるボタンクリック")
      }

      // Dim(背景)クリック (オプション)
      func onDimClicked(_ ad: AdropPopupAd) {
          print("ポップアップ広告Dim領域クリック")
      }

      // 「今日は表示しない」クリック (オプション)
      func onTodayOffClicked(_ ad: AdropPopupAd) {
          print("今日は表示しない選択")
          // SDKが自動的に今日の非表示処理を行います。
          // このコールバックは分析ログやカスタムUI更新に活用してください。
      }
  }
  ```

  ```objc Objective-C theme={null}
  #pragma mark - AdropPopupAdDelegate

  // 広告受信成功 (必須)
  - (void)onAdReceived:(AdropPopupAd *)ad {
      NSLog(@"ポップアップ広告受信完了");
      // 広告が準備できたら表示
      [self showPopupAd];
  }

  // 広告受信失敗 (必須)
  - (void)onAdFailedToReceive:(AdropPopupAd *)ad :(AdropErrorCode)errorCode {
      NSLog(@"ポップアップ広告受信失敗: %ld", (long)errorCode);
  }

  // 広告表示 (オプション)
  - (void)onAdImpression:(AdropPopupAd *)ad {
      NSLog(@"ポップアップ広告表示");
  }

  // 広告クリック (オプション)
  - (void)onAdClicked:(AdropPopupAd *)ad {
      NSLog(@"ポップアップ広告クリック");
  }

  // ポップアップ広告が閉じた直後 (オプション)
  - (void)onAdDidDismissFullScreen:(AdropPopupAd *)ad {
      NSLog(@"ポップアップ広告を閉じた");
      // 次の広告を事前読み込み
      [self loadPopupAd];
  }

  #pragma mark - AdropPopupAdCloseDelegate

  // 閉じるボタンクリック (オプション)
  - (void)onClosed:(AdropPopupAd *)ad {
      NSLog(@"ポップアップ広告閉じるボタンクリック");
  }

  // Dim(背景)クリック (オプション)
  - (void)onDimClicked:(AdropPopupAd *)ad {
      NSLog(@"ポップアップ広告Dim領域クリック");
  }

  // 「今日は表示しない」クリック (オプション)
  - (void)onTodayOffClicked:(AdropPopupAd *)ad {
      NSLog(@"今日は表示しない選択");
      // SDKが自動的に今日の非表示処理を行います。
      // このコールバックは分析ログやカスタムUI更新に活用してください。
  }
  ```
</CodeGroup>

***

## SwiftUI実装

SwiftUIでは、`UIViewControllerRepresentable`を使用するか、UIWindowからrootViewControllerを取得して表示できます。

### ViewModelパターン

```swift theme={null}
import SwiftUI
import AdropAds

// ViewModel
class PopupAdViewModel: ObservableObject {
    @Published var isAdReady = false
    @Published var isAdShowing = false

    private var popupAd: AdropPopupAd?

    init() {
        loadAd()
    }

    func loadAd() {
        popupAd = AdropPopupAd(unitId: "YOUR_POPUP_UNIT_ID")
        popupAd?.delegate = self
        popupAd?.closeDelegate = self
        popupAd?.load()
    }

    func showAd() {
        guard let popupAd = popupAd,
              let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
              let rootViewController = windowScene.windows.first?.rootViewController else {
            return
        }

        popupAd.show(fromRootViewController: rootViewController)
    }

}

// 広告デリゲート
extension PopupAdViewModel: AdropPopupAdDelegate {
    func onAdReceived(_ ad: AdropPopupAd) {
        DispatchQueue.main.async {
            self.isAdReady = true
        }
    }

    func onAdFailedToReceive(_ ad: AdropPopupAd, _ errorCode: AdropErrorCode) {
        print("広告受信失敗: \(errorCode)")
    }

    func onAdDidPresentFullScreen(_ ad: AdropPopupAd) {
        DispatchQueue.main.async {
            self.isAdShowing = true
        }
    }

    func onAdDidDismissFullScreen(_ ad: AdropPopupAd) {
        DispatchQueue.main.async {
            self.isAdShowing = false
            self.isAdReady = false
        }
        // 次の広告を事前読み込み
        loadAd()
    }
}

// 閉じるデリゲート
extension PopupAdViewModel: AdropPopupAdCloseDelegate {
    func onClosed(_ ad: AdropPopupAd) {
        print("ポップアップ広告を閉じた")
    }

    func onDimClicked(_ ad: AdropPopupAd) {
        print("ポップアップ広告Dimクリック")
    }

    func onTodayOffClicked(_ ad: AdropPopupAd) {
        print("今日は表示しない選択")
        // SDKが自動的に今日の非表示処理を行います。
        // このコールバックは分析ログやカスタムUI更新に活用してください。
    }
}

// View
struct ContentView: View {
    @StateObject private var adViewModel = PopupAdViewModel()

    var body: some View {
        VStack {
            Text("ポップアップ広告の例")
                .font(.title)

            Button("ポップアップ広告を表示") {
                adViewModel.showAd()
            }
            .disabled(!adViewModel.isAdReady)
            .padding()
        }
        .onAppear {
            // アプリ起動時に自動表示
            if adViewModel.isAdReady {
                adViewModel.showAd()
            }
        }
    }
}
```

***

## カスタマイズ

ポップアップ広告の外観をカスタマイズできます。

### 背景色とテキストカラーの設定

```swift theme={null}
private func loadPopupAd() {
    popupAd = AdropPopupAd(unitId: "YOUR_POPUP_UNIT_ID")
    popupAd?.delegate = self
    popupAd?.closeDelegate = self

    // 背景色の設定
    popupAd?.backgroundColor = UIColor.black.withAlphaComponent(0.8)

    // 「今日は表示しない」テキストカラー
    popupAd?.hideForTodayTextColor = UIColor.white

    // 閉じるボタンテキストカラー
    popupAd?.closeTextColor = UIColor.white

    // CTAボタンテキストカラー
    popupAd?.ctaTextColor = UIColor.white

    popupAd?.load()
}
```

### カスタマイズオプション

| プロパティ                   | 型          | 説明                            | デフォルト |
| ----------------------- | ---------- | ----------------------------- | ----- |
| `backgroundColor`       | `UIColor?` | アクションバーの背景色                   | `nil` |
| `hideForTodayTextColor` | `UIColor?` | 「今日は表示しない」テキストカラー             | 白     |
| `closeTextColor`        | `UIColor?` | 閉じるボタンテキストカラー                 | 白     |
| `ctaTextColor`          | `UIColor?` | CTA（Call to Action）ボタンテキストカラー | 白     |

***

## デリゲートメソッド

### AdropPopupAdDelegate（広告イベント）

#### 必須メソッド

<ParamField body="onAdReceived" type="(AdropPopupAd) -> Void">
  広告受信成功時に呼び出されます。この時点で`show()`を呼び出して広告を表示できます。
</ParamField>

<ParamField body="onAdFailedToReceive" type="(AdropPopupAd, AdropErrorCode) -> Void">
  広告受信失敗時に呼び出されます。エラーコードで失敗原因を確認できます。
</ParamField>

#### オプションメソッド

<ParamField body="onAdImpression" type="(AdropPopupAd) -> Void">
  広告インプレッションが記録されたときに呼び出されます。
</ParamField>

<ParamField body="onAdClicked" type="(AdropPopupAd) -> Void">
  ユーザーが広告をクリックしたときに呼び出されます。
</ParamField>

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

<ParamField body="onAdDidPresentFullScreen" type="(AdropPopupAd) -> Void">
  ポップアップ広告が画面に表示された直後に呼び出されます。
</ParamField>

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

<ParamField body="onAdDidDismissFullScreen" type="(AdropPopupAd) -> Void">
  ポップアップ広告が閉じられた直後に呼び出されます。次の広告を事前読み込みするのに適したタイミングです。
</ParamField>

<ParamField body="onAdFailedToShowFullScreen" type="(AdropPopupAd, AdropErrorCode) -> Void">
  広告表示失敗時に呼び出されます。エラーコードで失敗原因を確認できます。
</ParamField>

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

<ParamField body="onAdVideoEnd" type="(AdropPopupAd) -> Void">
  動画広告の再生が完了したときに呼び出されます。
</ParamField>

### AdropPopupAdCloseDelegate（閉じるイベント）

すべてのメソッドはオプションです。

<ParamField body="onClosed" type="(AdropPopupAd) -> Void">
  ユーザーが閉じるボタンをクリックしたときに呼び出されます。
</ParamField>

<ParamField body="onDimClicked" type="(AdropPopupAd) -> Void">
  ユーザーがポップアップ外部（Dim領域）をクリックしたときに呼び出されます。
</ParamField>

<ParamField body="onTodayOffClicked" type="(AdropPopupAd) -> Void">
  ユーザーが「今日は表示しない」を選択したときに呼び出されます。このコールバックで日付を保存して、1日中広告を表示しないように実装できます。
</ParamField>

***

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

`useCustomClick`を使用して広告クリック動作を制御できます。有効にすると、SDKはクリック時に自動的にURLを開かず、手動で処理できます。

### useCustomClick

```swift theme={null}
popupAd = AdropPopupAd(unitId: "YOUR_POPUP_UNIT_ID")
popupAd?.useCustomClick = true
popupAd?.delegate = self
popupAd?.load()
```

`useCustomClick`が`true`の場合、SDKは広告クリック時に自動的にURLを開きません。`onAdClicked`デリゲートコールバックは引き続き呼び出され、`open()`メソッドを使用するか、独自にナビゲーションを処理できます。

### open()

広告の遷移先URLを開きます。カスタムURLを指定することもできます。

```swift theme={null}
// 広告のデフォルト遷移先URLを開く
popupAd?.open()

// カスタムURLを開く
popupAd?.open("https://example.com")

// アプリ内ブラウザを使用して開く
popupAd?.open(nil, useInAppBrowser: true)
```

### close()

プログラムでポップアップ広告を閉じます。

```swift theme={null}
popupAd?.close()
```

***

## プロパティ

| プロパティ            | 型                | 説明                      |
| ---------------- | ---------------- | ----------------------- |
| `unitId`         | `String`         | 広告ユニットID                |
| `isLoaded`       | `Bool`           | 広告が読み込まれたかどうか           |
| `useCustomClick` | `Bool`           | 広告クリックを手動で処理するかどうか      |
| `destinationURL` | `String?`        | 現在表示中の広告の遷移先URL         |
| `creativeId`     | `String?`        | 現在表示中の広告のクリエイティブID      |
| `txId`           | `String`         | 現在表示中の広告のトランザクションID     |
| `txIds`          | `[String]`       | 読み込まれたすべての広告のトランザクションID |
| `campaignId`     | `String`         | 現在表示中の広告のキャンペーンID       |
| `campaignIds`    | `[String]`       | 読み込まれたすべての広告のキャンペーンID   |
| `creativeIds`    | `[String]`       | 読み込まれたすべての広告のクリエイティブID  |
| `browserTarget`  | `BrowserTarget?` | 広告クリック時のURL開き方          |

***

## クロージャベースのコールバック

デリゲートに加えて、クロージャベースのコールバックも使用できます。完全なデリゲートパターンを実装したくない場合に便利です。

```swift theme={null}
let popupAd = AdropPopupAd(unitId: "YOUR_POPUP_UNIT_ID")

// 広告イベント
popupAd.onAdReceived = { ad in
    print("広告受信完了")
}
popupAd.onAdFailedToReceive = { ad, errorCode in
    print("広告受信失敗: \(errorCode)")
}
popupAd.onAdClicked = { ad in
    print("広告クリック、遷移先: \(ad.destinationURL ?? "")")
}
popupAd.onAdImpression = { ad in
    print("広告インプレッション")
}
popupAd.onAdWillPresentFullScreen = { ad in
    print("表示直前")
}
popupAd.onAdDidPresentFullScreen = { ad in
    print("表示完了")
}
popupAd.onAdWillDismissFullScreen = { ad in
    print("閉じる直前")
}
popupAd.onAdDidDismissFullScreen = { ad in
    print("閉じた")
}
popupAd.onAdFailedToShowFullScreen = { ad, errorCode in
    print("表示失敗: \(errorCode)")
}
popupAd.onAdVideoStart = { ad in
    print("動画再生開始")
}
popupAd.onAdVideoEnd = { ad in
    print("動画再生完了")
}

// 閉じるイベント
popupAd.onClosed = { ad in
    print("閉じた")
}
popupAd.onDimClicked = { ad in
    print("Dimクリック")
}
popupAd.onTodayOffClicked = { ad in
    print("今日は表示しない")
}

popupAd.load()
```

<Note>
  デリゲートコールバックとクロージャベースのコールバックは同時に使用できます。両方とも呼び出されます。
</Note>

***

## 「今日は表示しない」実装

ユーザーが「今日は表示しない」を選択したときに適切に処理する方法です。

<Note>SDKは「今日は表示しない」状態を自動的に管理します。以下の例は、組み込みの処理に加えてカスタム動作を追加する方法を示しています。</Note>

### 実装

SDKは「今日は表示しない」を選択した場合、`load()`時に自動的にロードをスキップします。手動チェックなしで`load()`を呼び出すだけで済みます。

```swift theme={null}
class PopupAdManager {
    private var popupAd: AdropPopupAd?

    // 広告の読み込みと表示
    func loadAndShowAd(from viewController: UIViewController) {
        popupAd = AdropPopupAd(unitId: "YOUR_POPUP_UNIT_ID")
        popupAd?.delegate = self
        popupAd?.closeDelegate = self
        popupAd?.load()
    }
}

extension PopupAdManager: AdropPopupAdDelegate {
    func onAdReceived(_ ad: AdropPopupAd) {
        // 広告受信後に自動表示
        if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
           let rootViewController = windowScene.windows.first?.rootViewController {
            ad.show(fromRootViewController: rootViewController)
        }
    }

    func onAdFailedToReceive(_ ad: AdropPopupAd, _ errorCode: AdropErrorCode) {
        print("広告受信失敗: \(errorCode)")
    }
}

extension PopupAdManager: AdropPopupAdCloseDelegate {
    func onTodayOffClicked(_ ad: AdropPopupAd) {
        print("今日は表示しない選択")
        // SDKが自動的に今日の非表示処理を行います。
        // このコールバックは分析ログやカスタムUI更新に活用してください。
    }
}
```

***

## ベストプラクティス

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

ポップアップ広告は次のタイミングで表示するのが効果的です:

```swift theme={null}
// ✅ 良い例: アプリ起動時
func applicationDidFinishLaunching() {
    loadAndShowPopupAd()
}

// ✅ 良い例: コンテンツ読み込み完了時
func onContentLoaded() {
    if shouldShowPopupAd() {
        showPopupAd()
    }
}

// ✅ 良い例: 特定のイベント完了時
func onAchievementUnlocked() {
    showPopupAd()
}

// ❌ 悪い例: ユーザーが作業中のとき
func onUserTyping() {
    showPopupAd() // ユーザー体験を阻害
}
```

### 2. 「今日は表示しない」の尊重

ユーザーが「今日は表示しない」を選択した場合は、必ず遵守してください。

```swift theme={null}
func shouldShowPopupAd() -> Bool {
    // 「今日は表示しない」を確認
    guard canShowAdToday() else {
        return false
    }

    // その他の条件を確認
    return true
}
```

### 3. 頻度制限

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

```swift theme={null}
class PopupAdFrequencyManager {
    private let lastShownKey = "popupAd_lastShown"
    private let minimumInterval: TimeInterval = 3600 // 1時間

    func canShowAd() -> Bool {
        // 「今日は表示しない」を確認
        guard canShowAdToday() else {
            return false
        }

        // 最小時間間隔を確認
        guard let lastShown = UserDefaults.standard.object(forKey: lastShownKey) as? Date else {
            return true
        }

        return Date().timeIntervalSince(lastShown) >= minimumInterval
    }

    func recordAdShown() {
        UserDefaults.standard.set(Date(), forKey: lastShownKey)
    }
}
```

***

## テストユニット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` |

<Warning>
  実際のデプロイ時には、必ず広告コントロールコンソールで作成した実際のユニットIDを使用してください。
</Warning>

***

## 関連ドキュメント

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

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

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

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