ネイティブ広告 - Ad Control Help Center

概要

ネイティブ広告は、アプリのコンテンツと自然に調和するようにカスタマイズできる広告です。AdropNativeAdとAdropNativeAdViewを使用して、アプリのUIに合わせて広告を構成できます。

主な特徴

アプリデザインに合わせたカスタムレイアウト構成が可能
ヘッドライン、本文、CTAボタン、プロフィールなど様々な要素を提供
画像およびHTMLクリエイティブをサポート
カスタムクリック処理をサポート
バックフィル広告をサポート

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

AdropNativeAd

コンストラクタ

AdropNativeAd({
  required String unitId,
  String? contextId,
  bool useCustomClick = false,
  AdropAdChoicesPosition preferredAdChoicesPosition = AdropAdChoicesPosition.topRight,
  AdropNativeListener? listener,
})

パラメータ

パラメータ	タイプ	必須	説明
`unitId`	`String`	Y	Ad Controlコンソールで作成したユニットID
`contextId`	`String`	N	コンテキストターゲティングに使用するコンテキストID（1.17.0+）
`useCustomClick`	`bool`	N	カスタムクリック処理を使用するかどうか（デフォルト: `false`）
`preferredAdChoicesPosition`	`AdropAdChoicesPosition`	N	バックフィルネイティブ広告のAdChoicesマーク表示位置（デフォルト: `AdropAdChoicesPosition.topRight`）
`listener`	`AdropNativeListener`	N	広告イベントリスナー

プロパティ

プロパティ	タイプ	説明
`isLoaded`	`bool`	広告のロード完了状態
`unitId`	`String`	広告ユニットID
`contextId`	`String?`	コンストラクタに渡したコンテキストID
`creativeId`	`String`	クリエイティブID
`txId`	`String`	トランザクションID
`campaignId`	`String`	キャンペーンID
`destinationURL`	`String`	遷移先URL
`properties`	`AdropNativeProperties`	ネイティブ広告プロパティ
`creativeSize`	`CreativeSize`	クリエイティブサイズ
`isBackfilled`	`bool`	バックフィル広告かどうか
`browserTarget`	`BrowserTarget?`	ブラウザターゲット（外部または内部）

メソッド

メソッド	戻り値の型	説明
`load()`	`Future<void>`	広告をロードします
`dispose()`	`Future<void>`	ネイティブWebViewおよびバックフィル広告の場合はAdMobネイティブ広告を解放します

ネイティブ広告を表示しなくなったらdispose()を呼び出してください。呼び出さない場合、ネイティブWebViewがリークし、フィード形式の画面でOOMを引き起こす可能性があります。

dispose()済みのAdropNativeAdは再利用できません。別の広告をリクエストするには、新しいAdropNativeAdインスタンスを作成してください。

@override
void dispose() {
  _nativeAd?.dispose();
  super.dispose();
}

AdropNativeAdView

ネイティブ広告を画面に表示するウィジェットです。

コンストラクタ

AdropNativeAdView({
  required AdropNativeAd? ad,
  required Widget child,
})

パラメータ

パラメータ	タイプ	必須	説明
`ad`	`AdropNativeAd?`	Y	ロードされたネイティブ広告オブジェクト
`child`	`Widget`	Y	広告コンテンツを表示する子ウィジェット

AdropNativeProperties

ネイティブ広告のコンテンツプロパティです。

プロパティ

プロパティ	タイプ	説明
`headline`	`String?`	広告タイトル
`body`	`String?`	広告本文
`creative`	`String?`	HTMLクリエイティブコンテンツ
`asset`	`String?`	画像アセットURL
`destinationURL`	`String?`	クリック時の遷移先URL
`callToAction`	`String?`	CTAボタンテキスト
`profile`	`AdropNativeProfile?`	広告主プロフィール情報
`extra`	`Map<String, String>`	追加のカスタムフィールド
`extraAssets`	`Map<String, AdropNativeAsset>`	メディアIDをキーとするメディア。複数メディアのクリエイティブを参照
`isBackfilled`	`bool`	バックフィル広告かどうか

