• デベロッパーガイド
  • Ad Partners

Airbridgeインテグレーションガイド

本ガイドはAirbridgeとメディアパートナー間のトラッキングリンク(Tracking Link)及びポストバック(Post Back)URL連携について記載しています。

連携開始の前に、下記の連携要請フォームを作成してお送りいただければ迅速に連携担当者をアサインし、詳細プロセスをご案内します。

下記のガイドを参考にトラッキングリンクテンプレート及びポストバックURLを構成してください。

1. トラッキングリンクテンプレートの設定

1) 基本パラメータの追加

Airbridgeのトラッキングリンクから取得できるデータの種類は下記の通りで、必須値が存在します。

Tracking Link内にADID追加を推奨

現在、トラッキングリンクテンプレート内のADIDは必須値ではありませんが、iOS 14.5のアップデート政策によりフィンガープリントを利用できなくなったため、ATT(AppTrackingTransparency)フレームワークを通じてオプトインをしたユーザーのIDFA値を最大限活用してアトリビューション(Attribution)を分析できるように、当該パラメータの追加を推奨します。

Airbridgeのトラッキングリンクに必須で追加が必要なマクロは御社の「Click ID」、「Publisher ID」です。当該マクロを含め、御社からご提供可能なマクロリストや別途ドキュメントがある場合、ご共有いただければこちらでトラッキングリンクテンプレートを作成し、システムに登録いたします。
例) https://abr.ge/@APP_NAME/MEDIA_NAME?click_id={CLICK_ID}&sub_id={SUB_ID}&gaid_raw={GAID}&ifa_raw={IDFA}

2) カスタムパラメータの追加

上記ご案内のパラメータ以外にもタッチポイントが発生した時、メディアの特定データを収集し、Postbackで取得したい値がありましたら、トラッキングリンクテンプレートにカスタムでパラメータを追加することができます。カスタムパラメータのKeyは御社ご希望の値を追加してください。
例) https://abr.ge/@APP_NAME/MEDIA_NAME?click_id={CLICK_ID}&sub_id={SUB_ID}&gaid_raw={GAID}&ifa_raw={IDFA}&custom_param1={MACRO1}&custom_param2={MACRO2}

3) トラッキングリンクの動作

クリックまたは閲覧用のトラッキングリンクの呼び出しをすれば、事前に協議されたトラッキングURL内のマクロに実際の値を埋め込んでデータが送信(トラッキングリンクURLを呼び出す)されます。下記の例をご参考ください。

[トラッキングリンクURLテンプレート及び実際の呼び出し] https://abr.ge/@airbridge/ab180_ads?click_id={TOUCHPOINT_ID}&ad_id={ADID}&sub_id={PUBLISHER_ID}→ https://abr.ge/@airbridge/ab180_ads?click_id=abcf15142ads&ad_id=94ec0320-7f08-11e6-bdf4-0800200c9a6 6&sub_id=abzdo_16345

2. ポストバックURLテンプレートの設定

Airbridgeのお客様がダッシュボードの中で設定したチャンネル別のポストバック送信オプション(アトリビューション有無及び新規イベントの有無によるポストバック送信)によって、Airbridgeでトラッキングしたお客様のイベント及びアトリビューション関連情報をポストバックでリアルテイムで受け取ることができます。

ポストバックを受信するには、下記のようにイベントの種類別にそれぞれのポストバックURLテンプレートをAirbridgeシステムに登録する必要があります。

  1. 設置(install)用のポストバックURLテンプレート

  2. インアップイベント(In-app Events)用のポストバックURLテンプレート

もし、イベントの種類別にポストバックURLテンプレートが同じなら、1つのポストバックURLテンプレートのみ構成してお送りください。ポストバックURLテンプレートの構成のための詳細スペックは下記の内容をご参考ください。

1) Airbridgeのイベントの種類

Airbridgeのポストバックで提供可能なイベントは「Airbridge基本イベント(Standard Event)」と「お客様ごとのカスタムイベント(Custom Event)」に分けられます。

設置イベントから購入完了イベントまではAirbridgeの基本イベント(Standard Event)で、全てのお客様に共通イベントリストとして提供しています。

ポストバックを送信する際に、各イベントに対して特定のイベント名(例えば、会員登録イベントに対して'airbridge.user.signup'ではなく'Registration'で取得)や特定イベントを意味するID('airbridge.user.signup'の代わりに数字のID 7)で取得したい場合、各イベントごとにマッピングテーブルをご共有いただければその値で送信することも可能です。ご希望の値がなければ、上記の表の「Event Name (raw)」に記載されている値でお送りします。

カスタムイベント(Custom Event)はお客様のサービスごとに設定及びトラッキングするイベントです。お客様ごとに異なるインアップイベント名が使われ、お客様の設定値がそのままポストバックURLのイベント名として送信されます。もし、お客様のカスタムイベントも他の値に変換して送信する必要がある場合はご要請をお願いします。

2) ポストバックURLテンプレートで提供可能データ及びマクロ

AirbridgeでポストバックURLを通じて提供するデータの種類は、下記のAirbridgeポストバックスペック(Postback Spec)シートでご確認ください。

