BuzzBenefit Web 표준 개발 연동 가이드
- 1 🌐 웹뷰 연동 개발 가이드
- 2 🛠️ 개발 연동 프로세스
- 3 🌐 도메인 구성
- 4 🔗 예시 URL
- 5 🔗 URL 구성 가이드
- 6 📘 1. 오퍼월 진입 URL 형식
- 7 📌 2. p 파라미터 생성 방법
- 7.1 ✅ 포함되어야 할 사용자 정보
- 8 🚫 주의사항
- 9 🛠️ 3. 인코딩 절차
- 10 💡 JavaScript 예시 코드
- 11 🚨 경고
- 12 iOS 웹뷰 세팅 가이드
- 13 📲 웹뷰 JS 인터페이스 연동 가이드
- 14 Android 다크모드 관련 주의사항
- 15 ✅ 필수 제공 기능
- 16 💡 인터페이스 구조 예시
- 17 어뷰징 방지용: 앱 출처 확인 기능
- 17.1 옵션 1: JS 인터페이스 제공
- 17.2 옵션 2: User-Agent 기반 구분
- 17.2.1 예시
- 18 🔗 포스트백 연동 안내
- 18.1 버즈빌 서버 IP 목록
- 18.2 FAQ
🌐 웹뷰 연동 개발 가이드
BuzzBenefit 오퍼월을 WebView로 연동하기 위해 필요한 개발 가이드를 안내드립니다.
🛠️ 개발 연동 프로세스
웹 연동 개발은 아래 순서로 진행됩니다:
JS 인터페이스 요구사항 을 버즈빌 담당자에게 전달
버즈빌에서 전달받은 정보 기반으로 지면(WebView용 페이지)을 개발
개발 완료 후, WebView용 URL을 제공
ℹ️ 버즈빌은 연동 요청에 맞춘 페이지를 구축하여 URL 형식으로 제공하며, 해당 URL을 앱 내 WebView에 연결하면 됩니다.
🌐 도메인 구성
버즈빌은 Staging(테스트) 환경과 Production(운영) 환경을 별도로 제공합니다.
📍 Staging (테스트용)
https://pointhub-staging.buzzvil.com/buzzbenefit/[버즈빌 발급 앱아이디]?p=ENCODED_QUERY📍 Production (운영용)
https://pointhub.buzzvil.com/buzzbenefit/[버즈빌 발급 앱아이디]?p=ENCODED_QUERY
p파라미터는 사용자 정보를 포함한 JSON 문자열을 URI 인코딩 + Base64 인코딩하여 구성합니다. (관련 가이드는 하단 참조)
🔗 예시 URL
✅ 기본 오퍼월 진입 URL (Staging)
https://pointhub-staging.buzzvil.com/buzzbenefit/1234567890?p=JTdCJTIycHVpZCUyMiUzQSUyMiVF...✅ 특정 페이지로 이동 (pageIndex 활용)
https://pointhub-staging.buzzvil.com/buzzbenefit/1234567890/2?p=JTdCJTIycHVpZCUyMiUzQSUyMiVF...✅ 고정 페이지 이동
페이지 | 설명 |
|---|---|
| 적립 내역 |
| 미션팩 |
| 럭키박스 |
예시:
https://pointhub-staging.buzzvil.com/buzzbenefit/1234567890/mission-pack?p=JTdCJTIycHVpZCUyMiUzQSUyMiVF...🔗 URL 구성 가이드
본 가이드는 버즈빌 오퍼월 연동 시 URL에 포함되는 파라미터 p의 생성 방법을 안내합니다.p 파라미터는 사용자 정보를 JSON으로 구성한 뒤, URI 인코딩 및 Base64 인코딩하여 전달해야 합니다.
📘 1. 오퍼월 진입 URL 형식
{domain}?p={encoded_p_value}예시:
https://pointhub.buzzvil.com/buzzbenefit/123456781234567?p=JTdCJTIycHVpZCUyMiUzQSUyMjMxZTgwMjc0YTU0NjRlNDhhZjUyYTY1ZDg2NWQ3ODM2JTIyJTdE📌 2. p 파라미터 생성 방법
✅ 포함되어야 할 사용자 정보
항목 | 설명 |
|---|---|
| 필수 매체사 암호화 유저 ID |
| 필수 광고 ID (가능한 경우 반드시 포함) |
| 권장 생년월일 ( |
| 권장 출생년도 ( |
| 권장 성별 ( |
| OS 정보 ( |
| 통신사 ( |
| 기기명 ( |
| 지역 정보 ( |
1️⃣
birthday와year_of_birth가 모두 있는 경우,birthday가 우선 사용됩니다 (만 나이 계산 목적)2️⃣ 성별과 출생연도 정보는 권장으로 표기되어 있으나 등록하지 않으면 타겟팅 광고 송출이 불가능합니다.
버즈빌의 광고는 타겟팅 광고가 대부분이기에 해당 정보를 등록해야 정상적인 광고 할당이 가능합니다.
🚫 주의사항
ifa값이 없으면 00000000-0000-0000-0000-000000000000 형식으로 채워서 전달해야합니다.JSON 문자열 내에는 공백이 포함되지 않아야 합니다.
올바른 예시:{"key":"value"} ✅ {"key":"value 내부에는 공백 허용"} ✅ { key: value } ❌
🛠️ 3. 인코딩 절차
사용자 정보를 아래 순서로 인코딩하여 p 파라미터로 구성합니다.
사용자 정보를 JSON 문자열로 생성
encodeURIComponent()로 URI 인코딩btoa()로 Base64 인코딩
💡 JavaScript 예시 코드
const userInfo = '{"puid":"매체사 암호화 유저ID","ifa":"a31752d2-5d7e-4f41-a45c-af4d39d2fb2d","birthday":"1989-07-15","year_of_birth":"1989","sex":"M","platform":"A","carrier":"kt","device_name":"SHV-E250S","region":"서울특별시 강남구"}';
const pquery = btoa(encodeURIComponent(userInfo));🚨 경고
p 파라미터에 포함된 정보가 누락되거나 형식이 잘못되면, 광고가 정상적으로 할당되지 않을 수 있습니다.
구성 시 주의 깊게 적용해주시기 바랍니다.
🔐 파라미터 값에 대한 URL-safe 인코딩 안내
API 연동 시, application/x-www-form-urlencoded 방식으로 전달되는 모든 파라미터 값(user_id 등)에 대해 다음과 같은 특수문자(+, =, 공백 등`)가 포함될 가능성이 있는 경우, URL-safe 인코딩(Percent Encoding) 을 적용해 주시기 바랍니다.
이는 암호화된 값, 사용자 식별자, 토큰 등 특수 문자가 포함된 데이터를 그대로 전송할 경우 파라미터 파싱 오류, 데이터 변형, 인증 실패 등의 문제가 발생할 수 있기 때문입니다.
예시:
원본 값:
abcd+ef123== token인코딩 후:
abcd%2Bef123%3D%3D%20token
⚠️ 특히
+문자는 공백으로 오해될 수 있으므로, 반드시 인코딩 처리해야 합니다.
요청 파라미터 전송 전, 특수문자(+, =, 공백 등`)가 포함될 가능성이 있는 모든 값에 대해 URL-safe 인코딩을 사전 적용해 주시기를 강력히 권장드립니다. 인코딩 누락 시, 데이터 정합성 문제나 인증 실패 등의 오류가 발생할 수 있습니다.
iOS 웹뷰 세팅 가이드
버즈빌에서 제공되는 미디에이션 광고를 정상적으로 표시하기 위해 iOS의 경우 앱 내에서 사용중이신 웹뷰에 세팅 추가가 필요합니다.
iOS 웹뷰가 웹페이지 내 플레이(Inline Media Playback)를 허용하도록 설정을 부탁드립니다.
WKWebViewConfiguration.allowsInlineMediaPlayback = true📲 웹뷰 JS 인터페이스 연동 가이드
버즈빌 오퍼월을 웹뷰로 연동하는 경우, 광고 참여 및 CS 처리를 위해 앱과의 JS 인터페이스 연동이 필수적입니다.
웹뷰 내에서 사용자가 발생시키는 동작을 앱으로 전달하고, 앱이 해당 동작을 처리하는 구조로 구성됩니다.
Android 다크모드 관련 주의사항
기본적으로 force 다크가 false이지만 true로 하는경우 웹뷰상에서 다크모드 색상을 지정해도 강제로 변환됩니다.
따라서 아래와 같이 force다크를 꺼주세요.
Android 앱 코드if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { // API 33+ webView.settings.algorithmicDarkeningAllowed = false} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) { // API 29-32 WebSettingsCompat.setForceDark( webView.settings, WebSettingsCompat.FORCE_DARK_OFF )}
✅ 필수 제공 기능
아래 항목은 JS 인터페이스를 통해 앱에서 반드시 처리되어야 하는 동작입니다:
기능 | 설명 |
|---|---|
| 새탭(새로운 웹뷰) 열기 |
| 새탭(새로 열린 웹뷰) 닫기 |
| 외부 브라우저로 링크 열기 |
| 네이티브 공유 기능 실행 (선택) |
💡 인터페이스 구조 예시
웹에서 window.buzzvil.postMessage()로 메시지를 전송하면, 앱에서 해당 메시지를 수신하고 처리하는 구조입니다.
import { NativeInterop } from "buzzbenefit-kit/native-interface";
export default class YourApp implements NativeInterop {
openNewTab(data: string): void {
this.#postMessage(JSON.stringify({ name: "openNewTab", data }));
}
closeTab(): void {
this.#postMessage(JSON.stringify({ name: "closeTab" }));
}
openExternalBrowser(data: string): void {
this.#postMessage(JSON.stringify({ name: "openExternalBrowser", data }));
}
share(data: string): void {
this.#postMessage(JSON.stringify({ name: "share", data }));
}
#postMessage(message: string): void {
try {
(window as any).buzzvil.postMessage(message);
} catch (e) {
console.error(e);
}
}
}
ℹ️ 자체적으로 사용 중인 인터페이스 방식이 있다면, 버즈빌 매니저에게 전달 부탁드립니다.
어뷰징 방지용: 앱 출처 확인 기능
포인트 적립 보안을 위해, 해당 웹뷰가 앱에서 연 것인지를 식별할 수 있는 기능이 필요합니다.
해당 기능이 제공되지 않으면, 웹 진입이 차단될 수 있습니다.
옵션 1: JS 인터페이스 제공
앱에서 띄운 웹뷰임을 JS로 확인할 수 있는 인터페이스가 있다면, 반드시 제공해 주세요.
옵션 2: User-Agent 기반 구분
위 인터페이스 제공이 어렵다면, 특정 문자열이 포함된 User-Agent를 통해 구분할 수 있어야 합니다.
예시
const isBuzzvilWebview = () => /BUZZVIL\//.test(window?.navigator.userAgent);🔗 포스트백 연동 안내
버즈빌은 광고 참여에 따른 포인트 적립을 위해 포스트백 API 연동이 필요합니다.
포인트 적립 API 연동 가이드는 [별도 문서 링크] 를 참고해 주세요.
보안을 위한 인바운드 IP 화이트리스팅을 하고 계시다면 아래 IP들에 대한 화이트리스트 등록이 필요합니다.
버즈빌 서버 IP 목록
13.231.21.93
18.179.158.39
52.68.114.43FAQ
웹뷰 JS 인터페이스 중 ‘웹뷰 열기’ 기능은 왜 필요한가요?
광고 상세 페이지 등 다른 페이지로 이동할때, 다른 도메인을 거쳐서 redirect되는 경우가 많습니다. 이럴 경우 페이지 이동후 백버튼이 정상동작하지 못하거나, 웹뷰사이드의 클라리언트 데이터들이 없어지기때문에 웹뷰 안에서 새로운 ‘웹뷰 열기’가 필요합니다.
웹뷰를 띄울 때 반드시 새탭으로 띄워야 한다고 나와있는데, 새창으로 띄우는 것과 차이가 있을까요?
pc로 보자면 크롬내에 새로운 탭 or 크롬으로 새창 띄우기와 같은 개념입니다. (단,둘다 인앱 웹뷰여야합니다.)
외부브라우저로 새 창을 띄우는 개념은 아닙니다.
* 만약 브라우저 히스토리가 없는 경우, 히스토리 백 하면 웹뷰가 닫히도록 구현되있어야하는 점 유의 부탁드립니다.
함수를 정의해서 사용 중인데 window 객체 등에 따로 정의를 해서 넘겨야하는지?
window 객체에 따로 정의해서 넘겨주시는 것을 가장 권장드립니다.