バナー広告 - Ad Control Help Center

概要

バナー広告は画面の一部領域に表示される長方形の広告です。AdropBannerViewウィジェットを使用して簡単に実装できます。

主な特徴

画面上部、下部、または中央に固定配置可能
画像および動画広告をサポート
コールバックによる広告イベント処理
広告メタデータを提供（クリエイティブID、キャンペーンIDなど）

開発環境ではテストユニットIDを使用してください：PUBLIC_TEST_UNIT_ID_320_100

AdropBannerView

コンストラクタ

AdropBannerView({
  required String unitId,
  String? contextId,
  AdropBannerListener? listener,
})

パラメータ

パラメータ	タイプ	必須	説明
`unitId`	`String`	Y	Ad Controlコンソールで作成したユニットID
`contextId`	`String`	N	コンテキストターゲティングに使用するコンテキストID（1.17.0+）
`listener`	`AdropBannerListener`	N	広告イベントリスナー

プロパティ

プロパティ	タイプ	説明
`contextId`	`String?`	コンストラクタに渡したコンテキストID
`creativeSize`	`CreativeSize?`	広告クリエイティブサイズ
`adSize`	`Size?`	バナービューのサイズ設定

メソッド

メソッド	戻り値の型	説明
`load()`	`Future<void>`	広告をロードします
`dispose()`	`Future<void>`	リソースを解放します

基本的な使い方

import 'package:flutter/material.dart';
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

class BannerExample extends StatefulWidget {
  const BannerExample({super.key});

  @override
  State<BannerExample> createState() => _BannerExampleState();
}

class _BannerExampleState extends State<BannerExample> {
  bool isLoaded = false;
  late AdropBannerView bannerView;

  @override
  void initState() {
    super.initState();

    bannerView = AdropBannerView(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (unitId, metadata) {
          debugPrint('バナー広告受信成功: $unitId');
          setState(() {
            isLoaded = true;
          });
        },
        onAdClicked: (unitId, metadata) {
          debugPrint('バナー広告クリック: $unitId');
        },
        onAdImpression: (unitId, metadata) {
          debugPrint('バナー広告表示: $unitId');
        },
        onAdFailedToReceive: (unitId, errorCode) {
          debugPrint('バナー広告受信失敗: $unitId, $errorCode');
          setState(() {
            isLoaded = false;
          });
        },
      ),
    );

    // 広告ロード
    bannerView.load();
  }

  @override
  void dispose() {
    bannerView.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('バナー広告の例')),
      body: Column(
        children: [
          // メインコンテンツ
          Expanded(
            child: Center(
              child: const Text('メインコンテンツ'),
            ),
          ),
          // バナー広告
          if (isLoaded)
            SizedBox(
              width: MediaQuery.of(context).size.width,
              height: 80,
              child: bannerView,
            ),
        ],
      ),
    );
  }
}

AdropBannerListener

バナー広告イベントを処理するリスナーです。

コールバック関数

AdropBannerListener(
  onAdReceived: (String unitId, Map<String, dynamic>? metadata) {
    // 広告受信成功
  },
  onAdClicked: (String unitId, Map<String, dynamic>? metadata) {
    // 広告クリック
  },
  onAdImpression: (String unitId, Map<String, dynamic>? metadata) {
    // 広告表示
  },
  onAdFailedToReceive: (String unitId, AdropErrorCode errorCode) {
    // 広告受信失敗
  },
  onAdVideoStart: (String unitId) {
    // 動画広告の再生開始
  },
  onAdVideoEnd: (String unitId) {
    // 動画広告の再生終了
  },
)

コールバックの説明

コールバック	説明
`onAdReceived`	広告受信成功時に呼び出し
`onAdClicked`	広告クリック時に呼び出し
`onAdImpression`	広告表示時に呼び出し
`onAdFailedToReceive`	広告受信失敗時に呼び出し
`onAdVideoStart`	動画広告の再生開始時に呼び出し
`onAdVideoEnd`	動画広告の再生終了時に呼び出し

メタデータ

onAdReceived、onAdClicked、onAdImpressionコールバックでメタデータを受け取ることができます。