AdropNativeProfile

プロパティ	タイプ	説明
`displayName`	`String?`	広告主名
`displayLogo`	`String?`	広告主ロゴ画像URL

基本的な使い方

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

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

  @override
  State<NativeAdExample> createState() => _NativeAdExampleState();
}

class _NativeAdExampleState extends State<NativeAdExample> {
  bool isLoaded = false;
  AdropNativeAd? nativeAd;

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

  @override
  void dispose() {
    nativeAd?.dispose();
    nativeAd = null;
    super.dispose();
  }

  void _createNativeAd() {
    nativeAd = AdropNativeAd(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropNativeListener(
        onAdReceived: (ad) {
          debugPrint('ネイティブ広告受信成功: ${ad.creativeId}');
          setState(() {
            isLoaded = true;
          });
        },
        onAdClicked: (ad) {
          debugPrint('ネイティブ広告クリック: ${ad.creativeId}');
        },
        onAdImpression: (ad) {
          debugPrint('ネイティブ広告表示: ${ad.creativeId}');
        },
        onAdFailedToReceive: (ad, errorCode) {
          debugPrint('ネイティブ広告受信失敗: $errorCode');
          setState(() {
            isLoaded = false;
          });
        },
      ),
    );

    // 広告をロード
    nativeAd?.load();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('ネイティブ広告サンプル')),
      body: SingleChildScrollView(
        child: Column(
          children: [
            // メインコンテンツ
            const Padding(
              padding: EdgeInsets.all(16),
              child: Text('メインコンテンツ'),
            ),
            // ネイティブ広告
            if (isLoaded) _buildNativeAdView(),
          ],
        ),
      ),
    );
  }

  Widget _buildNativeAdView() {
    return AdropNativeAdView(
      ad: nativeAd,
      child: Container(
        padding: const EdgeInsets.all(16),
        margin: const EdgeInsets.all(16),
        decoration: BoxDecoration(
          border: Border.all(color: Colors.grey),
          borderRadius: BorderRadius.circular(8),
        ),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            // 広告主プロフィール
            if (nativeAd?.properties.profile != null)
              Row(
                children: [
                  if (nativeAd?.properties.profile?.displayLogo != null)
                    Image.network(
                      nativeAd!.properties.profile!.displayLogo!,
                      width: 24,
                      height: 24,
                    ),
                  const SizedBox(width: 8),
                  Text(nativeAd?.properties.profile?.displayName ?? ''),
                ],
              ),
            const SizedBox(height: 8),
            // ヘッドライン
            if (nativeAd?.properties.headline != null)
              Text(
                nativeAd!.properties.headline!,
                style: const TextStyle(
                  fontSize: 18,
                  fontWeight: FontWeight.bold,
                ),
              ),
            const SizedBox(height: 4),
            // 本文
            if (nativeAd?.properties.body != null)
              Text(nativeAd!.properties.body!),
            const SizedBox(height: 8),
            // 画像アセット
            if (nativeAd?.properties.asset != null)
              Image.network(
                nativeAd!.properties.asset!,
                width: double.infinity,
                fit: BoxFit.cover,
              ),
            const SizedBox(height: 8),
            // CTAボタン
            if (nativeAd?.properties.callToAction != null)
              ElevatedButton(
                onPressed: () {},
                child: Text(nativeAd!.properties.callToAction!),
              ),
          ],
        ),
      ),
    );
  }
}

AdropNativeListener

ネイティブ広告イベントを処理するリスナーです。

コールバック関数

AdropNativeListener(
  onAdReceived: (AdropNativeAd ad) {
    // 広告受信成功
  },
  onAdClicked: (AdropNativeAd ad) {
    // 広告クリック
  },
  onAdImpression: (AdropNativeAd ad) {
    // 広告表示
  },
  onAdFailedToReceive: (AdropNativeAd ad, AdropErrorCode errorCode) {
    // 広告受信失敗
  },
  onAdVideoStart: (AdropNativeAd ad) {
    // 動画広告の再生開始
  },
  onAdVideoEnd: (AdropNativeAd ad) {
    // 動画広告の再生終了
  },
)

