Page Comparison

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

Proceed with the following steps:

Establish a server endpoint that can receive requests for reward from Buzzvil (the endpoint is referred as postback url)
Server-To-Server integration according to this guide
Forward postback url to your account manager

Note
Please consult with your account manager before proceeding with the integration.

Index

Table of Contents

maxLevel	3
exclude	\bIndex\b

...

This API is used to send the request to publisher regarding the rewards earned by users via BuzzScreen, BuzzAd and BuzzAd Benefit SDK. DrawiocontentId407371777simple0zoom1pageId384696503diagramDisplayNamepoint_request_general.drawiolbox1contentVer1revision1baseUrlhttps://buzzvil.atlassian.net/wikidiagramNamepoint_request_general.drawiowidth661linkstbstyleheight241

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
Note that even if the body contains an error, BuzzScreen will not retry if the response code is 200.

...

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)

Description

base_point

파라미터 필드(Field)

타입
(Type)

imp

설명

act

user_id

Status

app_key

colour

Long

Green

O

title

O

Identifier for ad inventory.

app_key for BuzzScreen
app_key for BuzzAd
unit_id for each type of BuzzAd Benefit

unit_id

Integer

O

The value is the same as that of app_key

It’s the same definition of app_key

transaction_id

String
(max 64)

O

REQUIRED

String
(max 255)

User_id defined by publisher

userId set via BuzzAd Benefit SDK’s UserProfile builder

transaction_id

Status

colour	Green
title	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.

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

title

user_idpoint

String
(max 255)

O

User_id defined by publisher

userId set via BuzzScreen SDK’s setUserId
userId set via BuzzAd SDK’s BuzzAd.showOfferWall
userId set via BuzzAd Benefit SDK’s UserProfile builder

campaign_id

Long

O

Campaign id that offered reward points

If action_type is u (unlocked): ID of the ad/content upon unlock
If action_type is l or a (ad landing or participation): ID of the ad

campaign_name

String
(max 255)

O

Campaign name that offered reward points

Info
The maximum length of campaign_name is 255, so make sure that your system supports it beforehand.

Status

colour	Green
title	REQUIRED

Integer

The total reward points rewarded to a user.

unit_id

Status

colour	Green
title	REQUIRED

Long

Unit id set for the Buzzvil ad inventory

Note
The normal length of this value is 15

title

Status

colour	Green
title	REQUIRED

String
(max 255)

X

O

The name of the ad a user participated in.

point

Integer

O

The total reward points rewarded to a user.

It is the sum of base_point and the original points of participated campaign.

Integer

O

X

Point rewarded to the user to a user at each base point period.

If the base point period has not been fulfilled, 0 is assigned.

Note
If `action_type` is `a`(which means that the reward is earned through user's action - eg. CPA/CPI campaigns), these parameters are not included.

is_media

Integer

O

0: Campaigns from Buzzvil
1: Campaigns from Publisher

revenue_type

String
(max 32)

O

Type of ad

cpi: cost per install (install only)
cpe: cost per engagement (install + open)
cpa: cost per action (action required by advertiser)
content : Set as null

action_type

Ad (Name of the participated ads)
- e.g 출시 임박! 해당 CPS 상품을 먼저 만나보세요! 😁 #Buzzvil #환상적
Others
- empty

action_type

Status

colour	Green
title	REQUIRED

String
(max 32)

O

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...)

Please take into consideration that new types may be added later

won: For Potto integration
walked: For pedometer integration

추후 다양한 타입이 추가될 수 있습니다.

event_at

Status

colour	Green
title	REQUIRED

Long (timestamp)

O

The timestamp of the reward event. (UNIX Timestamp)

Timestamp query: https://www.epochconverter.com/

Mostly, it's the same as the time of API request. However, it could vary in case there was the second trial of request.

extra

Status

colour	Green
title	REQUIRED

String
(max 1024)

O

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"}

Note
It might take up to 10 mins to apply updated information in case these `extra` data were changed in the middle of ongoing campaign.

unit_price

decimal (18,9)

X

O

The unit price of campaign provide to the publisher

custom

String
(max 64)

X

O

The value is the same as that of user_id value (For action type ads)

ifa

String
(max 64)

X

O

The users’s ad id (AOS: Google Ad ID, iOS: IDFA)

reward

Integer

X

O

The total reward points rewarded to a user (For action type ads)

The value is the same as that point value.

allow_multiple_conversions

0 or 1

X

O

0: Can participate in the same ad only once
1: Can participate in the same ad multiple times (e.g. some video ads)

data

String

Status

title	optional

data

Status