onAdReceived: (unitId, metadata) {
  debugPrint('クリエイティブID: ${metadata?['creativeId']}');
  debugPrint('トランザクションID: ${metadata?['txId']}');
  debugPrint('キャンペーンID: ${metadata?['campaignId']}');
  debugPrint('遷移先URL: ${metadata?['destinationURL']}');
  debugPrint('ブラウザターゲット: ${metadata?['browserTarget']}');
}

フィールド	タイプ	説明
`creativeId`	`String`	クリエイティブID
`txId`	`String`	トランザクションID
`campaignId`	`String`	キャンペーンID
`destinationURL`	`String`	遷移先URL
`browserTarget`	`int?`	ブラウザターゲット（0: 外部ブラウザ、1: アプリ内ブラウザ）

クリエイティブサイズはメタデータではなく、bannerView.creativeSize?.widthおよびbannerView.creativeSize?.heightからアクセスします。

広告サイズ

バナー広告はユニットに設定したサイズに合わせてコンテナサイズを指定する必要があります。

一般的なバナーサイズ

サイズ	テストユニットID	用途
320 x 50	`PUBLIC_TEST_UNIT_ID_320_50`	小型バナー
320 x 100	`PUBLIC_TEST_UNIT_ID_320_100`	中型バナー

固定サイズの使用

SizedBox(
  width: 320,
  height: 100,
  child: bannerView,
)

画面幅に合わせる

SizedBox(
  width: MediaQuery.of(context).size.width,
  height: 80,
  child: bannerView,
)

サイズ設定

adSizeプロパティを使用してバナービューのサイズを明示的に設定できます。

@override
void initState() {
  super.initState();

  bannerView = AdropBannerView(
    unitId: 'YOUR_UNIT_ID',
    listener: AdropBannerListener(
      onAdReceived: (unitId, metadata) {
        setState(() {
          isLoaded = true;
        });
      },
    ),
  );

  // コンテキストが準備された後にサイズを設定
  WidgetsBinding.instance.addPostFrameCallback((_) {
    bannerView.adSize = Size(
      MediaQuery.of(context).size.width,
      80,
    );
  });
}

エラー処理

広告ロード失敗時に適切なエラー処理を実装してください。

class _BannerExampleState extends State<BannerExample> {
  bool isLoaded = false;
  AdropErrorCode? errorCode;
  late AdropBannerView bannerView;

  @override
  void initState() {
    super.initState();

    bannerView = AdropBannerView(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (unitId, metadata) {
          setState(() {
            isLoaded = true;
            errorCode = null;
          });
        },
        onAdFailedToReceive: (unitId, error) {
          setState(() {
            isLoaded = false;
            errorCode = error;
          });
        },
      ),
    );

    bannerView.load();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        if (isLoaded)
          SizedBox(
            width: MediaQuery.of(context).size.width,
            height: 80,
            child: bannerView,
          )
        else if (errorCode != null)
          Text('広告ロード失敗: ${errorCode?.code}'),
      ],
    );
  }

  @override
  void dispose() {
    bannerView.dispose();
    super.dispose();
  }
}

ベストプラクティス

1. リソースの解放

バナービューが不要になったら必ずdispose()を呼び出してください。

@override
void dispose() {
  bannerView.dispose();
  super.dispose();
}

2. 広告の更新

必要に応じて広告を更新できます。

void refreshAd() {
  setState(() {
    isLoaded = false;
  });
  bannerView.load();
}

3. 条件付きレンダリング

広告がロードされるまでバナー領域を非表示にするか、プレースホルダーを表示してください。

Widget buildBanner() {
  if (isLoaded) {
    return SizedBox(
      width: MediaQuery.of(context).size.width,
      height: 80,
      child: bannerView,
    );
  } else if (isLoading) {
    return const SizedBox(
      height: 80,
      child: Center(child: CircularProgressIndicator()),
    );
  } else {
    return const SizedBox.shrink();
  }
}

4. 複数バナーの管理

複数のバナーを使用する場合は、それぞれの状態を管理してください。

class _MultiBannerState extends State<MultiBanner> {
  late AdropBannerView topBanner;
  late AdropBannerView bottomBanner;
  bool isTopLoaded = false;
  bool isBottomLoaded = false;

  @override
  void initState() {
    super.initState();

    topBanner = AdropBannerView(
      unitId: 'TOP_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (_, __) => setState(() => isTopLoaded = true),
      ),
    );