コールバックの説明

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

カスタムクリック処理

動画クリエイティブやカスタムクリック動作が必要な場合はuseCustomClickを使用します。

nativeAd = AdropNativeAd(
  unitId: 'YOUR_UNIT_ID',
  useCustomClick: true, // カスタムクリックを有効化
  listener: AdropNativeListener(
    onAdReceived: (ad) {
      setState(() {
        isLoaded = true;
      });
    },
    onAdClicked: (ad) {
      // カスタムクリック動作を処理
      debugPrint('広告クリック: ${ad.destinationURL}');
    },
  ),
);

useCustomClickがtrueの場合、子ウィジェットのクリックイベントが広告クリックとして処理されます。

HTMLクリエイティブの表示

ネイティブ広告にHTMLクリエイティブが含まれている場合、WebViewを使用して表示できます。

ネイティブ広告の動画クリエイティブは、必ずproperties.creative（HTMLペイロード）をWebViewでレンダリングする必要があります。properties.assetをvideo_playerなどの独自プレイヤーに直接渡すと、SDKの動画トラッキングパイプラインを経由しなくなり、VTRが計測されず、onAdVideoStart / onAdVideoEndコールバックも呼び出されません。動画トラッキングとVTRセクションを参照してください。

import 'package:webview_flutter/webview_flutter.dart';

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

  @override
  State<NativeWithWebView> createState() => _NativeWithWebViewState();
}

class _NativeWithWebViewState extends State<NativeWithWebView> {
  bool isLoaded = false;
  AdropNativeAd? nativeAd;
  late final WebViewController webViewController;

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

    // WebViewコントローラーの初期化
    webViewController = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted);

    _createNativeAd();
  }

  void _createNativeAd() {
    nativeAd = AdropNativeAd(
      unitId: 'YOUR_UNIT_ID',
      useCustomClick: true,
      listener: AdropNativeListener(
        onAdReceived: (ad) {
          // HTMLクリエイティブをロード
          if (ad.properties.creative != null) {
            webViewController.loadHtmlString(ad.properties.creative!);
          }
          setState(() {
            isLoaded = true;
          });
        },
      ),
    );

    nativeAd?.load();
  }

  @override
  Widget build(BuildContext context) {
    if (!isLoaded) return const SizedBox.shrink();

    return AdropNativeAdView(
      ad: nativeAd,
      child: Container(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            // プロフィール
            Row(
              children: [
                if (nativeAd?.properties.profile?.displayLogo != null)
                  Image.network(
                    nativeAd!.properties.profile!.displayLogo!,
                    width: 24,
                    height: 24,
                  ),
                const SizedBox(width: 8),
                Text(nativeAd?.properties.profile?.displayName ?? ''),
              ],
            ),
            const SizedBox(height: 8),
            // ヘッドライン
            if (nativeAd?.properties.headline != null)
              Text(
                nativeAd!.properties.headline!,
                style: const TextStyle(
                  fontSize: 18,
                  fontWeight: FontWeight.bold,
                ),
              ),
            const SizedBox(height: 8),
            // HTMLクリエイティブ
            SizedBox(
              width: MediaQuery.of(context).size.width,
              height: 300,
              child: WebViewWidget(controller: webViewController),
            ),
            // CTAボタン
            if (nativeAd?.properties.callToAction != null)
              Padding(
                padding: const EdgeInsets.only(top: 8),
                child: ElevatedButton(
                  onPressed: () {},
                  child: Text(nativeAd!.properties.callToAction!),
                ),
              ),
          ],
        ),
      ),
    );
  }
}

HTMLクリエイティブを使用するには、webview_flutterパッケージを追加する必要があります。

flutter pub add webview_flutter

バックフィル広告の処理

ネイティブ広告がバックフィル広告の場合、isBackfilledプロパティで確認して処理できます。

