ポイント付与Postback APIの連携

本文書は開発者向けドキュメントです。

ユーザーがBuzzvilプロダクトを通じてリワードポイントの付与を受けるには、Buzzvilとパブリッシャー間でポイントシステムの連携が必要です(S2S接続)。本ドキュメントにはポイント付与を実現するためのサーバー連携に関する技術情報を記載しています。

自社ポイントシステムと連携方法の選択

自社ポイントシステムを持っているかどうかによって連携方法が異なります。

下記の手順で連携を行います。

Buzzvilからのポイント付与リクエストを受け取れるサーバーエンドポイントを構築(該当のエンドポイントのURLのを"postback url"とする)
本ガイドに従ってServer-To-Sever連携を行う
Buzzvil担当者にpostback urlを伝える

パブリッシャーアプリをアメリカまたは複数の国・地域で展開する場合、Buzzvil担当者まで事前にお知らせください。

アプリ内にBuzzvilのポイントシステム(BuzzStore) を連携します。詳しくはBuzzvil担当者までお問い合わせください。

Index

- 1.1 自社ポイントシステムと連携方法の選択
2 イントロダクション
- 2.1 HTTP Request Parameters(リクエストパラメータ)
3 リクエストパラメータの検証オプション
- 3.1 1. HTTP Request Parameterの暗号化と復号
  - 3.1.1 手順
  - 3.1.2 暗号化と復号化の例

イントロダクション

このAPIはBuzzScreen SDK, BuzzAd SDKを通じてユーザーがリワードポイントの付与を受ける場合において、パブリッシャーにこの事実を伝達し、ポイント付与リクエストを送信するためのものです。

	項目	内容

	項目	内容
1	送信方向	Buzzvil → パブリッシャー
2	HTTP Request method	POST - application/x-www-form-urlencoded
3	HTTP Request URL	パブリッシャー側で定義
4	HTTP Request Parameters	下記の表を参照
5	HTTP Response Code	パブリッシャー側から受けた応答コードによって該当のPostbackリクエストの成功可否を決定 200 (ok): 成功パブリッシャーサーバーからのリクエストを正常に処理した場合の応答コードその他の応答コード: Buzzvilサーバーは24時間以内に最大5回まで再試行を行います。再試行を行う時間: 1分後・10分後・1時間後・3時間後・24時間後 Buzzvilサーバーは応答内容(body)を確認しません。リクエストの応答内容にエラーが含まれていても応答コードが200の場合、成功とみなします。

HTTP Request Parameters(リクエストパラメータ)

ポイント付与Postbackはポイントを付与する状況によって下記の2タイプに分けられて転送されます。各タイプ別のフィールド値は下記の表を参照してください。

ディスプレイ型
- CPC・CPM広告によって発生したポイントを付与する場合
アクション型
- CPC・CPM以外の広告によって発生したポイントを付与する場合(下記パラメータのうち action_type が a の場合に該当)

フィールド	対応	説明

フィールド	対応	説明
`user_id` 必須	String (max 255)	パブリッシャー側で定義したユーザー識別子
`transaction_id` 必須	String (max 32)	ポイント重複付与を防ぐためのid 最大32字まで伝達可能で、連携時に確認が必要です。 ★ 同じ `transaction_id`でリクエストを受け取った場合には必ずポイント重複付与が行われないように処理する必要があります。
`point` 必須	Integer	ユーザーに付与されるポイントの合計
`unit_id` 必須	Long	広告枠を区分するID値
`title` 必須	String (max 255)	ポイントが付与された方式に設定された名前広告 (参加した広告のキャンペーン名) e.g `まもなく発売の新商品を一足早くチェック!😁 #Buzzvil #オトク` その他はすべて空の値になる ex. 万歩計/Potto ( 現在日本では対象なし)
`action_type` 必須	String (max 32)	ポイントの付与を受けるためにユーザーが行ったアクション `u`: ロック解除 `l`: LP遷移 `a`: アクション(広告の指定アクションが実行された時)
`event_at` 必須	Long (timestamp)	ポイント付与時点 (UNIX Timestamp 秒単位) Timestampの照会: https://www.epochconverter.com/
`extra` 必須	String (max 1024)	パラメータを追加した場合、json serializeされた文字列を表示パブリッシャーが定義したキャンペーンデータが(管理画面上でキャンペーンを設定した場合に指定可能です) e.g `{"sub_type": "A", "source":"external"}`
`data` オプション	String	HTTP request parameterを暗号化して転送する場合に使用するパラメータ

