ADの技術面：仕組みと導入方法

概要

ADとは何か、誰のためのものか

ADは直接取引の広告サーバーです。オークションもブラックボックスもありません。パブリッシャーは自分が運営するサイトの広告スペースを売り、広告主は枠を選び、ターゲティングを設定して配信します。一つのアカウントでどちらの役割も — 両方も — 務められます。

アクセス

入り方

forhosting.comにログインし、アカウントメニューの「AD を管理」を選びます。パネルは短いセッションで開きます — 数分で失効する認証情報（最長60分）で、ブラウザに永続的なキーは一切残りません。失効したら同じメニューから開き直してください。

連携には、パネル（プロフィール）またはPOST /tenants/:id/keysでAPIキーを作成します。スコープは2種類：tenant（自分のアカウントへのフルアクセス）とread（読み取り専用、ダッシュボードやボット向け）。キーは一度しか表示されません。紛失したら新しく作り、古いものを失効させてください。

サポートのため、当社スタッフがお客様のパネルを「顧客として」開くことがあります。そのセッションは最長15分で、開いた担当者の名前が記録されます。当社が永続キーでお客様のアカウントを操作することはありません。

広告主

キャンペーンとターゲティング

キャンペーンは入れ物です：名前、期間、任意の予算、そしてクリエイティブが共有するターゲティング。draftとして生まれ、activeにしたり、pausedで一時停止したり、終わったらendedにしたりできます。配信されるのはアクティブなキャンペーンのアクティブなクリエイティブだけ — キャンペーンを一時停止すると配信は即座に止まります。

対象となるキャンペーンの中から、エンジンはランダムに選ぶのではなく順番に回します。一方を配信し、次にもう一方を配信し、両者が並んだときにだけ、各クリエイティブに設定した重みが同点を決めます — 同じ訪問者に同じキャンペーンを10回続けて見せても何も売れません。順番は訪問者ごと・広告枠ごとに、訪問者自身のブラウザで数えます。cookieがブロックされている場合は重み付きの抽選に切り替わります。配信上限のあるクリエイティブはペーシングもされます：5分ごとに重みを再調整し、予算が朝のうちに燃え尽きず、キャンペーン期間全体に行き渡るようにします。ペーシングは減速するだけで、トラフィックを生み出すことはありません。

クリエイティブは支払い済みの注文がある広告枠でのみ配信されます（「枠を購入する」を参照）。キャンペーン、クリエイティブ、広告枠、注文はパネル（キャンペーン、クリエイティブ、枠を購入する）で確認できます。

広告主

クリエイティブ：6種類、タグは一つ

すべてのクリエイティブはクリックURL、任意の固定サイズ、重みを持ちます。この表の上限はAPIがアップロード時に適用するもので、コードから読み取られており、ここに書かれたものではありません。

HTML5の契約

index.htmlはiframe内に読み込まれ、クリック先はクエリ文字列のclickTagとして渡されます。これを読み取り、クリック可能領域のhrefに使ってください — このURLは署名付きでクリックを計測します。手で書いたリンクは計測されません。

// index.html — the click goes where the engine says
var clickTag = new URLSearchParams(location.search).get("clickTag");
document.getElementById("ad").href = clickTag;

クリエイティブの高さを変える必要があるときは、postMessageで実際の高さをページに伝えます。タグは読み込み時とリサイズのたびに枠の幅をクリエイティブに伝え、枠が初めて画面内に入ったときにvisibleを送ります — アニメーションを始める好機です。高さは10000 pxまで適用されます。

// creative → page: ask for the real height (applied up to 10000 px)
parent.postMessage({ fh: "resize", nh: document.documentElement.scrollHeight }, "*");

// page → creative: { fh: "size" | "visible" }
window.addEventListener("message", function (ev) {
  if (ev.data && ev.data.fh === "visible") { /* start your animation */ }
});

両方を行う最小構成のクリエイティブです。そのままアップロードできます： サンプルZIPをダウンロード

スクリプト型クリエイティブのマクロ

