네이버SIS 연동 가이드

1. 플로우:시퀀스 다이어그램

유저가 매체 내의 네이버SIS 진입점을 클릭할 경우 매체사에선 필수 파라미터를 포함한 p 쿼리를 네이버SIS URL에 추가하여 네이버SIS 미션 페이지에 리다이렉팅합니다. 이 때 p 쿼리에 포함되어 있는 유저 정보를 기반으로 버즈빌 프론트에서 버즈빌 서버로 광고 할당 요청 및 응답하도록 구현되어 있습니다.

이후 유저가 미션에 참여 완료했다면, 공급사에서 버즈빌로 전환 포스트백을 요청합니다. 버즈빌에선 퍼블리셔(매체사)로 포스트백을 요청하여 유저에게 리워드를 지급합니다.

2. 네이버SIS 연동

네이버SIS 연동 절차는 아래와 같은 순서로 진행됩니다.

절차 요약

네이버SIS 연동 킥오프
매체사 커스텀(요구사항) 여부 확인 및 진입점 구현
본 가이드에 따라 네이버SIS URL 구현
1. 커스텀(요구사항)이 없을 경우 공용 URL으로 구현
2. 커스텀(요구사항)이 있을 경우 커스텀용 URL으로 구현
버즈빌 매니저에게 네이버SIS 진입점 위치 전달

2.1. URL 구현

2.1.1 URL(공용)

해당 URL은 네이버SIS에 진입하기 위한 공용 URL입니다.

커스텀(요구사항)이 없을 경우 아래 URL로 연동을 진행합니다.

https://pointhub.buzzvil.com/buzzad/multi-action/sis?p=[인코딩된_파라미터]

네이버SIS URL의 p 쿼리 파라미터 내에는 ifa 등의 유저 정보가 포함되기 때문에 URL이 유저마다 변경됩니다.하지만 매체사에서는 고정 URL로 진입점 내 URL을 기입해야 할 수 있습니다.

이 경우 ①번과 같이 진입점 내 URL을 적용해도 무관하나, 버즈빌로 URL을 리다이렉팅할 때는 ②번과 같이 p 쿼리 파라미터를 포함하여 전달해야 합니다.

① 진입점 내 URL 기입 :https://pointhub.buzzvil.com/buzzad/multi-action/sis

② 리다이렉팅 시 URL : https://pointhub.buzzvil.com/buzzad/multi-action/sis?p=[인코딩된_파라미터]

2.1.2 URL(커스텀)

매체사에서 커스텀(요구사항)이 있을 경우 아래와 같이 publisher_path와 custom 파라미터를 추가한 URL을 사용합니다. publisher_path는 연동 킥오프에서 사전 협의를 진행합니다.

https://pointhub.buzzvil.com/buzzad/multi-action/sis/publisher_path?p=[인코딩된_파라미터]&custom=[커스텀_파라미터]

publisher_path : 버즈빌과 사전 협의된 path를 입력합니다.

publisher_path를 buzzvil로 협의했을 경우 아래와 같이 URL을 구현합니다.

https://pointhub.buzzvil.com/buzzad/multi-action/sis/buzzvil?p=[인코딩된_파라미터]&custom=[커스텀_파라미터]

네이버SIS URL의 p 쿼리 파라미터 내에는 ifa 등의 유저 정보가 포함되기 때문에 URL이 유저마다 변경됩니다.하지만 매체사에서는 고정 URL로 진입점 내 URL을 기입해야 할 수 있습니다.

이 경우 ①번과 같이 진입점 내 URL을 적용해도 무관하나, 버즈빌로 URL을 리다이렉팅할 때는 ②번과 같이 p 쿼리 파라미터와 custom 파라미터를 포함하여 전달해야 합니다.

① 진입점 내 URL 기입 : https://pointhub.buzzvil.com/buzzad/multi-action/sis/publisher_path

② 리다이렉팅 시 URL : https://pointhub.buzzvil.com/buzzad/multi-action/sis/publisher_path?p=[인코딩된_파라미터]&custom=[커스텀_파라미터]

2.2 파라미터

파라미터	설명	필수 여부	예시

파라미터	설명	필수 여부	예시
p	JSON 객체를 URI 인코딩 후 Base64로 인코딩한 값으로, 사용자 및 매체 정보를 포함합니다.	REQUIRED	p=eyJhcHBfaWQiOjEyMzIzNDM0NSwibmFtZSI6IkpvaG4gRG9lIn0%3D
custom	추가 정보를 전달하기 위한 커스텀 파라미터입니다.	optional	custom=source_campaign_123

p 쿼리 파라미터는 다음 정보를 포함한 JSON 객체를 URI 인코딩 후 Base64로 인코딩하여 생성합니다. 아래에 나열된 모든 파라미터들은 이 JSON 객체의 필드로 포함되어야 합니다.