リクエストパラメータの検証オプション

1. HTTP Request Parameterの暗号化と復号

Postbackの際、Buzzvilサーバーからパブリッシャーのサーバーにパラメータを送信します。このパラメータの暗号化を希望する場合は下記の手順で行います。なお、この設定は任意であり、必須ではありません。

提供可能な暗号化方式は暗号化の標準であるAES(Advanded Encryption Standard)です。提供されるブロック暗号化はAES-256 で、ブロック暗号化モード(Block Cipher)はCBC(Cipher Block Chaning) Modeと PKCS7を使用します。

手順

暗号化キーの発行
1. Buzzvil担当者との事前協議
2. Buzzvil担当者に暗号化キー(AES key, IV 値)の発行を依頼する
Buzzvil serverにて下記順序でパラメータを暗号化
1. JSON serialized parameters with UTF-8 encoding
2. AES(CBC mode, PKCS7 padding) encryption
3. base64 encoding
HTTP POST requestにdataパラメータを追加した状態で暗号化されたデータを送信
受信側(パブリッシャー)は HTTP POST requestにてdata パラメータを取得し、下記順序で復号する
1. base64 decoding
2. AES decoding
3. JSON load

暗号化と復号化の例

元データ(Original)
例ではAES key, IV 値としてすべて 12341234asdfasdfを使用

{
    "event_at": 1442984268, 
    "user_id": "testuserid76301", 
    "action_type": "u", 
    "extra": "{}", 
    "is_media": 0, 
    "base_point": 2, 
    "point": 2, 
    "campaign_name": "test campaign", 
    "campaign_id": 3467, 
    "transaction_id": 429482977
}

暗号化の結果
- JSON (UTF-8encoding) → AES encryption → base64 encoding の順に行う
  sgfHOC5Z66tLmlokmQEaXY39u+64gMWhLnxQAZ9ivYsTvF1isjVfaRx2BNhOADwPR6KB55/7F7iXBm5FKU8mHmHnlR3wSomVAlcjtx77KluoYoXi/jRCvaFLGIo7vcK1GVHxS557u/XTo53/AzdPZpk/aXkvFZvWPgS+GWj1TWle0mBJ0xOgfmb8LwMfi4rvfayTph3bZeryLuphorBzMoIhf+kQLyjfIyouWVoCh6UICeRBgzTS9SlgdUA6M1PVlCsQch0zKVeTJZEFEn8478QbpEEhgHDhXkzdo8tXgkw=
復号するには
- base64 decoding)
  \xb2\x07\xc78.Y\xeb\xabK\x9aZ$\x99\x01\x1a]\x8d\xfd\xbb\xee\xb8\x80\xc5\xa1.|P\x01\x9fb\xbd\x8b\x13\xbc]b\xb25_i\x1cv\x04\xd8N\x00<\x0fG\xa2\x81\xe7\x9f\xfb\x17\xb8\x97\x06nE)O&\x1ea\xe7\x95\x1d\xf0J\x89\x95\x02W#\xb7\x1e\xfb*[\xa8b\x85\xe2\xfe4B\xbd\xa1K\x18\x8a;\xbd\xc2\xb5\x19Q\xf1K\x9e{\xbb\xf5\xd3\xa3\x9d\xff\x037Of\x99?iy/\x15\x9b\xd6>\x04\xbe\x19h\xf5Mi^\xd2`I\xd3\x13\xa0~f\xfc/\x03\x1f\x8b\x8a\xef}\xac\x93\xa6\x1d\xdbe\xea\xf2.\xeaa\xa2\xb0s2\x82!\x7f\xe9\x10/(\xdf#*.YZ\x02\x87\xa5\x08\t\xe4A\x834\xd2\xf5)`u@:3S\xd5\x94+\x10r\x1d3)W\x93%\x91\x05\x12\x7f8\xef\xc4\x1b\xa4A!\x80p\xe1^L\xdd\xa3\xcbW\x82L
- AES decryption) Key, IV: 12341234asdfasdf
- UTF-8 decoding
  (memo) 上の例では日本語文字が含まれていないためUTF-8 decoding を行わなくても同じ結果が得られます

開発言語別のコード例は下記のとおりです。