script型クリエイティブでは、広告枠の公開時にエンジンがこれらのプレースホルダーを置き換えます。パネルのテンプレートも同じ仕組みで、フォームで入力する追加のプレースホルダーを持ちます。

一つのクリエイティブに複数の遷移先

クリエイティブは、主となるクリックURLのほかに名前付き遷移先を最大8件持てます — たとえば同じ広告の中にApp StoreボタンとGoogle Playボタンを並べる場合です。それぞれ最大20文字の小文字のIDを持ち、mainは主となるURL用に予約されています。

HTML5クリエイティブでは、通常のclickTagと並んでクエリ文字列にclickTag_<id>として渡されます。script型クリエイティブでは[CLICKTAG:<id>]と書きます。いずれもクリックトラッカーを通るため、合計に加算されかつレポートではボタンごとの内訳も得られます。

サードパーティのトラッキングと同意

どのクリエイティブにもトラッキングコード（計測事業者のピクセルやスクリプト）を付けられます。広告の後に出力され、各srcはdata-srcに変換されるため、タグが許可するまで何も読み込まれません。

事業者のIAB TCF v2 IDを設定すると、その事業者に対する訪問者の同意が得られた後にのみ、${GDPR}と${GDPR_CONSENT_n}を埋めた状態でコードが読み込まれます。タグはサイトの同意管理ツールを最大10秒待ちます。事業者IDがない場合、コードは通常の要素として読み込まれます。

手動審査

すべてのクリエイティブはen_revisionとして生まれ、配信前に人が審査します。承認されたらactiveまたはpausedに設定できます。却下された場合は理由が表示され、修正して再提出できます。未審査のクリエイティブからは、マークアップもスクリプトもトラッキングコードも、訪問者には一切届きません。

承認済みクリエイティブのクリックURL、内容、ファイルを変更すると再審査に戻ります。承認されたものだけが配信され、それ以外が配信されることはありません。

広告主

枠を購入する

マーケットプレイスには販売中のすべての広告枠が並びます：サイト、サイズ、許可形式、販売モデル、パブリッシャーが設定した価格。広告枠、その枠が許可する形式のクリエイティブ、予算、開始日を選びます。見積もりと課金は同じ式を使います：

最低注文額は$5で、それ未満の見積もりは拒否されます。注文はボリュームの前払い購入で、お金が動くのは購入時の一度だけです。idempotencyKeyを送れば、再送しても二つ目の注文ではなく同じ注文が返ります。

支払い方法

注文が支払い済みになると、最終価格の80%が広告枠のパブリッシャーに計上されます — 配信量に応じた按分ではなく注文全体に対してです。広告枠はただちに再公開され、クリエイティブは翌分から配信されます。

パブリッシャー

サイト、広告枠、タグ、支払い

サイト

ドメインでサイトを登録します（パブリッシャーになる）。保留状態で生まれ、そのあと自分で確認を済ませます：お渡しするトークンを/.well-known/fh-ad-site-verification.txtかトップページに掲載し、確認を依頼すると、サイトは自分で有効になります — 待ち行列もなく、こちらの誰かが先に見る必要もありません。未確認のドメインは取り分を受け取れません。サイトを退役させるとドメインに90日間のクールダウンがかかり、その間は他の誰もそのドメインを登録して履歴を引き継ぐことができません。

広告枠

広告枠は販売できるスロットです：名前、ピクセル単位のサイズ（または可変幅なら-1）、許可する形式、価格付きの販売モデル、マーケットプレイスで販売中かどうか。他に対象がないときに配信される自分のフォールバッククリエイティブを設定でき、これはターゲティングとキャップを無視します。

訪問者のブラウザで動く任意の機能が二つあります：自動更新（N秒ごとに新しいリクエスト、最小5秒。非表示のタブでは更新せず、空で返ってきた枠は前の広告を保持します）とパラメータの転送（ページのクエリ文字列がクリックとともに広告主の遷移先へ渡されます）。

インタースティシャルが表示されるきっかけ

オーバーレイはサイトではなく広告枠の属性です：そのために貼り付けるものはなく（必要なものはタグが自分で作ります）、表示の間隔は枠を購入するパネルから変更します。モードは4種類：

