Publisher integration guide

提供：

移動： 案内, 検索


目次

概要

JumptapのtapLinkシステムは、携帯オペレーターやパブリッシャーがJumptap広告ネットワークから表示広告を取得できる単一のインターフェイスの機能を果たします。

本ページはtapLink APIの最新バージョン(バージョン2.9)に適用されます。

本wikiページでは、パブリッシャーと携帯オペレーターがtapLink APIを使用してバナーを取得する方法について説明します。

対象読者

本書は、表示広告へのJumptapのtapLInk APIの実装を担当するソフトウェアエンジニア、システムアーキテクト、製品・プロジェクト管理者を対象としています。

広告リクエストAPI

携帯ウェブパブリッシャーやアプリケーション開発者は、tapLink APIを使用することで、サーバー側の呼び出しメカニズムから表示広告をリクエストすることができます。 広告をリクエストするには、RESTスタイルのウェブインターフェイスを用いてパブリッシュサーバーからJumptap広告サービスにサーバー対サーバー呼び出しを行います。 この結果生成されたXHTMLマークアップが、エンドユーザーのブラウザページまたはアプリケーションに表示されます。

広告のリクエスト

tapLinkへの広告リクエストは、「ジャストインタイム」ベースで行う必要があります。つまり、広告が表示されるページの構築中に広告をリクエストする必要があります。tapLinkでは、将来の表示に備えた広告のプリフェッチはサポートしていません。

Jumptap APIへの広告リクエストは、次の要素で構成されています。

  • フォームの簡単なHTTP GETリクエスト： 
http://a.adjust-sp.jp/a/ads?<required parameters><optional parameters>
  • 元の機種から転送されたHTTPヘッダー

GETリクエストの構造

最初にベースのURIを記述し、必須のリクエストパラメータ、およびオプションのパラメータがあれば追加します。

次の点に注意してください。

  • パラメータ/値のペアは、相互に'&'文字で区切ります。
  • クエリー内のパラメータ/値のペアの順序は重要ではありません。
  • すべてのパラメータ値はURLでエンコードする必要があります。
  • 既にヘッダーとして送信した値にはパラメータを渡す必要はありません。
    • たとえば、デバイスからユーザーエージェント(user-agent)ヘッダーを送信している場合は、uaパラメータを渡す必要はありません。
  • すべてのリクエストに同じパラメータを渡す必要はありません。
    • たとえばサイトの特定のページのみで郵便番号が使用可能な場合、これらのページのリクエストには"&pc=&country="が含まれますが、他のページからのリクエストには含まれません。
  • 値がないパラメータには、NULL値や空の文字列を渡さないでください。 代わりに、そのようなパラメータをクエリー文字列からすべて除外してください。

使用可能なすべてのパラメータの広告リクエストのテンプレートを以下に示します。 定義済みのパラメータに値が含まれていないため、実際にはこれは有効なリクエストではないことにご注意ください。 

http://a.adjust-sp.jp/a/ads?v=&pub=&site=&spot=&a=&url=&ua=&gateway-ip&client-ip=&operator=&l=&ll=&pc=&country=&u=&hid=&mt-gender=&mt-age=&mt-hhi=

クライアントヘッダーを渡す

機種の特定、オペレーター/キャリアの解決、地域別ターゲット設定、フリークエンシーキャップなどのさまざまな機能を実行するには、元の(機種)クライアントからのHTTPヘッダーを各広告リクエストと一緒に渡す必要があります。

少数の特別な例外を除き、すべてのヘッダー – Accept*ヘッダーを含む – をJumptapに転送する必要があります。 次のヘッダーは明示的に除外されています。 

Host:
Keep-Alive:
Connection:
Cookie:
Cache-Control:
Content-Length:


IPを渡す

tapLinkではIPアドレスを使用して、広告リクエストに関するさまざまな情報を特定します。次のような情報が特定されます。

  • 広告リクエストが作成されたネットワークの携帯オペレーター。 広告主はこの情報を使用することで、キャリアにターゲットを絞ったキャンペーンを展開できます。
  • 広告リクエストが寄せられた国。 広告主はこの情報を使用することで、国にターゲットを絞ったキャンペーンを展開できます。


