Skip to content

Latest commit

 

History

History
198 lines (146 loc) · 8.91 KB

Zucks-Ad-Network-Native-api-specification-1.1.md

File metadata and controls

198 lines (146 loc) · 8.91 KB
Raw

Zucks Ad Network Native Ad API v1.1 Specification

こちらは旧バージョンのAPIとなります。
新しいバージョンの Native Ad API（v2） を公開しております。

Request

Request Headers:

  • User-Agent: String, Required.
    • デフォルトブラウザと同等のものをHeader、もしくは後述のParameter ua で必ず送信してください
    • 末尾に独自の付加情報が追加されていても、許容されます
    • Parameter ua が設定されている場合、Parameter側の設定が優先されます
  • Referer: Optional.
    • Parameter ref が設定されている場合、Parameter側の設定が優先されます
  • Accept-Language: Optional.
    • Parameter lang が設定されている場合、Parameter側の設定が優先されます
  • Origin: Optional.
    • withCredentials 属性を true にてリクエストする場合は設定してください
  • Cookie: Optional.

Request Parameters:

  • frameid: String, Requierd.
    • 枠ID. Zucks Ad Network担当者にご確認ください.
  • ida: String, Optional.
    • IDFA(iOS) or Advertising ID(Android)
    • Parameter ida を送信する場合、iOS13以前やAndroidでは後述のParameter lat も送信してください
  • lat: 0 or 1, Optional.
    • 「広告トラッキング制限」が無効な場合: 0
    • 「広告トラッキング制限」が有効な場合: 1
  • ua: String, Optional.
    • Headerと異なるUser-Agentを利用する場合に設定してください
  • chm: String, Optional.
    • ブラウザのユーザエージェントクライアントヒントAPI機能(以下, Client Hints)によって取得できる端末モデル名
    • Client Hintsの取得
  • chpv: String, Optional.
    • ブラウザのユーザエージェントクライアントヒントAPI機能(以下, Client Hints)によって取得できるプラットフォームバージョン(OSバージョン)
    • Client Hintsの取得
  • ref: String, Optional.
    • Headerと異なるRefererを利用する場合に設定してください
  • lang: Optional.
    • Headerと異なるAccept-Languageを利用する場合に設定してください
  • ip: Source IP address, Optional.

Client Hintsの取得

UserAgent Client Hints API 用いてモデル、プラットフォームバージョンを取得する例

if(navigator.userAgentData){
  navigator.userAgentData.getHighEntropyValues(["model", "platformVersion"]).then((uaData) => {
    //取得したUA情報の処理
  });
}

参考: API Reference

HTTPヘッダー によるClient Hintsの取得も可能です

その他

  • ブラウザ/WebView内からの XmlHttpRequest を使ってリクエストを送る場合:
    • withCredentials 属性を true にてリクエストしてください
    • Request Headers の Origin を設定してください

Response

Zucks Ad Serverから、JSON文字列を返します。

Response Header

  • HTTP status: 200 OK
  • Content-Type: application/json;charset=UTF-8

Response Body

  • status: String. ok / no_ad.
  • imp_url: URL. インプレッション計測用エンドポイント.
  • type: String. native.
  • image_src: URL. Banner image src.
    • 縦横比を保って表示してください。
  • width: Integer. 画像の横幅.
  • height: Integer. 画像の高さ.
  • landing_url: URL. 広告タップ時の遷移先URL.
  • text: String. 広告の本文.全角1～44文字（半角1～88文字）の文字列.
  • sub_text: String. 広告素材のタイトル.全角0～18文字（半角0～36文字）の文字列.

status: no_ad

配信できる広告案件がないときに返されます。案件がない場合でも、 HTTP status: 200 OK で返します。

imp_url 値を後述 Firing Impressions にしたがって処理することで、Zucks Ad Network管理画面上で「配信した広告がなかった」数としてカウントします。

その他

レスポンス内容はキャッシュせずに、広告表示のタイミングで毎回APIを叩いて習得したレスポンスを利用してください。

キャッシュした内容で広告表示を行うと正しく広告が表示されていないと判断されインプレッション、クリックが正しくカウントされない場合があります。