    bottomBanner = AdropBannerView(
      unitId: 'BOTTOM_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (_, __) => setState(() => isBottomLoaded = true),
      ),
    );

    topBanner.load();
    bottomBanner.load();
  }

  @override
  void dispose() {
    topBanner.dispose();
    bottomBanner.dispose();
    super.dispose();
  }

  // ...
}

完全な例

import 'package:flutter/material.dart';
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

class BannerAdPage extends StatefulWidget {
  const BannerAdPage({super.key});

  @override
  State<BannerAdPage> createState() => _BannerAdPageState();
}

class _BannerAdPageState extends State<BannerAdPage> {
  static const double bannerHeight = 80;
  bool isLoaded = false;
  bool isLoading = false;
  AdropErrorCode? errorCode;
  late AdropBannerView bannerView;

  @override
  void initState() {
    super.initState();

    bannerView = AdropBannerView(
      unitId: 'PUBLIC_TEST_UNIT_ID_320_100', // テストユニットID
      listener: AdropBannerListener(
        onAdReceived: (unitId, metadata) {
          debugPrint('広告受信成功');
          debugPrint('クリエイティブID: ${metadata?['creativeId']}');
          debugPrint('キャンペーンID: ${metadata?['campaignId']}');
          debugPrint('クリエイティブサイズ: ${bannerView.creativeSize?.width}x${bannerView.creativeSize?.height}');
          setState(() {
            isLoaded = true;
            isLoading = false;
            errorCode = null;
          });
        },
        onAdClicked: (unitId, metadata) {
          debugPrint('広告クリック: ${metadata?['destinationURL']}');
        },
        onAdImpression: (unitId, metadata) {
          debugPrint('広告表示: ${metadata?['creativeId']}');
        },
        onAdFailedToReceive: (unitId, error) {
          debugPrint('広告受信失敗: $error');
          setState(() {
            isLoaded = false;
            isLoading = false;
            errorCode = error;
          });
        },
      ),
    );

    WidgetsBinding.instance.addPostFrameCallback((_) {
      bannerView.adSize = Size(
        MediaQuery.of(context).size.width,
        bannerHeight,
      );
    });
  }

  void loadAd() {
    setState(() {
      isLoading = true;
      errorCode = null;
    });
    bannerView.load();
  }

  @override
  void dispose() {
    bannerView.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('バナー広告の例'),
      ),
      body: SafeArea(
        child: Column(
          children: [
            // ロードボタン
            Padding(
              padding: const EdgeInsets.all(16),
              child: ElevatedButton(
                onPressed: isLoading ? null : loadAd,
                child: Text(isLoading ? 'ロード中...' : 'バナー広告をロード'),
              ),
            ),

            // 状態表示
            if (errorCode != null)
              Padding(
                padding: const EdgeInsets.all(16),
                child: Text(
                  'エラー: ${errorCode?.code}',
                  style: const TextStyle(color: Colors.red),
                ),
              ),

            // メインコンテンツ
            const Expanded(
              child: Center(
                child: Text('メインコンテンツ領域'),
              ),
            ),

            // バナー広告
            Container(
              width: MediaQuery.of(context).size.width,
              height: bannerHeight,
              color: Colors.grey[200],
              child: isLoaded
                  ? bannerView
                  : isLoading
                      ? const Center(child: CircularProgressIndicator())
                      : const Center(child: Text('広告領域')),
            ),
          ],
        ),
      ),
    );
  }
}

バックフィル広告

バックフィル広告が有効な場合、ダイレクト広告がない時に自動的にバックフィル広告がロードされます。バックフィル広告のロードはSDKが自動的に処理します。backfillNoFillエラーコードを使用してバックフィル関連のエラーを処理できます。

bannerView = AdropBannerView(
  unitId: 'YOUR_UNIT_ID',
  listener: AdropBannerListener(
    onAdReceived: (unitId, metadata) {
      debugPrint('広告ロード完了');
      setState(() {
        isLoaded = true;
      });
    },
    onAdFailedToReceive: (unitId, errorCode) {
      switch (errorCode) {
        case AdropErrorCode.adNoFill:
          debugPrint('ダイレクト広告なし');
          break;
        case AdropErrorCode.backfillNoFill:
          debugPrint('バックフィル広告もありません');
          // 広告領域を非表示にする
          break;
        default:
          debugPrint('広告ロード失敗: ${errorCode.code}');
      }
    },
  ),
);