広告リクエストと一緒にデバイスヘッダーを転送することができ、同時にヘッダーを変更する機能が使用できる場合は、プロキシと同様にx-forwarded-forヘッダーを操作する必要があります。

  • x-forwarded-forヘッダーがデバイスのヘッダーに存在し、その長さがゼロ長以外だった場合は、Jumptapに転送する前に"<client ip>"を末尾に追加してください。
  • x-forwarded-forがゼロ長だったりデバイスのヘッダーに存在しない場合は、これをカンマなしで"<client ip>"に設定します。


広告リクエストと一緒にデバイスヘッダーを転送できる一方で、ヘッダーを変更することはできない場合は、次のようにします。

  • x-forwarded-forヘッダーをそのままJumptapに転送します。
  • 広告リクエストのクエリー文字列にclient-ipパラメータを含め、"<client ip>"に設定します。


デバイスヘッダーを転送できない場合は、次のようにします。

  • 広告リクエストのクエリー文字列にgateway-ipパラメータを含め、これをデバイスのx-forwarded-forヘッダーに設定します。
  • 広告リクエストのクエリー文字列にclient-ipパラメータを含め、"<client ip>"に設定します。


上記すべての例で、<client ip>呼び出し元のクライアントのIPアドレスを示します。 このIPアドレスは、使用中のHTTP実装から入手できます。

x-forwarded-forヘッダーの詳細については、Wikipedia： http://en.wikipedia.org/wiki/x-forwarded-forを参照してください。

必要なリクエスト情報

パラメータHTTPヘッダー必須説明
gateway-ipx-forwarded-for○広告リクエストに関連付けられた一連のIP。 詳細は、上記の「IPを渡す」セクションを参照してください。
hid○固有のデバイスハードウェアID。
  • このパラメータは、iPhoneとAndroidアプリケーションでのみ必須です。携帯ウェブサイトには必要ありません。
  • Jumptapで全商品を正しく収益化するためには、ハードウェアIDのフォーマットを広告主が使用しているフォーマットに一致させる必要があります。 つまりiOSアプリにはUDIDを使用し、AndroidアプリにはAndroid_IDを使用する必要があります。
  • iOSアプリ： iOSでは、40文字の半角英数字で構成されるUDIDを使用する必要があります。UDIDの入手方法に関する開発者向けマニュアルについては、Apple iOS Developer Guide (Apple iOS開発者ガイド)を参照してください。
    • iOS UDID(40文字の半角英数字)の例： 483a269b72ab8bc5d4a5fe0659c90f4808ce615b
  • Androidアプリ： Androidの性質上、ユーザーを識別するIDは混乱を招く可能性があります。 Jumptapでは、全商品の収益化を促進するためにAndroid_IDを使用することを義務付けています。 Android_IDの入手方法に関する開発者向けマニュアルについては、Android Developer Guide (Android開発者ガイド)を参照してください。
    • AndroidのAndroid_ID(64ビットHEX)の例： 20014303ca716d69
    • 重要な注意事項： Jumptapでは、Android DeviceIDを有効な識別子として認めていません。 JumptapにAndroidのDeviceIDを送信しないでください。大半の広告主のトラフィックが無効になります。
lAccept-Language○ユーザーの優先言語。 有効な値はISO-639-1の2文字の言語コードです。http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
pub○Jumptapから割り当てられたパブリッシャーエイリアス。
site○Jumptapから割り当てられたサイトエイリアス。
spot○Jumptapから割り当てられたアドスポットエイリアス。
url○/×広告をリクエスト中のページのURL。
  • これは(前のページを参照する可能性がある)参照元ヘッダーではなく、広告が表示されるページのURLであることにご注意ください。
  • このパラメータの値はエンコードする必要があります。
  • このパラメータは携帯ウェブサイトからのリクエストでは必須ですが、アプリケーションからのリクエストの場合は必要ありません。
