7. 퍼블리셔 오퍼월 S2S API

Index

1 1. 광고 목록 조회
- 1.1 5) Response Fields
2 2. 광고 참여 요청
- 2.1 4) HTTP Request parameters
- 2.2 5) Response
3 3. 광고 참여 완료
- 3.1 4) HTTP Request parameters
- 3.2 5) Response
4 4. 포인트 적립 포스트백 API 연동
5 부록
6 FAQ
7 가이드 변경 이력

1. 광고 목록 조회

퍼블리셔가 받아볼 수 있는 광고 목록을 조회합니다.

	항목	내용

	항목	내용
1	요청 방향	매체사 → BuzzAd
2	HTTP Request method	GET
3	HTTP Request URL	https://ad.buzzvil.com/api/v1/list
4	HTTP Request parameters	Field 설명 `unit_id` (Integer) : 매체사 식별을 위한 아이디
5	Response	JSON 형식으로 반환 Field 설명은 아래 ‘5) Response Fields' 표 참고

5) Response Fields

Field	Type	Description

Field

Type

Description

ads

list

광고 목록

자세한 아이템은 아래 'ads 세부 항목' 표 참고

code

String

처리 결과 코드

200인 경우에만 정상

msg

String

처리 결과 메세지

`ads` 세부 항목 (Response Fields - ads)

Field	Type	Description

Field	Type	Description
`id`	Integer	광고 아이디 (식별값)
`title`	String	광고 제목
`description`	String	광고 설명
`action_description`	String	광고 적립방법 설명
`icon`	String	아이콘 이미지 주소
`revenue`	String	매체사 단가
`revenue_type`	String	광고 타입. 추후 새로운 타입이 추가될 수 있으므로 연동시 이를 고려해야 합니다. `cpi`: 앱 설치형 `cpe`: 앱 실행형 또는 앱 실행후 액션형 `cpa`: 액션형 `cpl`: 페이스북 좋아요 `cpinsta`: 인스타그램 팔로우 `cps`: 쇼핑 적립형 광고 `cpyoutube`: 유튜브 광고 `cpq`: 퀴즈형 `cpk`: 카카오톡 채널 참여하기 `cpylike`: 유튜브 구독 + 영상 좋아요 광고 `cptiktok`: 틱톡 팔로우 `cpnstore` : 네이버 스마트스토어 찜 `cpqlite` : 퀴즈형 `cpcquiz` : 퀴즈 적립 컨텐츠 예제) “cpc”
`package_name`	String	안드로이드 package_name
`url_scheme`	String	아이폰 url scheme
`platform`	String	광고가 지원되는 플랫폼 `A`: 안드로이드 `I`: 아이폰 `W`: 안드로이드/아이폰 둘 다 지원 해당 파라미터는 광고운영단에서 세팅되는 값이며 W로 내려가는 값을 매체사 측에서 다시 필터링 하여 내리는 경우 올바른 유닛에 광고가 내려가지 않을 수 있음
`age_from`	Integer	나이 하한 타게팅. 타게팅이 없는 경우 `null`
`age_to`	Integer	나이 상한 타게팅. 타게팅이 없는 경우 `null`
`age_ranges`	JSON	다 구간 나이 타게팅. age_ranges를 사용하는 경우 age_from, age_to 값은 무시해도 된다. 타게팅이 없는 경우 `[]` 타게팅이 있는 경우 `[{"from":10, "to":20}, {"from":30, "to":40}]`
`sex`	String	성별 타게팅. 타게팅이 없는 경우 `null` `M`: 남자 `F`: 여자
`relationship`	String	결혼 유무 타게팅. 타게팅이 없는 경우 `null` `S`: 미혼 `M`: 기혼
`carrier`	String	통신사 타게팅. 타게팅이 없는 경우 `null` `kt`: KT 통신사 `skt`: SKT 통신사 `lgt`: LGT 통신사
`udid_required`	Bool	`true`: 광고 참여/참여완료 요청시 udid 파라미터 필수 `false`: 광고 참여/참여완료 요청시 udid 파라미터 필수 아님
`device_name`	String	디바이스 모델 타게팅 콤마(,)로 구분된 디바이스 모델명 OR 조건 ex) `SHV-E250S,SHV-E275K,SM-G928L` → `SHV-E250S` 또는 `SHV-E275K` 또는 `SM-G928L` 인 유저에게 타게팅
`target_app`	String	앱 타게팅 (안드로이드만 지원) 콤마(,)로 구분된 패키지 네임으로, 해당 앱이 설치된 유저에게 타게팅 패키지 네임 앞에 ‘-’ 기호가 있는 경우 설치되지 않은 유저에게 타게팅 OR 조건 ex1) `Pl.idreams.skyforcehd,com.imangi.templerun2` → `Pl.idreams.skyforcehd` 또는 `com.imangi.templerun2` 가 설치된 유저에게 타게팅 ex2) `com.thinkreals.couponmoa,-com.supercell.clashofclans` → `com.thinkreals.couponmoa`가 설치되어 있거나 `com.supercell.clashofclans`가 설치되어 있지 않은 유저에게 타게팅
`region`	String	지역 타게팅 콤마로 구분된 지역: 도/시 단위로 타게팅 가능 OR 조건 ex) `서울특별시 강남구,경상남도` → 서울특별시 강남구 또는 경상남도에 거주중인 유저에게 타게팅
`creative`	list	creative 목록 자세한 아이템은 아래 '`creative` 세부 항목' 표 참고