Widget _buildCreativeView() {
  if (nativeAd?.isBackfilled == true) {
    // バックフィル広告: 画像アセットを使用
    return Image.network(
      nativeAd?.properties.asset ?? '',
      width: double.infinity,
      fit: BoxFit.cover,
      loadingBuilder: (context, child, loadingProgress) {
        if (loadingProgress == null) return child;
        return const Center(child: CircularProgressIndicator());
      },
      errorBuilder: (context, error, stackTrace) {
        return const Icon(Icons.error);
      },
    );
  } else if (nativeAd?.properties.creative != null) {
    // 通常広告: HTMLクリエイティブを使用
    return SizedBox(
      width: double.infinity,
      height: 300,
      child: WebViewWidget(controller: webViewController),
    );
  } else {
    return const SizedBox.shrink();
  }
}

AdChoicesの位置調整

バックフィルネイティブ広告で、AdChoicesマークを表示するコーナーを指定できます。AdropNativeAdコンストラクタでpreferredAdChoicesPositionを設定してください。

final nativeAd = AdropNativeAd(
  unitId: 'YOUR_UNIT_ID',
  preferredAdChoicesPosition: AdropAdChoicesPosition.bottomRight,
  listener: AdropNativeListener(
    onAdReceived: (ad) => debugPrint('受信完了'),
    onAdFailedToReceive: (ad, errorCode) => debugPrint('失敗: $errorCode'),
  ),
);

await nativeAd.load();

値	説明
`AdropAdChoicesPosition.topLeft`	左上
`AdropAdChoicesPosition.topRight`	右上（デフォルト）
`AdropAdChoicesPosition.bottomLeft`	左下
`AdropAdChoicesPosition.bottomRight`	右下

この設定はバックフィルネットワークに渡される希望位置のヒントで、バックフィルネイティブ広告にのみ適用されます — ダイレクト広告には影響しません。バックフィルネットワークがポリシー上別の位置に表示する場合があります。

動画トラッキングとVTR

Adropはネイティブ広告の動画指標 — VTR（動画完了率）、onAdVideoStart、onAdVideoEnd — を、SDKメディアコンテナ内で動画がレンダリングされる場合にのみ収集します。FlutterではHTMLクリエイティブの表示セクションのように、properties.creative（HTMLペイロード）をWebViewでレンダリングする方式がこれに該当します。これは広告のメインメディア（メディア 1）に当てはまります。複数メディアのクリエイティブのそれ以外のメディアについては、複数メディアのクリエイティブを参照してください。 properties.assetフィールドは元の画像または動画ファイルのURLを返します。これはサムネイル表示や媒体社独自分析などの補助メタデータとして公開されており、再生を直接行うためのものではありません。

動画ネイティブ広告のproperties.asset URLを独自の動画プレイヤー（video_player、chewieまたはサードパーティプレイヤー）に直接渡さないでください。SDKメディアコンテナを経由しないと以下の現象が発生します。

該当面でVTR（動画完了率）が収集されません。
onAdVideoStart / onAdVideoEndコールバックが呼び出されません。
該当ユニットの動画パフォーマンス集計が欠落または0として報告されます。

クリック（onAdClicked）とインプレッション（onAdImpression）トラッキングはAdropNativeAdViewに接続されているため引き続き動作しますが、動画関連シグナルは失われます。

推奨パターン

動画クリエイティブはWebView + HTMLクリエイティブパターンを使用してください。

if (ad.properties.creative != null) {
  webViewController.loadHtmlString(ad.properties.creative!);
}

WebViewをAdropNativeAdView内部に配置し、クリックとインプレッショントラッキングが広告コンテナに接続されたまま維持されるようにしてください。

特定の面がどうしても独自プレイヤーを使う必要があり、VTRが計測されないことを許容する場合、広告をAdropNativeAdViewにバインドしたままにすることで、クリックとインプレッションのアトリビューションは引き続き確保できます。ただしその面を社内レポートで非VTRインベントリとして分類し、SDKが計測した動画パフォーマンスと混在させないでください。

追加フィールドの使用

媒体社が定義した追加フィールドはextraマップからアクセスできます。

onAdReceived: (ad) {
  // 追加フィールドにアクセス
  final customField = ad.properties.extra['customFieldKey'];
  if (customField != null) {
    debugPrint('カスタムフィールド: $customField');
  }

  setState(() {
    isLoaded = true;
  });
}

