Permalink
92c8ee4 Nov 23, 2016
@cou929 @ka2u @yoheimuta @tada-y @tk8s @detani
441 lines (333 sloc) 19 KB

目次

In-Feed 広告

Getting Started

広告枠の登録

管理 UI から広告枠を登録します。事前に管理 UI へのアカウント開設が必要です。

広告テンプレートの入稿

管理 UI から広告テンプレートを入稿します。以下のように {{click_url}} という記法でプレースホルダーを指定すると、その部分が広告素材に置き換えられ、広告として表示されます。

使用できるプレースホルダーはこちらを参照してください。

<div class="article">
  <div class="icon">
    <a href="{{click_url}}">
      <img src="{{main_image_url}}" />
    </a>
  </div>

  <div class="contents">
    <h3>{{title}}</h3>
    <p><span {{optout_click}}>【PR】</span>{{description}}</p>
    <span class="source">{{displayed_advertiser}}</span>
  </div>
</div>

テンプレート作成上の注意点

広告箇所が広告であることをユーザーが視認・理解できる文言を必ず記述して下さい。

(例:「PR」・「Sponsored」・「Ad」・「広告」)

広告タグの発行

管理 UI からタグを発行します。以下の様なタグが発行されるので、ページ内の広告を表示させたい位置に挿入します。

<div data-advs-adspot-id="広告枠ID" style="display:none"></div>

body 閉じタグ直前に挿入します。

<script src="http://js.mtburn.com/advs-instream.js"></script>
<script type="text/javascript">MTBADVS.InStream.Default.run({immediately:true})</script>

広告の追加ロード

フィード型のサイトなどでユーザーがサイト下部に到達した際に追加フィードを読み込むような UI の場合に、追加で広告ロードを行うことも可能です。

  • フィードの追加読み込み時に挿入される DOM 上に、初期状態と同様の広告位置指定要素を含めていただきます。
<div data-advs-adspot-id="MjQzOjIw" style="display:none"></div>
  • フィード追加読み込み後に SDK の MTBADVS.InStream.Default.reloadAds() メソッドを呼び出します。呼び出し後に広告案件の追加取得と表示を行います。
// 追加フィードの読み込み後に呼び出される関数の例
function onAdditionalFeedLoaded() {
    // ...

    // SDK の reloadAds メソッドを呼び出し
    MTBADVS.InStream.Default.reloadAds();
}

広告タイトル・説明文・表記広告主名の短縮

管理画面から設定することで、広告のタイトルや説明文のテキスト、表記広告主名を媒体様のサイトに合わせて短縮させることができます。詳しくは管理画面のご利用マニュアルを参照してください。

コールバック関数による編集

コールバック関数を渡すことで、媒体様の任意の方法で文字長の調整が可能です。コールバック関数は広告表示の直前に呼び出されます。引数として案件情報と設置箇所が渡されます。よって案件情報を任意に編集する処理を記述できます。また設置箇所に応じて、案件の文字数などを変動させることも可能です。コールバック関数は before_render オプションに渡します。管理画面上で長さの設定をしている場合でも、before_render が優先されます。

以下は、タイトルの先頭に [PR] という文字列を入れる。かつ、説明文を広告枠Aでは30文字、広告枠Bでは40文字に短縮し末尾に三点リーダーを付け加える例です。

MTBADVS.InStream.Default.run({
    before_render: function(ad_info, placement_info) {
        // タイトルの先頭に `[PR]` を挿入
        ad_info.title = '[PR] ' + ad_info.title;

        // 広告枠ごとに説明文の最大長を設定する
        var desc_max_len = 30;
        if (placement_info.adspot_id === 'ADSPOT_A') {
            desc_max_len = 30;
        } else if (placement_info.adspot_id === 'ADSPOT_B') {
            desc_max_len = 40;
        }

        // 説明文がdesc_max_len文字数におさまるよう切り取り、末尾に三点リーダーを加える
        if (ad_info.description.length > desc_max_len) {
            ad_info.description = ad_info.description.substr(0, desc_max_len - 1) + '';
        }

        // 編集結果を return する
        return ad_info;
    }
});
  • before_render の第一引数には広告案件のオブジェクトが渡されます。オブジェクトが持つプロパティは 広告パラメータ を参照してください
  • before_render の第二引数には設置位置情報のオブジェクトが渡されます。オブジェクトが持つプロパティは adspot_id (広告枠ID) です。
  • コールバック関数は編集結果の案件情報オブジェクトを必ず return で返す必要があります。

広告表示の高速化

immediately オプションを追加することで、広告が表示されるまでの速度を速めることができます。

以下は高速化のオプションを有効にする例です。

MTBADVS.InStream.Default.run({
    immediately: true
});

このオプションはデフォルトでは無効になっています。

immediately オプションが有効の場合、MTBADVS.InStream.Default.run() の呼び出し時に、即座に広告の読み込みと表示処理が開始されます。そのため、正しい順序で広告タグを貼る必要があります (広告テンプレートと広告挿入位置のタグの後に、広告呼び出しタグを設置する必要があります)。また M.T.Burn の広告が表示された後に動作する、媒体社様や外部の JavaScript の動作によって、表示が崩れる可能性があります。