uaUser-Agent○リクエストを行っている機種のユーザーエージェント(user-agent)。tapLinkはこの情報を使用してリクエストを行っている機種を特定します。これにより、機種にターゲットを絞ったキャンペーンを配信し、正しいサイズの広告が返されるようにすることができます。
  • uaパラメータを使用する際は、値をエンコードする必要があります。user-agent HTTPヘッダーをエンコードしないでください。
  • Opera Miniの場合、機種のユーザーエージェントがX-OperaMini-Phone-UAヘッダーに渡されます。 uaパラメータにユーザーエージェントを渡す場合、この値をOpera Miniリクエストに使用する必要があります。 リクエストヘッダーを渡すと、Opera Miniリクエストの機種がJumptapによって自動解決されます。
v○Jumptap tapLink APIのバージョン。 現在のバージョンは'v29'(バージョン2.9)です。

オプションのリクエスト情報

パラメータHTTPヘッダー必須説明
a×広告リクエストに対してアダルト広告を返してもよいかどうかを指定します。
  • デフォルトでは、アダルト広告は返されません。アダルト広告はパブリッシャーがはっきりとリクエストする必要があります。
  • 有効な値は次のとおりです。
  • "notallowed" - アダルト広告は返されません。 パラメータのデフォルト値です。
  • "allowed" - アダルト広告が返される可能性があります。返される広告はアダルト広告である場合とそうでない場合があります。
  • "only" - アダルト広告のみが返されます。
client-ip×広告をリクエスト中のデバイスのIPアドレス。 tapLinkおよび広告プロバイダーがキャリア/ゲートウェイのターゲットを設定する際に使用されます。 詳細は、上記の「IPを渡す」セクションを参照してください。
country○/×元のユーザーのリクエストの2文字のISO国コード。http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
  • 広告リクエストを発信しているユーザーの国がはっきりとわかっている場合にのみ国を渡すようにしてください。すべてのリクエストの静的値として設定しないでください。
  • リクエストに国が含まれていない場合、国はユーザーまたはゲートウェイのIPに基づいて自動判別されます。
  • 郵便番号(pc)パラメータを渡した場合は、国パラメータが必要です。
  • 緯度/経度を渡している場合は、国パラメータを渡さないでください。
ll×緯度/経度
  • 緯度と経度はカンマで区切る必要があります。
  • このパラメータの値はエンコードする必要があります。
  • 例：ll=42.369%2C-71.075
  • 緯度/経度は、郵便番号パラメータと国パラメータよりも優先されます。
mt-age×ユーザーの年齢がわかっている場合に使用します。 1～199の任意の整数が有効な値となります。
mt-gender×ユーザーの性別がわかっている場合に使用します。 有効な値は'm'(男性)または'f'(女性)です。
mt-hhi×ユーザーの世帯収入がわかっている場合に、収入を1000ドル単位で示します。
  • 有効な値は次のとおりです。
  • 000_015
    • 世帯収入が$15,000未満の場合
  • 015_020
    • 世帯収入が$15,000～$19,999の場合
  • 020_030
    • 世帯収入が$20,000～$29,999の場合
  • 030_040
    • 世帯収入が$30,000～$39,999の場合
  • 040-050
    • 世帯収入が$40,000～$49,999の場合
  • 050-075
    • 世帯収入が$50,000～$74,999の場合
  • 075-100
    • 世帯収入が$75,000～$99,999の場合
  • 100_125
    • 世帯収入が$100,000～$124,999の場合
  • 125_150
    • 世帯収入が$125,000～$149,999の場合
  • 150_OVER
    • 世帯収入が$150,000を超える場合
operator×サイトでオンデッキインスタンスを使用しているパブリッシャーの場合、このパラメータを使用して「オンデッキ携帯オペレーター」を指定します。
  • このパラメータは、オペレーター/キャリアがはっきりとわかっているオンデッキインスタンスでのみ渡してください。
  • オフデッキリクエストの場合、JumptapはリクエストヘッダーとゲートウェイIP情報に基づいてオペレーターを決定します。
  • 有効なオペレーターの一覧は、有効なオペレーターを参照してください。
pc×郵便番号
  • 緯度/経度を渡している場合は、pcパラメータを渡さないでください。
  • このパラメータの値はエンコードする必要があります。
  • 要求に郵便番号が含まれている場合は、国パラメータが必要になります。
  • 例： pc=02141&country=us
