Real-time Postback API

Owned by Jen Yoon (Unlicensed)
Last updated: Mar 07, 2022 by Olivia Kim
4 min read

To provide user with rewards through Buzzvil products, server-to-server integration between Buzzvil server and publisher’s server is necessary.

Index

Introduction

This API is used to send the request to publisher regarding the rewards earned by users via BuzzScreen, BuzzAd and BuzzAd Benefit SDK.

Content

Details

Content

Details

1

Request Direction

BuzzScreen → Publisher Server

2

HTTP Request method

POST - application/x-www-form-urlencoded

3

HTTP Request URL

Defined by publisher

4

HTTP Request Parameters

Refer to the table below

5

HTTP Response Code

BuzzScreen determines the success of the request based on the response code received from the publisher.

  • 200 (ok): Success

    • The code when the publisher server processed the request properly.

  • Response code other than 200: BuzzScreen retries the request to the publisher server up to 5 times exponentially within 24 hours.

    • Retries exponentially - 1 minute, 10 minutes, 1 hour, 3 hours, 24 hours

Note that even if the body contains an error, BuzzScreen will not retry if the response code is 200.

 

HTTP Request Parameters

There are two types of postback depending on the types of ads. Please refer to the table below for the field values included in each postback for each type.

  • Impression ads (impression type → imp)

    • base reward via Buzzscreen

    • reward via CPC, CPM type ads

  • Action type ads (action type → act)

    • reward via CPY (video), and all action-related ads (when action_type is a)

파라미터 필드(Field)

타입
(Type)

설명

파라미터 필드(Field)

타입
(Type)

설명

user_id

REQUIRED

String 
(max 255)

User_id defined by publisher

  • userId set via BuzzAd Benefit SDK’s UserProfile builder

transaction_id

REQUIRED

String 
(max 32)

Use this to prevent duplicate rewards payouts.

  • If there exists a record with the same transaction_id in your server, don't give out the rewards to prevent duplicated payment.

The maximum length of transaction_id is 64, so make sure that your system supports it beforehand.

point

REQUIRED

Integer

The total reward points rewarded to a user.

unit_id

REQUIRED

Long

Unit id set for the Buzzvil ad inventory

The normal length of this value is 15

title

REQUIRED

String
(max 255)

The name of the ad a user participated in.

  • Ad (Name of the participated ads)

    • e.g 출시 임박! 해당 CPS 상품을 먼저 만나보세요! 😁 #Buzzvil #환상적

  • Others

    • empty

action_type

REQUIRED

String
(max 32)

The type of action that the user has done in order to get the point.
New types can be added later.

  • u: unlock

  • l: landing

  • a: action(For CPA type - execute, sign up...)

  • won: For Potto integration

  • walked: For pedometer integration

event_at

REQUIRED

Long (timestamp)

The timestamp of the reward event. (UNIX Timestamp)

extra

REQUIRED

String
(max 1024)

Json serialized strings of campaign data defined by publisher.
(It can be set in the dashboard when creating ad campaigns.)

eg) {"sub_type": "A", "source":"external"}

data

OPTIONAL

String

Use this parameter when the parameters are encrypted. Please refer to the below for more information.

c

OPTIONAL

String

Use this parameter when Checksum is used.

 

Request Parameter Validation optional

1. Add Checksum Parameter

Used to add Checksum parameter to validate the postback data. Data validation method is HMAC verification and it uses SHA-256 algorithm.

Requirement

  1. Ask account manager for hmac_key (MAX 64)

Procedure

  1. Create a string called msg with parameters(transaction_id, user_id, campaign_id, point) from the postback as shown below.

    1. Note : msg has to be encoded and there are no space around each colon.

      msg=u'{0}:{1}:{2}:{3}'.format( params['transaction_id'], params['user_id'], params['campaign_id'], params['point'], ).encode('utf-8')

       

  2. Use HMAC SHA-256 algorithm to encode msg.

    • key: hmac_key

    • data: msg

  3. Compare the result value to the value in field c from the postback for verficiation.

    • Length of result value: 64 characters

Example

  • hmac_key = 12345678abcdefgh12345678abcdefgh12345678abcdefgh12345678abcdefgh

    { "transaction_id": 429482977, "user_id": "testuserid76301", "campaign_id": 3467, "point": 2, "c": "57a11e913980277b6fb628ca0aa8bf09f8dc368015a9d53db56299d5c6121998" }

     

  • msg = 429482977:testuserid76301:3467:2

 

2. HTTP Request Parameter Encryption/Decryption

This is used when you want to encrypt the HTTP Request parameter sent from the Buzzvil server to the media company. The encryption method provided is the Advanced Encryption Standard, AES (Advanded Encryption Standard). The provided block encryption is AES-256, and the used block encryption mode (Block Cipher) uses CBC (Cipher Block Chaning) Mode and PKCS7.

Please follow the process below in order.

Requirement

  1. Ask account manager for AES Key (Max 32) and AES IV (Max 16)

Procedure

  1. Buzzvil server encrypts parameters in the order as follows.

    1. JSON serialized parameters with UTF-8 encoding

    2. AES(CBC mode, PKCS7 padding) encryption

    3. base64 encoding

  2. Encrypted data should be sent as data parameter in HTTP POST request.

    1. e.g

      { "data": "cg087LiIp30jCWpc3MVLfxPL4F05OFGGCkQwwpS6pRVMZhkumzfTFxc8iBoZ8unI15uk0cmY+CbSeOaLHsd7PaxsbyKISiJ31WJJ1OwfaYttoMwFysKNfL7pSz2HB9ULWZicG8MSPxCPKr9RDqgOXpuEoVm9YR3I4yNE5M0LNltpCTdXRBjTrOcjp+RtEZ1VENtHqTICK18nDqO+91BUt3AJsf4VmzogJ8UpA0izEbY=" }

  3. When receiving it, data parameter from HTTP POST request should be decrypted as below.

    1. base64 decoding

    2. AES decoding and remove PKCS7 padding

    3. UTF-8 decoding

Example

  • AES key and IV value in the example are both buzzvil123456789.

  • Example in plaintext

  • Example in ciphertext

    • JSON (UTF-8encoding) → AES encryption → base64 encoding

  • decrypted version of the above string is as follow

    • base64 decoding

    • AES decryption) Key, IV: buzzvil123456789

    • UTF-8 decoding