`creative` 세부 항목 (Response Fields - ads - creative)

Field	Type	Description

Field	Type	Description
`ID`	Integer	creative ID
`short_action_description`	String	짧은 참여방법/주의사항 기재
`height`	integer	native creative 가 세팅 되어 있는 경우 627 (고정값), 없는 경우 0
`width`	integer	native creative 가 세팅 되어 있는 경우 1200 (고정값), 없는 경우 0
`action_description`	String	참여방법 및 주의사항이 기재 22자 권장, 최대 40자
`call_to_action`	String	ex) 팔로워 누르러 가기
`image_url`	String	Native creative가 세팅되어 있을 경우에만 native 타입의 이미지 파일 url이 담김
`icon`	String	오퍼월 리스트내에 볼수 있는 아이콘 이미지

광고 목록 조회 요청 시, Native creative 가 세팅되어 있는 광고만을 선별하여 반환 받을 수 있습니다.

Request parameters 내 아래의 key & value를 포함해주시기 바랍니다.

Key: types
Value: {"NATIVE":[]}

{
    "ads": [
       {
            "id": 1234757, //camapign_id를 의미합니다. 이해를 돕기 위한 임의의 숫자입니다.
            "icon": "https://oooooooooo.cloudfront.net/uploads/1671688583-ZRSHX.png",
            "reward_name": "P",
            "url_scheme": "",
            "package_name": "",
            "target_app": "",
            "action_description": "[참여방법]\n- oooo을 완료하시면 포인트가 지급됩니다.(최초 계좌개설에 한함)\n\n[주의사항]\n- 이미 참여한 이력이 있다면 포인트가 지급되지 않습니다.\n- WIFI가 아닌 환경에서는 데이터 이용료가 발생할 수 있습니다.",
            "description": "캠페인에 참여하세요.",
            "revenue_type": "cpa",
            "image": "",
            "creative": {
                "id": 1170669,
                "creative_type": 1,
                "category": "finance",
                "width": 1080,
                "height": 2340,
                "image_url": "https://ooooooooooo.cloudfront.net/uploads/1675213124-FUZZW_processed.jpg",
                "click_url": "https://ooooooooo.ap1.adtouch.dfinery.io/api/v1/click/nfOTxG3RmEOfUdurAoHShw?m_adid={ifa}&cb_1={cb_param1}&adv_campaign=direct&adv_ad=benefit_50000&adv_adgroup=app_none&adv_agency=money_pocket&adv_creative=make_ing&adv_keyword=direct_display_buzzvill_app_none_benefit_50000_money_pocket_make_ing&adv_placement=display&utm_source=buzzvill&utm_medium=display&utm_campaign=direct&utm_term=display_ad&utm_content=direct_display_buzzvill_app_none_benefit_50000_money_pocket_make_ing",
                "is_deeplink": true,
                "adchoice_url": "",
                "icon": "https://ooooooooooooo.cloudfront.net/uploads/1671688583-ZRSHX.png",
                "background_image_url": "",
                "html": "",
                "description": "캠페인에 참여하세요.",
                "action_description": "[참여방법]\n- ㅇㅇㅇㅇ을 완료하시면 포인트가 지급됩니다.(최초 계좌개설에 한함)\n\n[주의사항]\n- 이미 참여한 이력이 있다면 포인트가 지급되지 않습니다.\n- WIFI가 아닌 환경에서는 데이터 이용료가 발생할 수 있습니다.",
                "call_to_action": "ooooo하기",
                "short_action_description": "캠페인에 참여하세요.",
                "layout_type": 16,
                "landing_type": null,
                "name": "oooo EVENT"
            },
            "platform": "W",
            "age_to": null,
            "age_from": null,
            "age_ranges": [],
            "sex": null,
            "carrier": "",
            "relationship": null,
            "device_name": "",
            "region": "",
            "udid_required": false,
            "title": "계좌개설 EVENT",
            "revenue": 8500.0
        },
        ...
    ],
    "code": 200,
    "msg": "allocate successfully"
}