間隔が一定だと、30日目の訪問者も1日目と同じだけ疲れさせてしまいます — 段階的なスケジュールはそのためのもので、最初の表示は早めに使い、そのあとは身を引きます。回数は訪問者自身のブラウザに保存され、ストレージが使えない場合は、壊れる代わりにメモリ上で数える動作に切り替わります。

広告をいつ要求するか — サイトが先です

広告がサイトを遅くしてはなりません。その設定はお客様のHTMLではなくこちらにあります。サイトごとに、タグが最初の広告を要求するタイミングを選べます：

そして広告が届くまでの間も、枠は空白ではありません：タグはプレースホルダーを描画し、高さを学習します — 初回の訪問では余裕を見たサイズを確保し、2回目からは確保する枠がちょうどの大きさになるため、広告が届いてもページが跳ねません。この跳ねがGoogleの測るレイアウトシフトであり、広告ネットワークがサイトのスコアを落とす典型的な原因です。

タグ

広告を出したい場所に貼り付けてください — または広告枠自身に場所を宣言させて、この手順をまるごと省略できます（下の「広告が出る場所」を参照）。広告枠のidはパネル（サイトと広告枠）にあります。同じタグでその枠が受け付けるすべての形式を配信します。インタースティシャルの枠も標準のタグを使います。

標準（divとscriptが一つずつ、非同期）：

<div data-fh-ad="zon_XXXXXXXXXXXXXXXXXXXXXXXX"></div>
<script src="https://api.ad.forhosting.com/ad-tag.js" async></script>

レガシー版。非同期スクリプトを実行できないCMS向け：

<script src="https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=js"></script>

テキストリンク：表示回数を数えて広告主へリダイレクトするURL：

https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=link

タグは自動で更新されます。URL にバージョンは含まれず変わることもないため、当社側の改善は約 60 分で全サイトに届き、誰もテンプレートを編集しません（現在は v11 を配信、x-tag-version ヘッダーで確認できます）。ページの読み込みが完全に終わってから広告を要求するので、広告がコンテンツと帯域を奪い合うことはありません。ページに残る印は data-fh-ad 属性とオーバーレイの id だけで、主要な広告ブロックリストと照合して一致はゼロです。フリークエンシーキャップはファーストパーティ Cookie を使います。

同じ位置がページ内で繰り返される場合 — たとえばフォーラムの「Nスレッドごと」 — タグはそのすべてのコピーを1回のリクエストでまとめて要求し（最大10）、フリークエンシーキャップはそのまとまりの中で進むため、一つのクリエイティブがページ上のすべての枠を埋めることはありません。当社側がまとめての要求を解釈できない場合、タグはページを空のままにせず、一枠ずつの動作に戻ります。広告枠を繰り返す場合は当社に申告してください：原則として位置ごとに一つの広告枠です。レポートが集計する単位が広告枠だからです。

広告が出る場所 — テーマに触れずに

広告枠はどこに置くかを自分で宣言できます：CSSセレクタ（最大300文字）と、そのセレクタが見つけた要素に対する位置です。枠はタグが作るので、広告を動かすのはパネルでの変更であって、テーマの編集ではありません。

繰り返しは任意の2つの数値で決まります：N件ごとに枠を置くもの（最大50）と、作る枠の総数の上限（繰り返すときは既定で4、最大20）です。上限は常にあります：pのような緩いセレクタは長い記事で何百回も一致するので、その制限が設定する人の記憶に頼ってはいけません。

知っておくとよいことが2つ。テーマにご自身で置いたdata-fh-adのdivが優先されます：タグはその枠に2つ目を作らないので、一方の方式からもう一方へ移っても1回の表示で2回課金されることはありません。そして一致しないセレクタはエラーになりません — ページは広告なしで問題なく表示され、パネルも緑のままです。配置はブラウザで、デスクトップ幅とスマートフォン幅の両方で確認してください：記事には存在してトップページには存在しないセレクタもあれば、デスクトップで1360px、スマートフォンで0pxになるものもあります。

WordPress：貼り付けるものはありません

