ネイティブ広告

実装方法

ネイティブ広告は、アプリのデザインに合わせてカスタムUIで広告を表示できます。

方式	説明	推奨
基本テンプレート	SDK提供テンプレート使用	迅速な実装
カスタムUI	直接UI構成	デザインカスタマイズが必要な場合

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

基本テンプレート

バナー広告と同じ方式で基本テンプレートを使用できます。SDKが提供するテンプレートに画像、テキストが自動的にレンダリングされます。

function NativeAd() {
  return <div data-adrop-unit="YOUR_NATIVE_UNIT_ID" />;
}

基本テンプレートは広告主プロフィールセクションをサポートしていません。広告主プロフィールを表示するには、カスタムUIを使用してください。

カスタムUI

1. Data Attributes方式

data-adrop-render="custom"属性を追加し、内部要素にdata-adrop-native属性でフィールドをバインディングします。

function CustomNativeAd() {
  return (
    <div
      data-adrop-unit="YOUR_NATIVE_UNIT_ID"
      data-adrop-render="custom"
      data-adrop-entire-click="true"
      data-adrop-custom-click="true"  // カスタムクリック処理の有効化
      className="native-ad"
    >
      {/* 広告主プロフィール */}
      <div className="ad-profile">
        <img data-adrop-native="profile.displayLogo" alt="広告主" />
        <span data-adrop-native="profile.displayName"></span>
      </div>

      {/* 広告コンテンツ */}
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="広告" />
      <p data-adrop-native="body"></p>

      {/* 追加テキスト項目 */}
      <span data-adrop-native="extra.price"></span>

      {/* CTAボタン */}
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

Data Attributes

string

必須

Ad Controlコンソールで作成したユニットID

string

必須

カスタムUI使用時はcustomに設定

string

コンテキストターゲティング用Context ID

string

デフォルト:"light"

テーマ設定（lightまたはdark）

boolean

デフォルト:false

全体領域クリックを有効化

false：テキスト/画像のみクリック可能、広告主プロフィールクリック時はプロフィールリンクに移動
true：コンテナ全体クリック可能、すべてのクリックが広告先に移動

boolean

デフォルト:false

カスタムクリック処理の有効化 - trueに設定するとSDKが自動で目的地URLに移動せず、adClickedイベントのみ発生させます。開発者がクリック動作を直接実装できます。

string

広告識別子 — デバイスで表示機能で登録済みテストデバイスからドラフトクリエイティブをプレビューするときに必要です。本番環境にハードコードしないでください。

2. renderAd方式

広告読み込みタイミングを直接制御したい場合に使用します。

import { useEffect, useRef } from 'react';
import { Adrop } from '@adrop/ads-web-sdk';

function CustomNativeAd() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: 'YOUR_NATIVE_UNIT_ID',
        contextId: 'YOUR_CONTEXT_ID',
        theme: 'light',
        trackMode: 1,        // カスタムUI使用時必須
        isEntireClick: true, // 全体領域クリックを有効化
        useCustomClick: true // カスタムクリック処理の有効化
      });
    }

    return () => {
    };
  }, []);

  return (
    <div ref={containerRef} className="native-ad">
      <div className="ad-profile">
        <img data-adrop-native="profile.displayLogo" alt="広告主" />
        <span data-adrop-native="profile.displayName"></span>
      </div>
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="広告" />
      <p data-adrop-native="body"></p>
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

renderAdオプション

string

必須

Ad Controlコンソールで作成したユニットID

string

ユーザー識別子（SDK設定値を個別の広告枠で上書きする場合に使用）

string

コンテキストターゲティング用Context ID

number

必須

カスタムUI使用時は1に設定

boolean

デフォルト:false

全体領域クリックを有効化

string

デフォルト:"light"

テーマ設定（lightまたはdark）

boolean

デフォルト:false

string

フィールドバインディング

data-adrop-native属性で広告データをUI要素にバインディングします。

フィールド	説明	要素タイプ
`profile.displayLogo`	広告主ロゴURL	`<img>`
`profile.displayName`	広告主名	テキスト
`headline`	広告タイトル	テキスト
`body`	広告説明	テキスト
`asset`	メイン画像URL	`<img>`
`callToAction`	CTAボタンテキスト	テキスト
`extra.{key}`	追加テキスト項目	テキスト
`extraAssets.{id}.asset`	メディアの画像URL	`<img>`

extra.{key}はAd Controlコンソールで設定した追加テキスト項目のIDです。必須設定していない場合は空の可能性があります。

extraAssets.{id}は複数メディアユニットのメディアID（例：m2）です。このバインディングは画像のみを表示します。動画を受け付けるユニットの場合は、複数メディアのクリエイティブに従ってメディアを表示してください。（SDK 1.4.0+）

広告主プロフィール（profile.displayLogo、profile.displayName）を表示するには、Ad Controlコンソールで該当広告ユニットの広告主プロフィール表示を有効化する必要があります。

広告サイズ

カスタムUIのサイズは自由に設定できます。

区分	サイズ設定	配置
ダイレクト広告	レスポンシブ対応	水平/垂直中央
バックフィル広告	初期幅合わせ、高さ必須	水平中央

バックフィル広告はコンテナサイズに合う素材をリクエストします。適切なサイズを指定してください。

requestAdでデータのみ取得

UIを完全に直接制御したい場合は、requestAdで広告データのみを取得できます。

import { useState, useEffect } from 'react';
import { Adrop } from '@adrop/ads-web-sdk';

function NativeAd() {
  const [adData, setAdData] = useState<AdData | null>(null);

  useEffect(() => {
    async function loadAd() {
      const adrop = Adrop.instance();

      const response = await adrop.requestAd({
        unit: 'YOUR_NATIVE_UNIT_ID',
        trackMode: 1
      });

      if (response.code === 0 && response.result) {
        setAdData(response.result);
      }
    }

    loadAd();
  }, []);

  if (!adData) return null;

  return (
    <div className="native-ad">
      <div className="ad-header">
        {adData.profile?.displayLogo && (
          <img src={adData.profile.displayLogo} alt="広告主" />
        )}
        <span>{adData.profile?.displayName}</span>
      </div>
      <h3>{adData.headline}</h3>
      {adData.asset && <img src={adData.asset} alt="広告" />}
      <p>{adData.body}</p>
      <a href={adData.destinationURL} target="_blank" rel="noopener noreferrer">
        {adData.callToAction}
      </a>
    </div>
  );
}

requestAd使用時はインプレッション/クリック追跡を直接実装する必要があります。また、この方式ではバックフィル広告はサポートされていません。特別な場合でなければrenderAdを推奨します。

AdropAdResponse

requestAd()の戻り値です。

フィールド	タイプ	説明
`code`	`number`	レスポンスコード（0：成功、4000-4003：エラー）
`msg`	`string`	レスポンスメッセージ
`result`	`AdData`	広告データ（成功時のみ存在）

AdData

広告データオブジェクトです。イベントハンドラーでも同じ構造で渡されます。詳細はリファレンス > AdDataを参照してください。

フィールド	タイプ	説明
`format`	`string`	広告フォーマット（`banner`、`nativeAd`、`backfill`）
`unit`	`string`	ユニットID
`headline`	`string`	広告タイトル
`body`	`string`	広告説明
`callToAction`	`string`	CTAボタンテキスト
`asset`	`string`	メイン画像URL
`destinationURL`	`string`	クリック時の移動先URL
`profile.displayLogo`	`string`	広告主ロゴURL
`profile.displayName`	`string`	広告主名
`profile.link`	`string`	広告主プロフィールリンク
`extra`	`Record<string, string>`	追加テキスト項目
`extraAssets`	`Record<string, AdropNativeAsset>`	メディアIDをキーとするメディア。複数メディアのクリエイティブを参照

カスタムクリック処理

useCustomClickが有効化されるとSDKが自動で目的地URLに移動しません。代わりにクリックイベントを処理してカスタム動作を実装できます。

import { useEffect, useRef } from 'react';
import { Adrop } from '@adrop/ads-web-sdk';

function CustomClickNativeAd({ unitId }: { unitId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();
    const filter = { unit: unitId };

    // カスタム動作で広告クリック処理
    const handleClicked = (unit: string, adData: any) => {
      console.log('広告クリック:', unit);
      console.log('目的地URL:', adData.destinationURL);
      
      // カスタムクリック動作実装
      // 例：SPA内ナビゲーション、モーダル表示、分析追跡など
      if (adData.destinationURL) {
        // カスタムナビゲーションロジック
        window.location.href = adData.destinationURL;
      }
    };

    adrop.on(Adrop.Events.AD_CLICKED, handleClicked, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: unitId,
        trackMode: 1,
        isEntireClick: true,
        useCustomClick: true
      });
    }

    return () => {
      adrop.off(Adrop.Events.AD_CLICKED, handleClicked);
    };
  }, [unitId]);

  return (
    <div ref={containerRef} className="native-ad">
      <div className="ad-profile">
        <img data-adrop-native="profile.displayLogo" alt="広告主" />
        <span data-adrop-native="profile.displayName"></span>
      </div>
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="広告" />
      <p data-adrop-native="body"></p>
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

カスタムクリック処理が有効化されると、ユーザーが広告をクリックしたときの動作を完全に制御できます。destinationURLはadClickedイベントデータに含まれて提供されます。

イベント処理

import { useEffect, useRef } from 'react';
import { Adrop } from '@adrop/ads-web-sdk';

function NativeAd({ unitId }: { unitId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();
    const filter = { unit: unitId };

    const handleReceived = (unit: string, adData: any) => {
      console.log('広告受信:', adData);
    };

    const handleNoFill = (unit: string) => {
      console.warn('広告なし:', unit);
    };

    const handleFailed = (unit: string) => {
      console.error('広告失敗:', unit);
    };

    const handleImpression = (unit: string, adData: any) => {
      console.log('広告表示:', unit);
    };

    const handleClicked = (unit: string, adData: any) => {
      console.log('広告クリック:', unit);
    };

    // 動画再生開始
    const handleVideoStart = (unit: string, adData: any) => {
      console.log('動画開始:', unit);
    };

    // 動画再生完了
    const handleVideoEnd = (unit: string, adData: any) => {
      console.log('動画完了:', unit);
    };

    adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);
    adrop.on(Adrop.Events.AD_NO_FILL, handleNoFill, filter);
    adrop.on(Adrop.Events.AD_FAILED, handleFailed, filter);
    adrop.on(Adrop.Events.AD_IMPRESSION, handleImpression, filter);
    adrop.on(Adrop.Events.AD_CLICKED, handleClicked, filter);
    adrop.on(Adrop.Events.AD_VIDEO_START, handleVideoStart, filter);
    adrop.on(Adrop.Events.AD_VIDEO_END, handleVideoEnd, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: unitId,
        trackMode: 1,
        isEntireClick: true
      });
    }

    return () => {
      adrop.off(Adrop.Events.AD_RECEIVED, handleReceived);
      adrop.off(Adrop.Events.AD_NO_FILL, handleNoFill);
      adrop.off(Adrop.Events.AD_FAILED, handleFailed);
      adrop.off(Adrop.Events.AD_IMPRESSION, handleImpression);
      adrop.off(Adrop.Events.AD_CLICKED, handleClicked);
      adrop.off(Adrop.Events.AD_VIDEO_START, handleVideoStart);
      adrop.off(Adrop.Events.AD_VIDEO_END, handleVideoEnd);
    };
  }, [unitId]);

  return (
    <div ref={containerRef} className="native-ad">
      <div className="ad-profile">
        <img data-adrop-native="profile.displayLogo" alt="広告主" />
        <span data-adrop-native="profile.displayName"></span>
      </div>
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="広告" />
      <p data-adrop-native="body"></p>
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

サポートするイベント

イベント	定数	説明
広告受信	`AD_RECEIVED`	広告リクエスト成功
広告なし	`AD_NO_FILL`	配信可能なダイレクト広告なし
リクエスト失敗	`AD_FAILED`	広告リクエスト失敗
インプレッション	`AD_IMPRESSION`	広告インプレッション記録
クリック	`AD_CLICKED`	ユーザーが広告をクリック
バックフィルなし	`AD_BACKFILL_NO_FILL`	バックフィル広告なし
動画開始	`AD_VIDEO_START`	動画広告の再生開始
動画完了	`AD_VIDEO_END`	動画広告の再生完了

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

@adrop/ads-web-sdk 1.4.0以降が必要です。

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

const media2 = adData.extraAssets?.m2; // AdropNativeAsset | undefined

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

AdropNativeAsset

フィールド	タイプ	説明
`id`	`string`	コンソールで設定したメディアID（例：`m1`、`m2`）
`asset`	`string`	画像または動画ファイルのURL
`ad`	`string`	動画メディアを再生するHTML。トラッキングを含みます
`cover`	`string`	動画のポスター画像URL。画像の場合はなし
`type`	`string`	`'display'`（画像）または`'video'`。ない場合があります
`isVideo`	`boolean`	動画かどうか

メディアの表示

このセクションはカスタムUI（trackMode: 1）を前提としています。

メディア	表示方法	配置
画像	`asset`で`<img>`を表示	広告コンテナの中
動画	`ad`を`<iframe>`に書き込む	広告コンテナの中

画像: 自分で追加した画像のクリックも広告クリックとして集計されるよう、isEntireClick: trueに設定してください。画像はassetで表示してください。trackMode: 1では、画像のad HTMLはクリックをAdropに報告しません。
動画: asset URLではなくad HTMLを<iframe>で再生してください。HTMLに動画プレイヤーとトラッキングが含まれているため、動画指標はこのHTMLでのみ計測されます。<iframe>内のクリックは広告コンテナに伝わらないため、動画のタップはHTMLだけが処理します。<iframe>にsandbox属性は付けないでください。HTMLがスクリプトを実行し、ランディングページを開く必要があります。
ランディングページ: ユーザーが動画をタップすると、HTMLがクリックを報告し、ランディングページを開きます。

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

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

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

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

例

メディア 2（m2）を画像または動画として広告コンテナの中に表示する例です。m2はユニットのメディアIDに置き換えてください。

import { useEffect, useRef, useState } from 'react';
import { Adrop, type AdData, type AdropNativeAsset } from '@adrop/ads-web-sdk';

// 動画メディアを再生します。HTMLが広告のタップと再生も報告します。
function MediaItemVideo({ item }: { item: AdropNativeAsset }) {
  const iframeRef = useRef<HTMLIFrameElement>(null);

  useEffect(() => {
    const doc = iframeRef.current?.contentDocument;
    if (!doc) return;
    doc.open();
    doc.write(
      '<!DOCTYPE html><html><head><meta charset="UTF-8">' +
        '<style>html, body { margin: 0; height: 100%; overflow: hidden; }</style>' +
        `</head><body>${item.ad}</body></html>`
    );
    doc.close();
  }, [item]);

  return (
    <iframe
      ref={iframeRef}
      title="Ad video"
      allow="autoplay"
      style={{ display: 'block', width: '100%', aspectRatio: '16 / 9', border: 0 }}
    />
  );
}

export function MultiMediaNativeAd({ unitId }: { unitId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [media2, setMedia2] = useState<AdropNativeAsset>();

  useEffect(() => {
    const adrop = Adrop.instance();
    const filter = { unit: unitId };

    // メディア 2（m2）。メディアが1つのクリエイティブとバックフィル広告にはない
    const handleReceived = (_unit: string, adData: AdData) => {
      setMedia2(adData.extraAssets?.m2);
    };

    adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, {
        unit: unitId,
        trackMode: 1,
        isEntireClick: true, // 自分で追加したメディアのクリックも広告クリックとして集計
      });
    }

    return () => {
      adrop.off(Adrop.Events.AD_RECEIVED, handleReceived);
    };
  }, [unitId]);

  return (
    <div ref={containerRef} className="native-ad">
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="Ad" />
      {/* メディア 2（m2） */}
      {media2 &&
        (media2.isVideo ? (
          <MediaItemVideo item={media2} />
        ) : (
          <img src={media2.asset} alt="Ad" />
        ))}
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

<iframe>のサイズは、ユニットに設定したメディアのサイズに合わせてください。例は16:9のメディアを想定しています。

バックフィル広告

バックフィル広告が有効な場合、直接広告がないときに自動的にバックフィル広告がリクエストされます。adData.formatで広告タイプを区別できます。

import { useEffect, useRef } from 'react';
import { Adrop } from '@adrop/ads-web-sdk';

function NativeAd({ unitId }: { unitId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const adrop = Adrop.instance();
    const filter = { unit: unitId };

    // 広告受信（直接広告またはバックフィル）
    const handleReceived = (unit: string, adData: any) => {
      if (adData.format === 'backfill') {
        console.log('バックフィル広告がロードされました');
      } else {
        console.log('直接広告がロードされました'); // 'nativeAd'
      }
    };

    // 直接広告なし（バックフィルリクエスト開始）
    const handleNoFill = (unit: string) => {
      console.log('直接広告なし、バックフィル広告をリクエスト中...');
    };

    // バックフィル広告もなし
    const handleBackfillNoFill = (unit: string) => {
      console.warn('バックフィル広告もありません');
      // 広告エリアを非表示にするなどの処理
    };

    adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);
    adrop.on(Adrop.Events.AD_NO_FILL, handleNoFill, filter);
    adrop.on(Adrop.Events.AD_BACKFILL_NO_FILL, handleBackfillNoFill, filter);

    if (containerRef.current) {
      adrop.renderAd(containerRef.current, { unit: unitId });
    }

    return () => {
      adrop.off(Adrop.Events.AD_RECEIVED, handleReceived);
      adrop.off(Adrop.Events.AD_NO_FILL, handleNoFill);
      adrop.off(Adrop.Events.AD_BACKFILL_NO_FILL, handleBackfillNoFill);
    };
  }, [unitId]);

  return (
    <div ref={containerRef}>
      <h3 data-adrop-native="headline"></h3>
      <img data-adrop-native="asset" alt="広告" />
      <p data-adrop-native="body"></p>
      <button data-adrop-native="callToAction"></button>
    </div>
  );
}