複数メディアのクリエイティブ

adrop_ads_flutter 1.16.0以降が必要です。バックフィルを使う場合は、バックフィルモジュールも1.16.0に更新してください。

ネイティブユニットにメディアが2つ以上ある場合、クリエイティブにはメディアごとのファイルが含まれます。properties.extraAssetsには、広告のすべてのメディアがコンソールで設定したメディアIDをキーとして格納されています。メディア 1は常にm1で、それ以外のメディアには広告ユニット詳細画面のメディアサイズに表示されるID（例：m2、m3）が使われます。

final media2 = ad.properties.extraAssets['m2']; // AdropNativeAsset?

メディア 1（m1）はproperties.asset、properties.creativeと同じメディアです。これまでどおり表示し、それ以外のメディアだけを自分で描画してください。
メディアが1つのユニットのクリエイティブとバックフィル広告では、extraAssetsは空です。これらの広告は通常どおり表示してください。
メディアは順序に頼らず、IDで取得してください。
広告がダークモードで配信される場合、画像メディアもダークモード用の画像になります。
複数メディアのクリエイティブでレイアウトを確認するには、テストデバイスでクリエイティブをプレビューしてください。

AdropNativeAsset

プロパティ	タイプ	説明
`id`	`String`	コンソールで設定したメディアID（例：`m1`、`m2`）
`asset`	`String`	画像または動画ファイルのURL
`creative`	`String`	動画メディアを再生するHTML。トラッキングを含みます
`cover`	`String?`	動画のポスター画像URL。画像の場合は`null`
`type`	`String?`	`'display'`（画像）または`'video'`
`isVideo`	`bool`	動画かどうか

メディアの表示

メディア	表示方法	配置
画像	`asset`を`Image.network`で表示	`AdropNativeAdView`の中
動画	`creative`を`WebViewWidget`に読み込む	`AdropNativeAdView`の外（例：すぐ下）

画像: useCustomClickの設定にかかわらず、AdropNativeAdView内のウィジェットのタップは広告クリックになるため、その中に置いた画像のタップも、広告のほかの部分と同じように集計されます。画像のcreative HTMLはクリックをAdropに報告しないため、読み込まないでください。
動画: asset URLではなくcreative HTMLを再生してください。HTMLに動画プレイヤーとトラッキングが含まれているため、動画指標はこのHTMLでのみ計測されます。WebViewWidgetはAdropNativeAdViewの外に配置してください。中に置くと、プレイヤーのコントロールのタップを含むすべてのタップが広告クリックになります。HTMLは事前に読み込まず、広告が画面に表示される直前に読み込んでください。
ランディングページ: ユーザーが動画をタップすると、HTMLがクリックを報告し、ランディングページを新しいウィンドウまたは同じウィンドウで開くよう要求します。どちらの要求もonNavigationRequestに届くため、そこで要求されたURLを開いてください。

インプレッションとクリック

インプレッション、クリック、動画指標は、SDKとメディアの両方が報告しても、メディア単位ではなく広告ごとに1回だけ集計されます。

イベント	集計方法
インプレッション	`AdropNativeAdView`が50%以上表示された状態が0.5秒続いたとき。動画メディアも、動画の再生が始まると広告のインプレッションを報告します。
`AdropNativeAdView`内のクリック	SDKが集計し、`onAdClicked`が呼び出されます。
動画メディアのタップ	メディアのHTMLが報告します。`onAdClicked`は呼び出されません。
動画の再生（有効視聴数、視聴完了数）	メディアのHTMLが報告します。`onAdVideoStart`と`onAdVideoEnd`は呼び出されません。

動画のどのタップがクリックとして集計されるかは、ユニットの動画コントローラー設定によって異なります。コントローラーがオフの場合は動画のすべてのタップがクリックになり、オンの場合は再生・ミュートのコントロールのタップはクリックになりません。

例