バナー広告のメタデータにはcreativeId、txId、campaignId、destinationURL、browserTargetフィールドのみが含まれます。バックフィル広告はメタデータでは区別できません。backfillNoFillエラーコードを使用してバックフィル広告の失敗を検知できます。

バックフィル広告を使用するには、ネイティブプラットフォームにバックフィル依存性を追加する必要があります。はじめにを参照してください。

バックフィル広告のプリロード (preload)

SDK 1.17.0から、AdropBannerView.preload()でバックフィルバナー広告をプリロードしておくことができます。同じユニットIDと同じサイズでload()したバナーが、ダイレクト広告なしでバックフィル広告に切り替わると、バックフィル広告を再度リクエストせず、プリロードしておいた広告をすぐに表示します。 load()はpreloadに関係なく、まずダイレクト広告をリクエストします。ダイレクト広告が表示された場合、プリロードしておいた広告はそのまま残ります。preloadを呼び出さなければ、動作はこれまでと同じです。

動作条件

adrop_ads_flutter 1.17.0以降と、ネイティブプラットフォームのバックフィル依存性1.17.0以降が必要です。はじめにを参照してください。
現在表示するダイレクト広告がないとサーバーからアプリに通知されている状態でのみ、バックフィル広告を受信します。それ以外の場合は、バックフィル広告をリクエストせずにERROR_CODE_AD_PRELOAD_SKIPPEDで終了します。ダイレクト広告のキャンペーンがあるアプリでは正常な結果です。
アプリのインストール直後、アプリキーを変更した直後、setUIDで別のユーザーに切り替えた直後は、サーバーの応答を受信するまでERROR_CODE_AD_PRELOAD_SKIPPEDで終了します。
テストユニットIDでは常にERROR_CODE_AD_PRELOAD_SKIPPEDで終了します。

使用方法

バナーがある画面を表示する直前に呼び出してください。プリロードした広告は使用されないと30分後に破棄されるため、すぐに表示するバナーに対してのみ呼び出してください。結果を待ってからload()する必要はありません。まだ受信中の場合は、load()がその結果を待って使用します。 preload()はプリロードに成功すると完了し、それ以外の結果（ERROR_CODE_AD_PRELOAD_SKIPPEDを含む）は、codeがエラーコード文字列であるPlatformExceptionとして渡されます。処理しないと、正常な結果であるSKIPPEDも未処理の非同期エラーとして報告されるため、try/catchで囲むか、.catchErrorを付けてください。

import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

// バナーがある画面を表示する直前に呼び出します。
Future<void> preloadFeedBanner() async {
  try {
    await AdropBannerView.preload(
      unitId: 'YOUR_UNIT_ID',
      adSize: const Size(320, 50), // 省略すると320x50
    );
    debugPrint('プリロード完了');
  } on PlatformException catch (e) {
    // ERROR_CODE_AD_PRELOAD_SKIPPEDは正常な結果です。
    // ここでpreloadをすぐに再度呼び出さないでください。
    final errorCode = AdropErrorCode.getByCode(e.code);
    debugPrint('プリロードされませんでした: ${errorCode.code}');
  }
}

結果が不要な場合は、次のように呼び出せます。

AdropBannerView.preload(unitId: 'YOUR_UNIT_ID', adSize: const Size(320, 50))
    .catchError((_) {});

プリロードしておいた広告を使用するには、load()するAdropBannerViewのadSizeを、preloadに渡したサイズと同じに設定してください。

final bannerView = AdropBannerView(unitId: 'YOUR_UNIT_ID');
bannerView.adSize = const Size(320, 50); // preloadに渡したサイズ
bannerView.load();

プリロードした広告が使われる条件