q×検索サイト/アプリケーションの場合は、q("クエリー")パラメータを使用して「検索用語」を渡します。
  • このパラメータの値はエンコードする必要があります。
Referer×参照元HTTPヘッダー。
  • これはリクエストを行っているページのURLではなく、前のページのURLであることに注意してください。
  • 現在、参照元ヘッダーに対応するパラメータはありません。
uClientID
x-up-subno
x-msisdn
XID
etc
×エンドユーザーの固有のID。tapLinkはこの識別子をフリークエンシーキャップに使用します。
  • 携帯オペレーターによってユーザー情報を渡すヘッダーが異なるため、デバイスのHTTPヘッダーを転送して、tapLinkがどのヘッダーにユーザーIDが含まれているかを判別できるようにすることをお勧めします。
  • ヘッダーを渡せない場合を除き、独自のアルゴリズムを作成してユーザーIDが含まれるヘッダーを判断することは避けてください。
  • デバイスヘッダーを転送できず、使用可能なさまざまなパラメータ内でユーザーIDを確認するアルゴリズムも作成できず、サイトでログインが必要な場合は、uパラメータにハッシュされたログインIDを渡すことができます。 渡される値はユーザーごとに固有ですが、同一ユーザーからのリクエストで一貫している必要があります。

一般的なエラー

HTTPヘッダー

  • HTTPヘッダーが渡されていない場合。
  • 機種のHTTPヘッダーではなく、パブリッシュしているサーバーのHTTPヘッダーを渡した場合。

User-agent

  • uaパラメータに渡すときにuser-agentがエンコードされなかった場合。
  • uaパラメータに渡すときにuser-agentをダブルエンコードした場合。
  • 機種ではなくパブリッシャーサーバーのuser-agentを渡した場合。

緯度 / 経度

  • 緯度と経度の値をカンマで区切らなかった場合。
  • 緯度、経度をエンコードしていない場合。

郵便番号

  • 郵便番号をエンコードしていない場合。
  • 郵便番号を渡したときに国パラメータが含まれていない場合。

国

  • すべての広告リクエストに静的値を渡した場合。
  • 国の2桁のコードではなく、国の完全名を渡した場合。

表示エラー

  • 空の広告応答を考慮しなかった場合(例：広告が返されない場合にプレースホルダを折りたたんでいない、など)
  • iPhoneアプリで、サポートされている両方の広告サイズ： 300 x 50 / 320 x 50を考慮しなかった場合
  • 任意のアプリケーションで、バナーに十分な垂直スペースを設けなかった場合

広告の応答

応答の形式

tapLinkから返される広告は有効なXHTMLです。 XHTMLには多くの利点があり、広告主の商品価値を高めることができます。

  • XHTMLを使用すると、サポート対象の機種でのJavascript広告やリッチメディア広告など、広告主がリクエストしているリッチな広告ユニットに対応することができます。
  • XHTMLを使用すると、広告の応答にトラッキングピクセルを導入することができます。
  • XHTMLを使用すると、現在のインテグレーションを変更することなく、今後も追加の広告タイプや機能を導入することができます。

スタイル情報の追加

スタイル情報を<DIV>タグで囲むことによって、応答にスタイル情報を追加することができます。 一般的なスタイル変更には、バナーの中央揃え、バナーの下のテキストの中央揃え、バナーのテキストの色変更などがあります。

応答の処理

広告の応答は変更なしで全文表示されます。 応答を解析したりその他の方法で変更すると、予期しない/望ましくない動作につながることがあります。 たとえば、画像とクリックを解析すると、応答に含まれるトラッキングピクセルも無視されるため、サードパーティによる追跡キャンペーンが行えなくなります。

クリエイティブの仕様

tapLinkでは、MMA携帯広告ガイドの2008年10月改訂版に準拠したバナーをサポートしています。

またtapLinkでは、iPhone用に最適化されたバナーやインタースティシャルもサポートしています。

バナータイプ機種例メモ
iPhoneインタースティシャルlApple iPhone / iTouch
  • サイズ： 320 x 415ピクセル
  • サポートされているファイルの種類： .gif、.png,、jpg