サイトがWordPressならforhosting-adというプラグインがあります。インストールすると自分で名乗り出ます：ご自身のドメインにチャレンジを公開し、こちらがそれを読み、認証情報は一度だけ渡されます。鍵もidもトークンも入力しません — そしてドメインを管理していると証明することは招かれていることと同じではありません：サイトが承認されるまで何も発行されません。

そこから先は広告枠をパネルで管理します。配置も含みます。プラグインはさらに、サイトで使っているページキャッシュに、HTMLが変わったページの破棄を依頼します — よくあるものを判別し、それぞれのやり方で頼みます。キャッシュされたページは、タグはHTMLにあるのに広告が画面に出ない、いちばんよくある理由です。しかもコマンドラインからは見えません：古い写しは本物のブラウザにしか渡されないからです。

もう一つforhosting-ad-updaterというプラグインがあり、パッケージを受け取って導入します。これは設計上リモート実行の経路なので、当社のサイトにしか入れません。お客様のサイトでは更新はWordPress本来の経路で届き、適用する時期はお客様が決めます。

支払い

支払い済み注文ごとの80%の取り分がパネル（支払い）に積み上がります。累計が$10に達したら、プロフィールの方法（paypal, bank, other）で支払いを申請してください。当社スタッフがパネル外で送金し、参照番号を記録します。

状態：accrued → requested → processing → paid。送金に失敗した場合は理由とともに戻され、情報を修正して再申請できます。

全員向け

レポート

表示回数、クリック、動画の開始/終了は、リクエストごとにエッジで数えられます。計測前にトラフィックをフィルタリングします：ユーザーエージェントで知られるクローラー、データセンターのネットワーク、ボットスコアが非常に低いリクエスト、2秒以内に同じリクエストを繰り返すIP。フィルタされたリクエストにも広告やリダイレクトは返されます — 守られるのはカウンターだけです。

5分ごとに、計測値はクリエイティブ・広告枠・リファラーのホスト別の日次行に集計されます。当日はその分だけ遅れることがあり、締めた日の数値は変わりません。

パネル（レポート）では、合計と日次推移、CTR（クリック ÷ 表示 × 100）、eCPM（配信価値 × 1000 ÷ 表示）を広告主側またはパブリッシャー側で表示し、6つの集計単位のいずれかでまとめた上位一覧も見られます：

いずれの表示も、キャンペーン・クリエイティブ・広告枠・リファラーのホスト・遷移先で絞り込めます。同じ数値はAPIからも取得できます。

計測される前に、トラフィックはボットフィルターを通ります。当社は3つのモードのいずれかで運用します：block（既定。フィルターされたリクエストにも広告は返されますが、数えられません）、log（数えたうえで別に記録し、判断の前に計測します）、off。

導入

APIリファレンス

ベースURLはhttps://api.ad.forhosting.com。キーはBearerトークンとして送り、リクエストボディとレスポンスはJSONです。すべてのレスポンスは{"success":true,"data":…}または{"success":false,"error":{"code","message"}}の形で、対応するHTTPステータスを伴います。

curl https://api.ad.forhosting.com/me \
  -H "Authorization: Bearer ads_ten_…"

認証情報のスコープ

tenant、read、sessionの認証情報は常に自分のアカウントを操作します — クライアントが送ったtenantIdは無視されます。他人のIDには403ではなく404が返ります。APIはその存在を決して確認しません。

ルート

サービスが公開するすべてのルートと、ルーターが要求するスコープ — ビルドのたびにルーター自身から導出されます。

公開: 認証不要 — 配信経路 · 任意: 有効な認証情報なら何でも、自分のアカウントに対して · 読み取り: tenant、session、read · 書き込み: tenantまたはsession（readは拒否） · system: 当社のみ

知っておきたいエラー：401 unauthorized（認証情報がない、または失効）、403 forbidden（そのスコープでは実行不可）、404 not_found、400 bad_request（理由はメッセージに）、409 conflict（許可されない状態遷移）、注文の支払い時の402 insufficient_balance、販売停止中の503 payments_disabled。

FAQ

技術的な質問