同じユニットIDと同じサイズ: load()するAdropBannerViewのadSizeが、preloadに渡したサイズと同じである必要があります。サイズが異なる場合、プリロードした広告はそのまま残り、load()は通常どおりバックフィル広告をリクエストします。
一度だけ使用: プリロードした広告は、1回のload()で使用されるとなくなります。再度プリロードするには、preloadをもう一度呼び出してください。
有効期間と個数: 30分以内に使用されなかった広告は破棄されます。同じユニット・サイズには1個のみ保持し、バナーは異なるユニット・サイズの組み合わせを最大5個まで保持します。5個を超えると、最も早く受信した広告から破棄します。
再度呼び出す場合: 同じユニット・サイズで再度呼び出しても、新たにリクエストしません。受信済みの広告がある場合は新しいリクエストなしで完了し、受信中の場合はそのロードの結果（成功または失敗）がそのまま伝えられます。広告を更新する用途には使用できません。ただし、その間にユーザーの同意状態が変わった場合は、既存の広告を破棄して新たに受信します。
同意状態の変更: プリロードした後にユーザーの同意状態が変わると、その広告はload()に使用されません。
完了の意味: preload()が完了したということは、プリロードが終わったという意味です。その結果を待っていたload()がすでに使用している場合もあります。

失敗コード

エラーコード	コード文字列	説明
`preloadSkipped`	`ERROR_CODE_AD_PRELOAD_SKIPPED`	ダイレクト広告が表示される可能性があるか、まだ確認されていないため、バックフィル広告をリクエストしませんでした。正常な結果のため、次の画面を表示する直前に再度呼び出してください。
`adNoFill`	`ERROR_CODE_AD_NO_FILL`	1.17.0以降のバックフィル依存性がないか、ユニットにバックフィルが設定されていないか、SDKがその設定をまだ受信していません。しばらくしてから再度呼び出してください。バックフィル依存性がない場合は、引き続きこのコードで終了します。iOSでは、デバイスが対象国に属していない場合もこのコードで終了します。
`backfillNoFill`	`ERROR_CODE_AD_BACKFILL_NO_FILL`	バックフィル広告がありません。
`internal`	`ERROR_CODE_INTERNAL`	リクエストが中断されたか（例：Androidで受信中にActivityが終了した）、内部エラーが発生しました。後で再度呼び出してください。
`initialize`	`ERROR_CODE_INITIALIZE`	SDKが初期化されていません。Androidでは、デバイスが対象国に属していない場合もこのコードで終了します。
`invalidUnit`	`ERROR_CODE_INVALID_UNIT`	ユニットIDが空です。

catch内でpreloadをすぐに再度呼び出さないでください。バックフィル依存性がない場合のように結果が変わらないと、呼び出しが際限なく繰り返されます。次の画面を表示する前など、後で再度呼び出してください。

次のステップ

ネイティブ広告

UIに合わせてカスタマイズ可能なネイティブ広告を実装する

インタースティシャル広告

全画面を覆うインタースティシャル広告を実装する

ポップアップ広告

ポップアップ形式の広告を実装する

リファレンス

タイプ、メソッド、エラーコードを参照する

​概要

​主な特徴

​AdropBannerView

​コンストラクタ

​プロパティ

​メソッド

​基本的な使い方

​AdropBannerListener

​コールバック関数

​コールバックの説明

​メタデータ

​広告サイズ

​一般的なバナーサイズ

​固定サイズの使用

​画面幅に合わせる

​サイズ設定

​エラー処理

​ベストプラクティス

​1. リソースの解放

​2. 広告の更新

​3. 条件付きレンダリング

​4. 複数バナーの管理

​完全な例

​バックフィル広告

​バックフィル広告のプリロード (preload)

​動作条件

​使用方法

​プリロードした広告が使われる条件

​失敗コード

​次のステップ

ネイティブ広告

インタースティシャル広告

ポップアップ広告

リファレンス

概要

主な特徴

AdropBannerView

コンストラクタ

プロパティ

メソッド

基本的な使い方

AdropBannerListener

コールバック関数

コールバックの説明

メタデータ

広告サイズ

一般的なバナーサイズ

固定サイズの使用

画面幅に合わせる

サイズ設定

エラー処理

ベストプラクティス

1. リソースの解放

2. 広告の更新

3. 条件付きレンダリング

4. 複数バナーの管理

完全な例

バックフィル広告

バックフィル広告のプリロード (preload)

動作条件

使用方法

プリロードした広告が使われる条件

失敗コード

次のステップ