immediately オプションが無効の場合、MTBADVS.InStream.Default.run() の呼び出し後、ページの読み込みが完了した後に、広告の読み込みと表示処理が行われます。そのため表示の崩れは起きにくくなりますが、オプション有効時に比べて、広告が表示されるまでの時間が長くなります。

カスタム実装

SDK の raw API を使用し、広告の呼び出しやレンダリングなどを任意のタイミングで行うことも可能です。以下に説明する API を用いて、媒体様による追加の実装が必要になります。

インスタンスの作成

広告を管理するコントローラークラスのインスタンスを作成します。コンストラクタには広告枠 ID の指定が必須です。

var ad_controller = new MTBADVS.InStream.AdController({ adspot_id: 'MjQzOjIw' });

広告リクエストの送信

loadAds() メソッドで広告案件のリクエストを発行し、案件情報取得します。引数として完了後に呼び出されるコールバック関数を指定します。

コールバック関数の第一引数にはエラーオブジェクトが返されます。成功時には null となります。

var on_ad_loaded = function(error) {
    if (error) {
        // エラー処理
    }

    // ...
};

ad_controller.loadAds(on_ad_loaded);

広告案件情報の取り出し

loadAds() でサーバより取得した案件情報は getLoadedAds() メソッドで取り出すことができます。

var ads = ad_controller.getLoadedAds();

getLoadedAds() の返り値は次のような配列です。

[
    {
        "title": "testAd",
        "description": "テスト広告です。",
        "click_url": "http://...",
        "main_image_url": "http://...",
        "icon_image_url": "http://...",
        "ad_id": 123,
        "displayed_advertiser": "テスト広告主提供",
        "optout": "http://...",
        "optout_click": " onClick=..."
    },
    ...
]

各パラメータの詳細は 広告パラメータの節 を参照してください。

広告の表示

getLoadedAds() で取り出した案件情報をもとに、広告を表示させます。表示処理は媒体様で実装していただく必要があります。

インプレッションの送信

広告の表示後、必ず notifyImp() でインプレッションの通知をする必要があります。引数として表示した ad_id を渡します。

var ad_id = ads[0].ad_id;
ad_controller.notifyImp(ad_id);

追加ロード

フィードをさらに読み込んだ場合など、追加で広告をロードする場合について。

loadAd() メソッドを呼び出すごとに、あたらしい広告案件を取得することができます。getLoadedAds() は表示済の案件も含め、これまでに取得した案件をすべて返します。

始めにインスタンス化したコントローラーのインスタンスを使いまわす必要があります。 ひとつのインスタンスを使い続けると、重複した案件が返されることはありません。

ここまでの流れを踏まえた実装例

var ad_controller = new MTBADVS.InStream.AdController({ adspot_id: 'MjQzOjIw' });

var on_ad_loaded = function(error) {
    if (error) {
        // エラー処理
    }

    // 案件の取得
    var ads = ad_controller.getLoadedAds();

    ads.forEach(function(ad) {
        // 広告案件情報をもとに広告を表示 (媒体様実装)
        showAd(ad);

        // インプレッションの通知
        var ad_id = ad.ad_id;
        ad_controller.notifyImp(ad_id);
    });
};

ad_controller.loadAds(on_ad_loaded);

注意事項

  • サーバから広告情報を取得はページの読み込みごとに行ってください。事前に取得したものをキャッシュし使いまわすことはご遠慮ください。
  • サーバから取得できる広告案件は、より効果が高いと期待される順に並んでいます。上位の案件は画面上の上位に表示することを推奨します。

広告パラメータ

パラメータ名 説明
title タイトル文言 TestAd
description 説明・紹介文 テスト広告です。
click_url 広告クリック時の遷移先 URL http://click.mtburn.com/...
icon_image_url アイコン型の正方形画像の URL http://banner.dspcdn.com/...
main_image_url バナー型の矩形画像の URL http://banner.dspcdn.com/...
ad_id 広告案件の ID 123
displayed_advertiser 表記広告主名 テスト広告主提供
optout オプトアウトページへのURL http://mtburn.jp/privacy_policyopt_out/
optout_click オプトアウトページへの遷移スクリプト onClick="function(e){...

DFP連携

DFP を利用した配信も可能です。Google サイト運営者タグの非同期タグと同期タグでそれぞれ実装方法が異なります。媒体様で実装されているタグの種類に応じて対応ください。

非同期タグの場合

  • 対象のオーダーにクリエイティブを追加します。クリエイティブのタイプは サードパーティ を選択します。
  • クリエイティブとして M.T.Burn のタグを入稿します。
    • 通常の配信面同様に、広告ユニットのテンプレート、広告表示位置指定の空要素、広告用スクリプトの呼び出しのタグを入稿します
    • 加えて、表示のために必要なスタイルシート呼び出しなどを適宜入れて頂く必要があります。
    • DFP のクリックマクロを挿入します。正しく挿入することで、正確な画面遷移とクリック数計測ができます。
    • DFP のクリックマクロを使用する場合は、タグ側でのテンプレート実装 が必須です。