メディア 2（m2）が画像の場合はAdropNativeAdViewの中に、動画の場合はそのすぐ下に表示する例です。m2はユニットのメディアIDに置き換えてください。先にWebViewとURL Launcherのパッケージを追加してください。

flutter pub add webview_flutter webview_flutter_android webview_flutter_wkwebview url_launcher

import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';
import 'package:flutter/material.dart';
import 'package:url_launcher/url_launcher.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'package:webview_flutter_android/webview_flutter_android.dart';
import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart';

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

  @override
  State<MultiMediaNativeAd> createState() => _MultiMediaNativeAdState();
}

class _MultiMediaNativeAdState extends State<MultiMediaNativeAd> {
  AdropNativeAd? _nativeAd;
  WebViewController? _creativeController;
  AdropNativeAsset? _media2;
  WebViewController? _media2VideoController;

  @override
  void initState() {
    super.initState();
    _nativeAd = AdropNativeAd(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropNativeListener(
        onAdReceived: (ad) {
          final properties = ad.properties;
          // メディア 2（m2）。メディアが1つのクリエイティブとバックフィル広告にはない
          final media2 = properties.extraAssets['m2'];
          setState(() {
            // メディア 1（m1）は既存のcreative
            _creativeController = _webViewController(properties.creative ?? '');
            _media2 = media2;
            _media2VideoController = media2 != null && media2.isVideo
                ? _webViewController(media2.creative, opensLanding: true)
                : null;
          });
        },
      ),
    );
    _nativeAd?.load();
  }

  WebViewController _webViewController(String html, {bool opensLanding = false}) {
    final PlatformWebViewControllerCreationParams params =
        WebViewPlatform.instance is WebKitWebViewPlatform
            ? WebKitWebViewControllerCreationParams(
                allowsInlineMediaPlayback: true,
                mediaTypesRequiringUserAction: const <PlaybackMediaTypes>{},
              )
            : const PlatformWebViewControllerCreationParams();
    final controller = WebViewController.fromPlatformCreationParams(params)
      ..setJavaScriptMode(JavaScriptMode.unrestricted);
    if (opensLanding) {
      controller.setNavigationDelegate(NavigationDelegate(
        onNavigationRequest: (request) {
          // HTML自体（about:blank）はそのまま読み込む
          if (!request.isMainFrame || request.url == 'about:blank') {
            return NavigationDecision.navigate;
          }
          // 動画のタップ: HTMLがクリックを報告し、ランディングページを開くよう要求
          launchUrl(Uri.parse(request.url), mode: LaunchMode.externalApplication);
          return NavigationDecision.prevent;
        },
      ));
    }
    final platform = controller.platform;
    if (platform is AndroidWebViewController) {
      platform.setMediaPlaybackRequiresUserGesture(false);
    }
    controller.loadHtmlString(html);
    return controller;
  }

  @override
  void dispose() {
    _nativeAd?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final ad = _nativeAd;
    final creativeController = _creativeController;
    if (ad == null || creativeController == null) return const SizedBox.shrink();

    final properties = ad.properties;
    final media2 = _media2;
    final media2VideoController = _media2VideoController;

    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        AdropNativeAdView(
          ad: ad,
          child: Padding(
            padding: const EdgeInsets.all(16),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(properties.headline ?? ''),
                SizedBox(
                  height: 200,
                  child: WebViewWidget(controller: creativeController),
                ),
                // メディア 2（m2）が画像の場合: AdropNativeAdViewの中
                if (media2 != null && !media2.isVideo)
                  Image.network(media2.asset, width: 120, height: 120),
                ElevatedButton(
                  onPressed: () {},
                  child: Text(properties.callToAction ?? ''),
                ),
              ],
            ),
          ),
        ),
        // メディア 2（m2）が動画の場合: AdropNativeAdViewの外
        if (media2VideoController != null)
          SizedBox(
            height: 200,
            child: WebViewWidget(controller: media2VideoController),
          ),
      ],
    );
  }
}

エラー処理

バックフィル関連エラー

バックフィル広告が設定されている場合、直接広告とバックフィル広告の両方がない場合はbackfillNoFillエラーコードが返されます。