2. 광고 참여 요청

광고에 참여하기 위해서는 참여 요청 API를 호출하여 참여 가능 여부를 확인해야 합니다.

	항목	내용

	항목	내용
1	요청 방향	매체사 → BuzzAd
2	HTTP Request method	POST
3	HTTP Request URL	https://ad.buzzvil.com/api/v1/participate
4	HTTP Request parameters	Field 설명은 아래 ‘4) HTTP Request parameters’ 표 참고 권장 파라미터를 주지 않는 경우 어뷰징 체크를 더 엄격하게 하므로 가능하다면 전달해주는 것이 좋습니다.
5	Response	JSON 형식으로 반환 Field 설명은 아래 ‘5) Response’ 표 참고

4) HTTP Request parameters

Field	Type	Description

Field	Type	Description
`unit_id`	Integer	매체 아이디
`campaign_id`	Integer	광고 아이디
`ifa`	String	안드로이드 광고 아이디(GAID) 또는 iOS Identifier for Advertiser(IDFA)
`custom`	String	사용자 고유 식별자입니다. 서비스 도중 변하지 않는 고정 값이며, 광고 할당을 위한 필수 정보입니다.
`client_ip`	String	광고 참여한 유저의 ip ex) 123.123.123.123
`udid` 권장	String	안드로이드 IMEI
`android_id` 권장	String	android id
`udid_sha1` 권장	String	sha1 적용한 안드로이드 IMEI
`android_id_sha1` 권장	String	sha1 적용한 android id
`sub_publisher_id` 선택	String	매체사의 하위 매체사 아이디
`sub_publisher_user_id` 선택	String	매체사의 하위 매체사의 유저 아이디
`device_name` 권장	String	디바이스 모델 이름
`carrier` 권장	String	통신사 ex) SKT, UPlus
`google_account_sha1` 권장	String	안드로이드 기기에 등록된 google account sha1 적용 값 복수 개인 경우 가장 첫 번째 account만 전달합니다. `getAccountsByType(”com.google”)` 함수를 이용해 가져올 수 있습니다. 부록 3) “Google account 가져오기 예제” 참고
`custom2` 선택	String	매체사에서 지정하는 커스텀 파라미터 버즈빌에서 매체사로 포스트백 request 시 전달 되는 값 최대 길이는 255 `custom2~4`까지 전달 가능
`custom3` 선택	String	매체사에서 지정하는 커스텀 파라미터 버즈빌에서 매체사 로 포스트백 request 시 전달 되는 값 최대 길이는 255 `custom2~4`까지 전달 가능
`custom4` 선택	String	매체사에서 지정하는 파라미터 버즈빌에서 매체사로 포스트백 request 시 전달 되는 값 최대 길이는 255 `custom2~4`까지 전달 가능

5) Response

Field	Type	Description

Field

Type

Description

code

Integer

처리결과 코드

200인 경우에만 참여 가능: 자세한 내용은 부록 참고

msg

String

처리결과 메세지

landing_url

String

광고주 페이지 랜딩 URL

3. 광고 참여 완료

CPI 광고는 매체사 측에서 사용자가 앱을 설치했는지 여부를 판단하고 BuzzAd으로 API를 통해서 설치 완료 요청을 해야합니다. 성공시 BuzzAd에서 매체사로 리워드 적립 postback가 호출됩니다.

패키지명 확인이 가능하면, 해당 api를 요청합니다.

private fun isInstalled(
        context: Context,
        packageName: String?
    ): Boolean {
        if (packageName == null) {
            return false
        }

        return try {
            context.packageManager.getPackageInfo(packageName!!, 0)
            true
        } catch (e: PackageManager.NameNotFoundException) {
            false
        }
    }

	항목	내용

	항목	내용
