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

概要

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

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

アクセス

入り方

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

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

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

広告主

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

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

対象となるクリエイティブの中から、エンジンは各クリエイティブに設定した重みに応じてランダムに選びます。配信上限のあるクリエイティブはペーシングされます：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型クリエイティブでは、広告枠の公開時にエンジンがこれらのプレースホルダーを置き換えます。パネルのテンプレートも同じ仕組みで、フォームで入力する追加のプレースホルダーを持ちます。

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

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

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

手動審査

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

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

広告主

枠を購入する

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

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

支払い方法

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

パブリッシャー

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

サイト

ドメインでサイトを登録します（パブリッシャーになる）。保留状態で生まれ、その広告枠が販売できるようになる前に人が確認します — 未確認のドメインは取り分を受け取れません。サイトを退役させるとドメインに90日間のクールダウンがかかり、その間は他の誰もそのドメインを登録して履歴を引き継ぐことができません。

広告枠

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

訪問者のブラウザで動く任意の機能が二つあります：自動更新（N秒ごとに新しいリクエスト、最小5秒。非表示のタブでは更新せず、空で返ってきた枠は前の広告を保持します）とパラメータの転送（ページのクエリ文字列がクリックとともに広告主の遷移先へ渡されます）。インタースティシャル枠では、オーバーレイを起動するリンク（既定はp a, nav a, h2 a）と、閉じられるようになるまでの秒数も指定します。

タグ

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

支払い

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

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

全員向け

レポート

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

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

パネル（レポート）では、合計と日次推移、CTR（クリック ÷ 表示 × 100）、eCPM（配信価値 × 1000 ÷ 表示）を広告主側またはパブリッシャー側で表示し、クリエイティブ・広告枠・キャンペーン・サイト・リファラーのホスト別の上位一覧も見られます。保存されるのはリファラーのホストだけで、URLは保存されません。

導入

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

技術的な質問