iPhone用に最適化されたバナーlApple iPhone / iTouch
  • サイズ： 320 x 50ピクセル
  • サポートされているファイルの種類： .gif、.png,、jpg
バナー(特大)
  • Apple iPhone/iTouch
  • Google G1
  • Nokia E70
  • Palm Treo 700p
  • サイズ： 300 x 50ピクセル
  • サポートされているファイルの種類： .gif、.png,、jpg
バナー(大)
  • LG VX-8500 Chocolate
  • Samsung MM-A900
  • サイズ： 216 x 36ピクセル
  • サポートされているファイルの種類： .gif、.png,、jpg
バナー(中)
  • LG VX-8000
  • Motorola RAZRs
  • Motorola ROKR E1
  • サイズ： 168 x 28ピクセル
  • サポートされているファイルの種類： .gif、.png,、jpg
バナー(小)
  • Motorola V195
  • サイズ： 120 x 20ピクセル
  • サポートされているファイルの種類： .gif、.png,、jpg
バナーのCall-to-action テキスト
  • すべて
  • サイズ：
    • 24文字 X-Large
    • 18文字 Large
    • 12文字 Medium
    • 10文字 Small
  • サポート対象： テキスト、アクセント記号付き文字

MMAガイドラインは http://mmaglobal.com/mobileadvertising.pdfでご覧いただけます。

サンプル応答

標準テキストバナー 

<a href="http://...">Vonage</a><br/>
Low Phone Rates!<br/>

標準画像バナー 

<a href="http://...">
	<img src="http://..." width="300" height="50" />
</a><br/>

標準画像/テキストを組み合わせたバナー 

<img src="http://..." width="300" height="50" /><br/>
<a href="http://...">Low Phone Rates!</a><br/>

トラッキングピクセル付きの画像バナー 

<div>
<img src="http://..." width="300" height="50" /><br/>
<a href="http://...">Low Phone Rates!</a><br/>
<img src="http://pixelurl.com" height="1" width="1" border="0" alt="">
</div>

2つのトラッキングピクセル付きの画像バナー 

<div>
<img src="http://..." width="300" height="50" /><br/>
<a href="http://...">Low Phone Rates!</a><br/>
<img src="http://pixelurl.com" height="1" width="1" border="0" alt="">
<img src="http://pixelurl2.com" height="1" width="1" border="0" alt="">
</div>

使用可能な広告がない場合 

ゼロ長の応答本文。

エラー処理とコード

このセクションでは、tapLinkがエラー条件にどのように対応するかを説明します。 エラーは標準のHTTPステータスコード一覧からクライアントに報告されます。

広告が返されないリクエストは標準的動作と見なされ、エラーとは見なされません。 XHTML応答では、ゼロ長のコンテンツ本文が得られます。

HTTPステータスコード

ステータスコード 説明
200リクエストが正常に完了したことを示す応答。
201この応答コードは、イベント報告アクティビティがtapLinkで正常にログ記録された場合に返されます。
400必須パラメータの一部が指定されていない場合や、必要なパラメータの1つに無効なパラメータが含まれている場合に、不正なリクエストステータスが送信されます。
401不適切な資格情報がリクエストと一緒に送信された場合に送信されます。
403IP制限が有効な場合に送信されます。
404アドスポットや広告プロバイダーが存在しない場合に送信されます。
500サーバー側に予期しないエラーが発生した場合に送信されます。
503現在サービスを使用できない場合に送信されます。

タイムアウト

パブリッシャーはtapLinkから返されたエラーに対応する責任があります。 またパブリッシャーは、クライアントアプリケーションに適切なソケット、接続および読み取り/アイドルタイムアウト値を設定する必要があります。

パブリッシャーはJumptapと協力して、パブリッシャーが開発したアプリケーションのタイプに基づいて、適切なタイムアウト値と再試行ポリシーを決定してください。 これらのタイムアウトの設定は、基盤となるHTTPクライアントライブラリ実装によって異なります。

「http://support.adjust-sp.jp/wiki/index.php/Publisher_integration_guide」より作成