1	요청 방향	매체사 → BuzzAd
2	HTTP Request method	POST
3	HTTP Request URL	https://ad.buzzvil.com/api/v1/complete
4	HTTP Request parameters	Field 설명은 아래 ‘4) HTTP Request parameters’ 표 참고
5	Response	JSON 형식으로 반환 Field 설명은 아래 ‘5) Response’ 표 참고

4) HTTP Request parameters

Field	Type	Description

Field	Type	Description
`unit_id`	Integer	매체 아이디
`campaign_id`	Integer	광고 아이디
`ifa`	String	안드로이드 광고 아이디(GAID) 또는 iOS Identifier for Advertiser(IDFA)
`client_ip`	String	광고 참여한 유저의 아이피 ex) 123.123.123.123
`udid` 선택	String	안드로이드 IMEI

5) Response

Field	Type	Description

Field

Type

Description

code

Integer

처리결과 코드

200인 경우에만 정상 처리: 부록 참고

msg

String

처리결과 메세지

4. 포인트 적립 포스트백 API 연동

BuzzAd에서 유저가 목표한 액션을 수행 시 매체사로 보내주는 리퀘스트입니다.

버즈애드에서 포인트 적립이 발생했을 때 버즈애드에서 직접 매체사 유저들에게 포인트를 지급하는 것이 아닙니다. 버즈애드 서버에서 매체사 서버로 포인트 적립 요청을 보낼 뿐이고, 실제 지급은 매체사 서버에서 처리합니다.

부록

1) 처리 결과 코드

코드	설명

코드	설명
200	정상
401	블랙리스트 유저
402	잘못된 ip 주소 형식
1000	시스템 에러
9001	존재하지 않는 unit_id
9004	유효하지 않은 파라미터 (요청에 required field가 누락됐을 경우 발생)
9008	존재하지 않는 캠페인
9011	요청 unit이 inactive 상태인 경우
9013	비활성화된 캠페인
9014	현재 캠페인이 라이브 중이 아니거나, 해당 매체에 타게팅되어 있지 않은 경우
9020	이미 캠페인에 참여한 경우
9021	캠페인이 모두 소진된 경우
9022	광고식별자 수집이 불가한 사용자가 광고식별자 필수 캠페인을 클릭한 경우
9031	알 수 없는 애드네트워크 캠페인 에러
9037	클릭한 사용자가 타게팅 조건에 맞지 않아 참여가 불가능한 경우
9040	광고식별자 형식이 잘못됐거나, 추적이 불가한 식별유형일 경우(e.g. 0000…)

2) 앱 설치 트래킹

iOS/안드로이드에서 앱 설치여부를 트래킹 하는 방법에 대한 간략한 예제입니다. OS에 맞는 항목을 선택하여 자세한 내용을 확인해주세요.

안드로이드

다음 링크를 참조합니다. : http://stackoverflow.com/questions/7470314/receiving-package-install-and-uninstall-events
참여 API 에서 수신받은 패키지명을 안드로이드 로컬 DB에 저장하고,
해당 리시버에서 수신받은 설치된 앱 패키지명( intent.getData().getSchemeSpecificPart() )이 해당 디비에 있는지 확인하여 광고 참여로 설치 여부를 확인합니다.

iOS는 별도로 앱 설치 시 발생하는 시그널이 없으므로 유저가 앱을 실행하는 타이밍에 설치여부를 체크하는 것을 추천합니다.

따라서 아래의 AppDelegate 함수에서 체크를 수행하는 방법이 있습니다.

- (void)applicationDidBecomeActive:(UIApplication *)application

설치여부 체크는 아래의 함수를 이용합니다.

3) Google account 가져오기 예제

FAQ

우선 request method 를 POST 로 설정하셨는지 확인 부탁드리며,
Content-type 을 application/x-www-form-urlencoded 로 설정해주시기 바랍니다.

Index

1. 광고 목록 조회

5) Response Fields

ads 세부 항목 (Response Fields - ads)

creative 세부 항목 (Response Fields - ads - creative)

2. 광고 참여 요청

4) HTTP Request parameters

5) Response

3. 광고 참여 완료

4) HTTP Request parameters

5) Response

4. 포인트 적립 포스트백 API 연동

부록

1) 처리 결과 코드

2) 앱 설치 트래킹

3) Google account 가져오기 예제

FAQ

가이드 변경 이력

`ads` 세부 항목 (Response Fields - ads)

`creative` 세부 항목 (Response Fields - ads - creative)