<!-- css の読み込み等。媒体様によるカスタマイズが必要です -->
<link rel="stylesheet" type="text/css" href="http://yourodmain/sampale.css">

<!-- 広告ユニットのテンプレート -->
<script type="text/advs-instream-template" data-adspot-id="NzYzOjEyMg">
<div class="article">
  <div class="icon">
    <!-- [重要] dfp のクリックマクロを挿入し、直後に M.T.Burn のクリック URL をつけてください。 -->
    <a href="%%CLICK_URL_UNESC%%{{click_url}}" target="_blank">
      <img src="{{icon_image_url}}" />
    </a>
  </div>

  <div class="contents">
    <h3>{{title}}</h3>
    <p>{{description}}</p>
    <span class="source">{{displayed_advertiser}}</span>
  </div>
</div>
</script>

<!-- 広告表示位置の指定 -->
<div data-advs-adspot-id="NzYzOjEyMg" style="display:none"></div>

<!-- 広告用スクリプトの呼び出し -->
<script src="https://js.mtburn.com/advs-instream.js"></script>
<script>
MTBADVS.InStream.Default.run({
    before_render:function(ad_info, placement_info) {
        // [重要] dfp マクロとの連携のため、必ずこの行の実装をお願い致します。
        ad_info.click_url = encodeURIComponent(ad_info.click_url);

        // 説明文の切り上げなどを媒体様に必要に応じて実装していただきます。
        // 広告枠の大きさが固定の場合、長い文字がはみ出す可能性があるため、切り上げ処理の実装を推奨します。
        var desc_max_len = 30;
        if (ad_info.description.length > desc_max_len) {
            ad_info.description = ad_info.description.substr(0, desc_max_len - 1) + '';
        }

        return ad_info;
    }
});
</script>

iframe 内での広告表示となるため、通常のタグに加えてスタイルシートなどの読み込みが必要になります。

同期タグの場合

  • 対象のオーダーにクリエイティブを追加します。クリエイティブのタイプは サードパーティ を選択します。
  • クリエイティブとして M.T.Burn のタグを入稿します。
    • 通常の配信面同様に、広告ユニットのテンプレート、広告表示位置指定の空要素、広告用スクリプトの呼び出しのタグを入稿します
    • DFP のクリックマクロを挿入します。正しく挿入することで、正確な画面遷移とクリック数計測ができます。
    • DFP のクリックマクロを使用する場合は、タグ側でのテンプレート実装 が必須です。
<!-- 広告ユニットのテンプレート -->
<script type="text/advs-instream-template" data-adspot-id="NzYzOjEyMg">
<div class="article">
  <div class="icon">
    <!-- [重要] dfp のクリックマクロを挿入し、直後に M.T.Burn のクリック URL をつけてください。 -->
    <a href="%%CLICK_URL_UNESC%%{{click_url}}" target="_blank">
      <img src="{{icon_image_url}}" />
    </a>
  </div>

  <div class="contents">
    <h3>{{title}}</h3>
    <p>{{description}}</p>
    <span class="source">{{displayed_advertiser}}</span>
  </div>
</div>
</script>

<!-- 広告表示位置の指定 -->
<div data-advs-adspot-id="NzYzOjEyMg" style="display:none"></div>

<!-- 広告用スクリプトの呼び出し -->
<script src="https://js.mtburn.com/advs-instream.js"></script>
<script>
MTBADVS.InStream.Default.run({
    before_render:function(ad_info, placement_info) {
        // [重要] dfp マクロとの連携のため、必ずこの行の実装をお願い致します。
        ad_info.click_url = encodeURIComponent(ad_info.click_url);

        // 説明文の切り上げなどを媒体様に必要に応じて実装していただきます。
        // 広告枠の大きさが固定の場合、長い文字がはみ出す可能性があるため、切り上げ処理の実装を推奨します。
        var desc_max_len = 30;
        if (ad_info.description.length > desc_max_len) {
            ad_info.description = ad_info.description.substr(0, desc_max_len - 1) + '';
        }

        return ad_info;
    }
});
</script>

非同期タグの場合に必要なスタイルシートなどの呼び出しが、同期タグの場合は不要です。

広告テンプレートの管理 UI 入稿

管理 UI から広告テンプレートを入稿する場合は、DFP のクリックマクロが使用できません。DFP でのクリック計測が不要な場合のみご利用ください。

また、その場合は呼び出しタグの以下の行が不要です。

// [重要] dfp マクロとの連携のため、必ずこの行の実装をお願い致します。
ad_info.click_url = encodeURIComponent(ad_info.click_url);

名前空間

MTBADVS 変数を window オブジェクト直下に作成します。この他のグローバル汚染は一切おこないません。

よくある質問

コード中にあるInstreamはどういう意味ですか

このガイド中にある、In-Feed と同じ意味で用いられています