onAdFailedToReceive: (ad, errorCode) {
  if (errorCode == AdropErrorCode.backfillNoFill) {
    debugPrint('バックフィル広告もありません');
  }
}

一般的なエラー処理

class _NativeAdState extends State<NativeAdWidget> {
  bool isLoaded = false;
  AdropErrorCode? errorCode;
  AdropNativeAd? nativeAd;

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

    nativeAd = AdropNativeAd(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropNativeListener(
        onAdReceived: (ad) {
          setState(() {
            isLoaded = true;
            errorCode = null;
          });
        },
        onAdFailedToReceive: (ad, error) {
          // バックフィル関連エラー処理
          if (error == AdropErrorCode.backfillNoFill) {
            debugPrint('バックフィル広告もありません');
          }

          setState(() {
            isLoaded = false;
            errorCode = error;
          });
        },
      ),
    );

    nativeAd?.load();
  }

  @override
  Widget build(BuildContext context) {
    if (isLoaded) {
      return _buildNativeAdView();
    } else if (errorCode != null) {
      return Text('広告ロード失敗: ${errorCode?.code}');
    } else {
      return const SizedBox.shrink();
    }
  }

  Widget _buildNativeAdView() {
    // ネイティブ広告UIの構成
    return AdropNativeAdView(
      ad: nativeAd,
      child: Container(
        // ...
      ),
    );
  }
}

ベストプラクティス

1. 広告の再生成

新しい広告をロードするには、新しいAdropNativeAdインスタンスを生成します。

void resetAd() {
  setState(() {
    isLoaded = false;
  });

  nativeAd = AdropNativeAd(
    unitId: 'YOUR_UNIT_ID',
    listener: AdropNativeListener(
      onAdReceived: (ad) {
        setState(() {
          isLoaded = true;
        });
      },
    ),
  );

  nativeAd?.load();
}

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

広告がロードされるまで適切なプレースホルダーを表示します。

Widget buildNativeAd() {
  if (isLoaded && nativeAd != null) {
    return _buildNativeAdView();
  } else if (isLoading) {
    return const SizedBox(
      height: 200,
      child: Center(child: CircularProgressIndicator()),
    );
  } else {
    return const SizedBox.shrink();
  }
}

3. レスポンシブレイアウト

様々な画面サイズに対応できるようにレイアウトを構成します。

Widget _buildNativeAdView() {
  return AdropNativeAdView(
    ad: nativeAd,
    child: LayoutBuilder(
      builder: (context, constraints) {
        return Container(
          width: constraints.maxWidth,
          padding: const EdgeInsets.all(16),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              // 広告コンテンツ
            ],
          ),
        );
      },
    ),
  );
}

4. 広告プロパティのnullチェック

ネイティブ広告プロパティはnullの可能性があるため、常に確認します。

Widget _buildHeadline() {
  final headline = nativeAd?.properties.headline;
  if (headline == null || headline.isEmpty) {
    return const SizedBox.shrink();
  }
  return Text(
    headline,
    style: const TextStyle(
      fontSize: 18,
      fontWeight: FontWeight.bold,
    ),
  );
}

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

SDK 1.17.0から、AdropNativeAd.preload()でバックフィルネイティブ広告をプリロードしておくことができます。同じユニットIDと同じAdChoicesの位置で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> preloadFeedNativeAd() async {
  try {
    await AdropNativeAd.preload(
      unitId: 'YOUR_UNIT_ID',
      preferredAdChoicesPosition: AdropAdChoicesPosition.topRight, // デフォルト値
    );
    debugPrint('プリロード完了');
  } on PlatformException catch (e) {
    // ERROR_CODE_AD_PRELOAD_SKIPPEDは正常な結果です。
    // ここでpreloadをすぐに再度呼び出さないでください。
    final errorCode = AdropErrorCode.getByCode(e.code);
    debugPrint('プリロードされませんでした: ${errorCode.code}');
  }
}

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

AdropNativeAd.preload(unitId: 'YOUR_UNIT_ID').catchError((_) {});