2.2.1 필수 파라미터

다음 파라미터들은 p 쿼리 파라미터를 구성하는 JSON 객체 내에 반드시 포함되어야 합니다.

구분	유형	내용	예시

구분	유형	내용	예시
app_id REQUIRED	Integer (MAX 20)	매체 앱 아이디 버즈빌에서 발급드린 고유 식별자입니다.	123234345
unit_id REQUIRED	Integer (MAX 20)	매체 지면 아이디 버즈빌에서 발급드린 고유 식별자입니다.	1234567
ifa REQUIRED	String (MAX 64)	사용자의 광고식별자 광고 타게팅 및 어뷰징 필터링, CS 처리를 위해 필요합니다. 광고식별자 수집이 불가능할 경우 uuid 포맷을 모두 0으로 채워 요청해야 합니다.	예제) ab4ade35-1c8a-4405-acda-10ca1ad1abe1
puid REQUIRED	String (MAX 65)	사용자 고유 식별자 서비스 도중 변하지 않는 고정 값입니다. 광고 할당을 위한 필수 정보입니다. (최대 65자까지만 전달이 가능합니다.)
client_ip REQUIRED	String (MAX 45)	광고에 참여한 유저의 ip 실제 유저의 ip 값을 전달해 주어야 합니다. 그러지 않을 경우 CPA 유형의 광고 송출이 불가합니다.	예제) 123.123.123.123

2.2.2 선택적(Optional) 파라미터

다음 파라미터들도 p 쿼리 파라미터를 구성하는 JSON 객체 내에 포함하는 것을 권장합니다.

구분	유형	내용	예시

구분	유형	내용	예시
currency_unit 선택	String	재화 단위 매체에서 사용하고 있는 리워드의 재화 단위가 “원”이 아닐 경우 매체의 재화 단위를 전달 받습니다. 해당 파라미터의 값이 없을 경우 재화 단위는 “원”으로 설정됩니다.	`포인트` `캐시`
won_to_currency_rate 선택	Integer	재화 환율 매체에서 적용하고 있는 환율을 전달 받습니다. 버즈빌에서 1원으로 리워드 적립을 요청하나, 매체에서 4원을 지급할 경우 환율은 `4` 해당 파라미터의 값이 없을 경우 환율은 `1`로 설정됩니다.	`4`: 1원당 4 currency_unit `2`: 1원당 2 currency_unit
birthday 권장	String (MAX 10)	유저의 생년월일 생년월일 정보가 없을 경우 일부 광고가 할당에서 제외됩니다.	예제) 1993-01-09 ( O ) 19930109 ( X )
gender 권장	String (MAX 20)	성별 타게팅을 위한 정보 성별 정보가 없을 경우 일부 광고가 할당에서 제외됩니다.	`M`: 남자 `F`: 여자
platform 권장	String	기기의 OS 정보	`A`: Android `I`: iOS
carrier 권장	String (MAX 20)	통신사 정보 통신사 정보가 없을 경우 일부 광고가 할당에서 제외됩니다.	`kt`: KT 통신사 `skt`: SKT 통신사 `lgt`: LGT 통신사
device_name 권장	String (MAX 255)	디바이스 모델명 디바이스 모델명이 없을 경우 일부 광고가 할당에서 제외됩니다.	예제) SHV-E250S,SHV-E275K,SM-G928L → SHV-E250S 또는 SHV-E275K 또는 SM-G928L 인 유저에게 타게팅
latitude 권장	Float (MAX 32)	위도 와 경도 지역별 광고 타게팅에 사용됩니다. 정보가 없을 경우 일부 광고가 할당에서 제외됩니다.
longitude 권장	Float (MAX 32)
user_agent 권장	String (MAX 255)	User Agent. 정보가 없을 경우 일부 광고가 할당에서 제외됩니다.

3. 적립 포스트백 연동

적립 포스트백 연동은 사용자에게 보상을 지급하기 위한 연동입니다. 만약, 이미 버즈빌 오퍼월 도입으로 적립 포스트백 연동이 완료되었다면 기존에 사용하는 포스트백 URL과 class을 사용하여 적립 연동을 대체할 수 있습니다.

만약, 버즈빌 오퍼월이 도입되지 않아 적립 포스트백 연동이 되어 있지 않을 경우 매체사 포인트 적립 포스트백 API 연동을 통해 적립 포스트백 연동을 진행해야 합니다.

구분	내용

구분	내용
버즈빌 오퍼월 O	적립 포스트백 연동 필요 여부 : 불필요 기존 사용하던 포스트백 URL & class 사용
버즈빌 오퍼월 X	적립 포스트백 연동 필요 여부 : 필요 매체사 포인트 적립 포스트백 API 연동 문서를 통해 연동 진행