ポストバックで取得したいデータは「ポストバックスペック」シートでプラットフォーム別のイベント(WebイベントまたはAppイベント)に応じて「Web」または「App」カラムに「1」と記載されている項目をご参考ください。当該データをポストバックURLテンプレートに追加する際には、「フィールドリュー(Field Value)」列の値を中括弧('{','}')の中に入れたマクロの形でお使いください。例えば、ポストバックでAirbridge Device IDの値を受け取るには’{device.deviceUUID}’を御社のKeyとマッピングします。

3) ポストバックURLテンプレートの必須パラメータ(必須)

万が一の重複送信防止及びイシュー発生時の円滑なトラブルシューティングのため、ポストバックURL内に下記2つのパラメータは必須で追加してください。

(a) ポストバックでイベント発生時間のデータを収集する場合、御社のパラメータとマッピングしてポストバックURLに追加する必要があります。もし、イベント発生時間のデータを収集しない場合でも、 'event_timestamp={eventTimestamp}'のように関連パラメータを任意で追加し、御社の社内システムで当該パラメータによるエラーが発生しないようにする作業が必要です。

(b) ポストバックでデバイスアイデンティファイア(Device Identifier)を収集する場合、御社のパラメータとマッピングしてポストバックURLに追加する必要があります。もし、Web広告枠を保有しているなどの理由でデバイスの識別子を収集しない場合でも、{device.deviceUUID} & {device.DeviceUUIDType}または{device.gaid} & {device.ifa}パラメータにより、御社の社内システムでエラーが発生しないようにする作業が必要です。 * deviceUUIDは計4つのタイプのDeviceID(GAID,IDFA,IDFV,Random Generated)が取得されることがありますので、deviceUUIDTypeマクロも一緒に追加してください。

4) 製品関連イベントの商品データ

カートに入れる、購入完了のように製品(Product)に関連したイベントには複数の製品データが存在する場合があります。ポストバックでは、このような複数の製品データをJSONの形で受け取ることができます。

ポストバックURLテンプレートにはJSONで様々な製品データを受け取るための御社のパラメータキー(Key)に{@postback.jsonData}をマッピングして追加し、JSONで受け取りたい製品関連データをマッピングしてポストバックURLテンプレートと一緒にお送りください。大括弧、中括弧などのJSONに関する文法的な要素は、御社の社内フォーマットに応じて自由に設定できます。

また、テンプレートを構成する際には、JSONデータ内で繰り返される部分とそうでない部分を明確に区別するために{@for ... in ...}文法を使います。

下記の例のように、テンプレートの{@for product in eventData.goal.semanticAttributes.products}と {@endfor}の間が繰り返されています。それぞれの商品には{product.}でアクセスできます。{product.}で活用できる値は下記のテーブルをご参考ください。

例) ...&product_info={@postback.jsonData}&...
例) {@postback.jsonData}で送られるJSONテンプレート

[ {@for product in eventData.goal.semanticAttributes.products} { "event_item_id": {product.productID}, "quantity": {product.quantity}, "unit_price": {product.price}, "currency_code": {product.currency}, "event_item_name": {product.name} }, {@endfor} ]

5) ポストバックURLの動作

Airbridgeは、固有のアトリビューションモデルを通じてコンバージョンイベントの発生に貢献したタッチポイントを選定します。その後、事前に御社と合意したポストバックURLに値を埋め込み、コンバージョンに関連する最終データをお送りします。
この時、カスタムパラメータの場合、ポストバックURLを構成する際に当該パラメータがトラッキングリンクパラメータであることを区別するため、@trackingLink. prefixをつける必要があります。(例: {@trackingLink.custom_param})下記の例をご参考ください。

[ポストバックURLテンプレート及び実際の呼び出し] https://api.example-ad-channel.com/postback/airbridge?touchpoint_id={attributionResult.attributedClickID}& ad_channel={attributionResult.attributedChannel}&event_timestamp={eventTimestamp}&customID={@trackin gLink.custom_param}
→https://api.example-ad-channel.com/postback/airbridge?touchpoint_id=e7580180-7f04-11e6-bdf4-0800200c 9a66&ad_channel=sample_channel&event_timestamp=1479186394000&customID=4093721

よくあるご質問

  1. タイムスタンプ(Timestamp)を1秒単位に変換することは可能ですか？

    ⇒ Airbridgeの全てのタイムスタンプフィールドは基本的に1ミリ秒(millisecond)単位を採用しています。これを1秒(second)単位に変換するには、変換したいタイムスタンプフィールドの値にInSecをつけてください。(例: {requestTimestamp} → {requestTimestampInSec})

  2. booleanタイプフィールドをintタイプに変換できますか？ ⇒ Airbridgeポストバックスペックシートのフィールド値のうち、booleanタイプのフィールドに限定して:intをつけてタイプを変換できます。trueは1、falseは0に変換されます。
    (例: {@postback.isAttributedToTargetChannel} → {@postback.isAttributedToTargetChannel:int})
    連携方法について追加のご質問は、Airbridgeプラットフォームチーム(platform@ab180.co)までお問い合わせください。