colour	Red
title	OPTIONAL

String

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

Info
This is only included when parameter encryption is enabled. (please refer to 5. HTTP Request Parameter Encryption)

c

Status

colour	Red
title	OPTIONAL

String

Use this parameter when Checksum is used.

Info
Please refer to Add Checksum Parameter below.

Request Parameter Validation
Status
title optional

...

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

...

Requirement

Ask account manager for hmac_key. (MAX 64)

Procedure

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

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

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

Use HMAC SHA-256 algorithm to encode msg.
- key: hmac_key
- data: msg
Compare the result value to the value in field c from the postback for verficiation.
- Length of result value: 64 characters

...

2. HTTP Request Parameter Encryption/Decryption

Guide for decrypting data parameter when HTTP Request Parameter Encryption is enabledThis 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.

Procedure

...

Please request for AES key and IV value to your account manager.

...

Requirement

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

Procedure

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

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

e.g

Code Block

language	json

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

When receiving it, data parameter from HTTP POST request should be decrypted as below.
1. base64 decoding
2. AES decoding JSON loadand remove PKCS7 padding
3. UTF-8 decoding

Example

AES key and IV value in the example are both 12341234asdfasdf buzzvil123456789.
Example in plaintext

Code Block

language	json

{
  "unit_id":"12345",
  "transaction_id":"10000000_1",
  "user_id": "testuserid76301buzzvil",
  "point": 1,
  "action_type":"won",
  "u"event_at": 1599622182,
  "title":"title",
  "extra": "{}", 
    "is_media": 0,
    "point": 2,
    "campaign_id": 3467,
   
}

Example in ciphertext
- JSON (UTF-8encoding) → AES encryption → base64 encoding

Code Block

cg087LiIp30jCWpc3MVLfxPL4F05OFGGCkQwwpS6pRVMZhkumzfTFxc8iBoZ8unI15uk0cmY+CbSeOaLHsd7PaxsbyKISiJ31WJJ1OwfaYttoMwFysKNfL7pSz2HB9ULWZicG8MSPxCPKr9RDqgOXpuEoVm9YR3I4yNE5M0LNltpCTdXRBjTrOcjp+RtEZ1VENtHqTICK18nDqO+91BUt3AJsf4VmzogJ8UpA0izEbY=

decrypted version of the above string is as follow

base64 decoding

Code Block

r\r<\xec\xb8\x88\xa7}#\tj\\\xdc\xc5K\x7f\x13\xcb\xe0]98Q\x86\nD0\xc2\x94\xba\xa5\x15Lf\x19.\x9b7\xd3\x17\x17<\x88\x1a\x19\xf2\xe9\xc8\xd7\x9b\xa4\xd1\xc9\x98\xf8&\xd2x\xe6\x8b\x1e\xc7{=\xaclo"\x88J"w\xd5bI\xd4\xec\x1fi\x8bm\xa0\xcc\x05\xca\xc2\x8d|\xbe\xe9K=\x87\x07\xd5\x0bY\x98\x9c\x1b\xc3\x12?\x10\x8f*\xbfQ\x0e\xa8\x0e^\x9b\x84\xa1Y\xbda\x1d\xc8\xe3#D\xe4\xcd\x0b6[i\t7WD\x18\xd3\xac\xe7#\xa7\xe4m\x11\x9dU\x10\xdbG\xa92\x02+_\'\x0e\xa3\xbe\xf7PT\xb7p\t\xb1\xfe\x15\x9b: \'\xc5)\x03H\xb3\x11\xb6

AES decryption) Key, IV: buzzvil123456789

Code Block
{"unit_id": "12345", "transaction_id": "10000000_1", "user_id": "buzzvil", "point": 1, "action_type": "won", "event_at":

...

1599622182, "title": "title", "extra": "{}"}

UTF-8 decoding
Code Block
{"unit_id":

...

- "12345", "transaction_id": "

...

10000000_1", "user_id": "buzzvil", "point": 1, "

...

- action_

...

- type":

...

"won", "event_at": 1599622182, "title": "title", "

...

- extra":

...

Example in ciphertext

...

- "{}"}

Versions Compared

Old Version 8

New Version Current

Key

Index

Request Parameter Validation
Status
title optional

Procedure

2. HTTP Request Parameter Encryption/Decryption

Procedure

Requirement

Procedure

Example

Page Comparison

Versions Compared

Old Version 8

New Version Current

Key

Index

Request Parameter Validation Statustitleoptional

Procedure

2. HTTP Request Parameter Encryption/Decryption

Procedure

Requirement

Procedure

Example

Request Parameter Validation
Status
title optional