Example

Request

iOS

https://sh.zucks.net/opt/native/api/v1?frameid=_xxxxxxxxxx&ida=xxxx-xxxx-xxxx-xxxx-xxxx&lat=0&ua=Mozilla%2F5.0%20%28iPhone%3B%20CPU%20iPhone%20OS%209_0%20like%20Mac%20OS%20X%29%20AppleWebKit%2F601.1.46%20%28KHTML%2C%20like%20Gecko%29%20Version%2F9.0%20Mobile%2F13A344%20Safari%2F601.1&ref=http%3A%2F%2Fexample.com&lang=ja&ip=1.66.96.0

Android

https://sh.zucks.net/opt/native/api/v1?frameid=_xxxxxxxxxx&ida=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&lat=0&ua=Mozilla%2F5.0%20%28Linux%3B%20Android%2011%3B%20Pixel%205%29%20AppleWebKit%2F537.36%20%28KHTML%2C%20like%20Gecko%29%20Chrome%2F90.0.4430.91%20Mobile%20Safari%2F537.36&chm=Pixel%205&chpv=11.0.0&ref=http%3A%2F%2Fexample.com&lang=ja&ip=1.66.96.0

Response

Native ad:

{
    "status": "ok",
    "type": "native",
    "image_src": "https:\u002F\u002Fstatic.zucks.net.zimg.jp\u002Fimage\u002F2015\u002F01\u002F29\u002F162401_phphVPOnl.png",
    "width": "114",
    "height": "114",
    "imp_url": "https:\u002F\u002Fk.zucks.net\u002F...",
    "landing_url": "https:\u002F\u002Fk.zucks.net\u002F...",
    "text": "こちらはネイティブ広告の本文となります",
    "sub_text": "こちらは追加の文言です"
}

no_ad:

{
    "status": "no_ad",
    "imp_url": "https:\u002F\u002Fk.zucks.net\u002F..."
}

Rendering the Ad

image_src は、png/jpg/gif(アニメーション含む)などの画像ファイルを示すURLです。そのURLから画像を取得し、内容を表示してください。 image_src の画像ファイルの内容は不変です。必要に応じてキャッシュして利用することができます。 text は全ての広告について設定されていますので、必ず表示するようにしてください。 sub_text は追加で利用することができるテキストです。広告によっては空文字の場合があります。

Firing Impressions

Zucks Ad Networkでは、ビーコン送信によりインプレッションを計測しています。

広告領域をレンダリングした直後、 imp_url のURLにGETリクエストを送信してください。

  • End point: imp_url のURL
  • Method: GET
  • ブラウザ/WebView内からの XmlHttpRequest を使ってリクエストを送る場合:
    • withCredentials 属性を true にてリクエストしてください。

Firing Clicks

広告タップ時、landing_url のURLでデフォルトブラウザを開いてください。

Check List

ご利用開始までに確認すべきチェック項目です。

広告収益の算出ができない場合がありますので、必ず確認してください 。

  • Native広告が表示された
  • Zucks Ad Network管理画面で、インプレッション数が増えた
  • クリック後、デフォルトブラウザでランディングページが表示された
  • Zucks Ad Network管理画面で、クリック数が増えた

Trouble Shooting

よくあるトラブルに対する確認項目です。

no_ad しか返りません

  • Request Parameterの frameid 値は正しいですか？
  • Request Headerの User-Agent 値またはRequest Parameterの ua 値は、デフォルトブラウザに準じた値ですか？
  • Zucks Ad Network上の設定は正しいですか？

該当枠に対する広告在庫がない場合もございます。詳しくはZucks営業担当にお問い合わせください。

インプレッションがカウントされません

  • Requestの frameid 値は正しいですか？
  • imp_url 値のURLにリクエストを発行していますか？
  • 管理画面上のレポーティングには多少のタイムラグがあります。しばらく待ってみてください。

クリックがカウントされません

  • landing_url 値のURLにリクエストを発行していますか？
  • そのレスポンスは 302 Moved Temporarily ですか？
  • 管理画面上のレポーティングには多少のタイムラグがあります。しばらく待ってみてください。