開発環境テスト: アプリに連携された広告ユニットのうち少なくとも1つが収益化中であれば、localhostからでもバックフィル広告のリクエストが可能です。承認されていないドメインでは AD_BACKFILL_NO_FILL イベントが発生します。

SDKガイド

AI

Android

iOS

React Native

Flutter

Web

REST API

実装方法

基本テンプレート

カスタムUI

1. Data Attributes方式

Data Attributes

2. renderAd方式

renderAdオプション

フィールドバインディング

広告サイズ

requestAdでデータのみ取得

AdropAdResponse

AdData

カスタムクリック処理

イベント処理

サポートするイベント

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

AdropNativeAsset

メディアの表示

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

例

バックフィル広告

​実装方法

​基本テンプレート

​カスタムUI

​1. Data Attributes方式

​Data Attributes

​2. renderAd方式

​renderAdオプション

​フィールドバインディング

​広告サイズ

​requestAdでデータのみ取得

​AdropAdResponse

​AdData

​カスタムクリック処理

​イベント処理

​サポートするイベント

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

​AdropNativeAsset

​メディアの表示

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

​例

​バックフィル広告

実装方法

基本テンプレート

カスタムUI

1. Data Attributes方式

Data Attributes

2. renderAd方式

renderAdオプション

フィールドバインディング

広告サイズ

requestAdでデータのみ取得

AdropAdResponse

AdData

カスタムクリック処理

イベント処理

サポートするイベント

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

AdropNativeAsset

メディアの表示

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

例

バックフィル広告