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

# ネイティブ広告

> CDN方式でネイティブ広告を実装する方法をご案内します。

## 実装方法

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

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

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

***

## 基本テンプレート

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

```html theme={null}
<div data-adrop-unit="YOUR_NATIVE_UNIT_ID"></div>
```

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

***

## カスタムUI

### Data Attributes方式

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

```html theme={null}
<div
  data-adrop-unit="YOUR_NATIVE_UNIT_ID"
  data-adrop-render="custom"
  data-adrop-entire-click="true"
  data-adrop-custom-click="true"
  class="native-ad">

  <!-- 広告主プロフィール -->
  <div class="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

<ParamField body="data-adrop-unit" type="string" required>
  Ad Controlコンソールで作成したユニットID
</ParamField>

<ParamField body="data-adrop-render" type="string" required>
  カスタムUI使用時は`custom`に設定
</ParamField>

<ParamField body="data-adrop-context-id" type="string">
  コンテキストターゲティング用Context ID
</ParamField>

<ParamField body="data-adrop-theme" type="string" default="light">
  テーマ設定（`light`または`dark`）
</ParamField>

<ParamField body="data-adrop-entire-click" type="boolean" default={false}>
  全体領域クリックを有効化

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

<ParamField body="data-adrop-custom-click" type="boolean" default={false}>
  カスタムクリック処理の有効化 - `true`に設定するとSDKが自動で目的地URLに移動せず、`adClicked`イベントのみ発生させます。開発者がクリック動作を直接実装できます。
</ParamField>

<ParamField body="data-adrop-ad-id" type="string">
  広告識別子 — **デバイスで表示**機能で登録済みテストデバイスからドラフトクリエイティブをプレビューするときに必要です。本番環境にハードコードしないでください。
</ParamField>

### renderAd方式

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

```html theme={null}
<div id="native-ad-container" class="native-ad">
  <div class="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>

<script>
  const container = document.getElementById('native-ad-container');
  const adrop = Adrop.instance();

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

#### renderAdオプション

<ParamField body="unit" type="string" required>
  Ad Controlコンソールで作成したユニットID
</ParamField>

<ParamField body="uid" type="string">
  ユーザー識別子（SDK設定値を個別の広告枠で上書きする場合に使用）
</ParamField>

<ParamField body="contextId" type="string">
  コンテキストターゲティング用Context ID
</ParamField>

<ParamField body="trackMode" type="number" required>
  カスタムUI使用時は`1`に設定
</ParamField>

<ParamField body="isEntireClick" type="boolean" default={false}>
  全体領域クリックを有効化
</ParamField>

<ParamField body="theme" type="string" default="light">
  テーマ設定（`light`または`dark`）
</ParamField>

<ParamField body="useCustomClick" type="boolean" default={false}>
  カスタムクリック処理の有効化 - `true`に設定するとSDKが自動で目的地URLに移動せず、`adClicked`イベントのみ発生させます。開発者がクリック動作を直接実装できます。
</ParamField>

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

***

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

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

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

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

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

***

## 広告サイズ

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

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

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

***

## requestAdでデータのみ取得

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

```html theme={null}
<div id="native-ad-container"></div>

<script>
  async function loadNativeAd() {
    const adrop = Adrop.instance();

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

    if (response.code === 0 && response.result) {
      const ad = response.result;
      const container = document.getElementById('native-ad-container');

      container.innerHTML =
        '<div class="native-ad">' +
          '<div class="ad-header">' +
            '<img src="' + (ad.profile?.displayLogo || '') + '" alt="ロゴ">' +
            '<span>' + (ad.profile?.displayName || '') + '</span>' +
          '</div>' +
          '<h3>' + (ad.headline || '') + '</h3>' +
          '<img src="' + (ad.asset || '') + '" alt="広告">' +
          '<p>' + (ad.body || '') + '</p>' +
          '<a href="' + ad.destinationURL + '" target="_blank">' + ad.callToAction + '</a>' +
        '</div>';
    }
  }

  loadNativeAd();
</script>
```

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

### AdropAdResponse

`requestAd()`の戻り値です。

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

### AdData

広告データオブジェクトです。イベントハンドラーでも同じ構造で渡されます。完全なインターフェース定義は[リファレンス > AdData](/ja/sdk/web/reference#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>` | 追加テキスト項目                                 |

***

## イベント処理

```html theme={null}
<script>
  const adrop = Adrop.instance();
  const filter = { unit: 'YOUR_NATIVE_UNIT_ID' };

  function handleReceived(unit, adData) {
    console.log('広告受信:', adData);
  }

  function handleNoFill(unit) {
    console.warn('広告なし:', unit);
  }

  function handleFailed(unit) {
    console.error('広告失敗:', unit);
  }

  function handleImpression(unit, adData) {
    console.log('広告表示:', unit);
  }

  function handleClicked(unit, adData) {
    console.log('広告クリック:', unit);
  }

  // 動画再生開始
  function handleVideoStart(unit, adData) {
    console.log('動画開始:', unit);
  }

  // 動画再生完了
  function handleVideoEnd(unit, adData) {
    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);
</script>
```

### サポートするイベント

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

***

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

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

```html theme={null}
<script>
  const adrop = Adrop.instance();
  
  // カスタム動作で広告クリック処理
  function handleCustomClick(unit, adData) {
    console.log('広告クリック:', unit);
    console.log('目的地URL:', adData.destinationURL);
    
    // カスタムクリック動作実装
    // 例：SPA内ナビゲーション、モーダル表示、分析追跡など
    if (adData.destinationURL) {
      // カスタムナビゲーションロジック
      window.location.href = adData.destinationURL;
    }
  }
  
  // クリックハンドラー登録
  const filter = { unit: 'YOUR_NATIVE_UNIT_ID' };
  adrop.on(Adrop.Events.AD_CLICKED, handleCustomClick, filter);
  
  // カスタムクリック有効化して広告レンダリング
  const container = document.getElementById('native-ad-container');
  adrop.renderAd(container, {
    unit: 'YOUR_NATIVE_UNIT_ID',
    trackMode: 1,
    isEntireClick: true,
    useCustomClick: true
  });
</script>
```

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