プリロードしておいた広告を使用するには、load()するAdropNativeAdを、preloadに渡した値と同じpreferredAdChoicesPositionで作成してください。どちらもデフォルト値はAdropAdChoicesPosition.topRightです。

final nativeAd = AdropNativeAd(
  unitId: 'YOUR_UNIT_ID',
  preferredAdChoicesPosition: AdropAdChoicesPosition.topRight, // preloadに渡した値
  listener: AdropNativeListener(
    onAdReceived: (ad) => debugPrint('受信完了'),
    onAdFailedToReceive: (ad, errorCode) => debugPrint('失敗: $errorCode'),
  ),
);

await nativeAd.load();

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

同じユニットIDと同じAdChoicesの位置: AdChoicesの位置はバックフィル広告を受信するときに決まるため、load()する広告のpreferredAdChoicesPositionが、preloadに渡した値と同じである必要があります。異なる場合、プリロードした広告はそのまま残り、load()は通常どおりバックフィル広告をリクエストします。
一度だけ使用: プリロードした広告は、1回のload()で使用されるとなくなります。再度プリロードするには、preloadをもう一度呼び出してください。
有効期間と個数: 30分以内に使用されなかった広告は破棄されます。同じユニット・AdChoicesの位置には1個のみ保持し、ネイティブ広告は異なる組み合わせを最大5個まで保持します。5個を超えると、最も早く受信した広告から破棄します。
再度呼び出す場合: 同じユニット・AdChoicesの位置で再度呼び出しても、新たにリクエストしません。受信済みの広告がある場合は新しいリクエストなしで完了し、受信中の場合はそのロードの結果（成功または失敗）がそのまま伝えられます。広告を更新する用途には使用できません。ただし、その間にユーザーの同意状態が変わった場合は、既存の広告を破棄して新たに受信します。
同意状態の変更: プリロードした後にユーザーの同意状態が変わると、その広告は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をすぐに再度呼び出さないでください。バックフィル依存性がない場合のように結果が変わらないと、呼び出しが際限なく繰り返されます。次の画面を表示する前など、後で再度呼び出してください。

次のステップ

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

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

リワード広告

報酬を提供するリワード広告を実装する

ポップアップ広告

ポップアップ形式で表示される広告を実装する

リファレンス

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

​概要

​主な特徴

​AdropNativeAd

​コンストラクタ

​プロパティ

​メソッド

​AdropNativeAdView

​コンストラクタ

​AdropNativeProperties

​プロパティ

​AdropNativeProfile

​基本的な使い方

​AdropNativeListener

​コールバック関数

​コールバックの説明

​カスタムクリック処理

​HTMLクリエイティブの表示

​バックフィル広告の処理

​AdChoicesの位置調整

​動画トラッキングとVTR

​推奨パターン

​追加フィールドの使用

​複数メディアのクリエイティブ

​AdropNativeAsset

​メディアの表示

​インプレッションとクリック

​例

​エラー処理

​バックフィル関連エラー

​一般的なエラー処理

​ベストプラクティス

​1. 広告の再生成

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

​3. レスポンシブレイアウト

​4. 広告プロパティのnullチェック

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

​動作条件

​使用方法

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

​失敗コード

​次のステップ

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

リワード広告

ポップアップ広告

リファレンス

概要

主な特徴

AdropNativeAd

コンストラクタ

プロパティ

メソッド

AdropNativeAdView

コンストラクタ

AdropNativeProperties

プロパティ

AdropNativeProfile

基本的な使い方

AdropNativeListener

コールバック関数

コールバックの説明

カスタムクリック処理

HTMLクリエイティブの表示

バックフィル広告の処理

AdChoicesの位置調整

動画トラッキングとVTR

推奨パターン

追加フィールドの使用

複数メディアのクリエイティブ

AdropNativeAsset

メディアの表示

インプレッションとクリック

例

エラー処理

バックフィル関連エラー

一般的なエラー処理

ベストプラクティス

1. 広告の再生成

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

3. レスポンシブレイアウト

4. 広告プロパティのnullチェック

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

動作条件

使用方法

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

失敗コード

次のステップ