BuzzBenefit Web 표준 개발 연동 가이드

🌐 웹뷰 연동 개발 가이드

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

✅ 고정 페이지 이동

페이지	설명

페이지	설명
`/history`	적립 내역
`/mission-pack`	미션팩
`/lucky-box`	럭키박스

예시:

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` 파라미터 생성 방법

✅ 포함되어야 할 사용자 정보

항목	설명

항목	설명
`puid`	매체사 암호화 유저 ID (필수)
`ifa`	광고 ID (가능한 경우 반드시 포함, 없을 경우 파라미터 자체를 생략)
`birthday`	생년월일 (`yyyy-mm-dd`)
`year_of_birth`	출생년도 (`birthday`가 우선순위 더 높음)
`gender`	성별 (`M` 또는 `F`)
`platform`	OS 정보 (`A`=Android, `I`=iOS)
`carrier`	통신사 (`kt`, `skt`, `lgt`, `null`)
`device_name`	기기명 (`예: SHV-E250S`)
`region`	지역 정보 (`예: 서울특별시 강남구`)

ℹ️ birthday와 year_of_birth가 모두 있는 경우, birthday가 우선 사용됩니다 (만 나이 계산 목적).

🚫 주의사항

ifa 값이 없으면 파라미터 자체를 전송하지 말아야 합니다.
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 인코딩을 사전 적용해 주시기를 강력히 권장드립니다. 인코딩 누락 시, 데이터 정합성 문제나 인증 실패 등의 오류가 발생할 수 있습니다.

📲 웹뷰 JS 인터페이스 연동 가이드

버즈빌 오퍼월을 웹뷰로 연동하는 경우, 광고 참여 및 CS 처리를 위해 앱과의 JS 인터페이스 연동이 필수적입니다.
웹뷰 내에서 사용자가 발생시키는 동작을 앱으로 전달하고, 앱이 해당 동작을 처리하는 구조로 구성됩니다.

✅ 필수 제공 기능

아래 항목은 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.43

FAQ

웹뷰 JS 인터페이스 중 ‘웹뷰 열기’ 기능은 왜 필요한가요?

광고 상세 페이지 등 다른 페이지로 이동할때, 다른 도메인을 거쳐서 redirect되는 경우가 많습니다. 이럴 경우 페이지 이동후 백버튼이 정상동작하지 못하거나, 웹뷰사이드의 클라리언트 데이터들이 없어지기때문에 웹뷰 안에서 새로운 ‘웹뷰 열기’가 필요합니다.

웹뷰를 띄울 때 반드시 새탭으로 띄워야 한다고 나와있는데, 새창으로 띄우는 것과 차이가 있을까요?

pc로 보자면 크롬내에 새로운 탭 or 크롬으로 새창 띄우기와 같은 개념입니다. (단,둘다 인앱 웹뷰여야합니다.)
외부브라우저로 새 창을 띄우는 개념은 아닙니다.
* 만약 브라우저 히스토리가 없는 경우, 히스토리 백 하면 웹뷰가 닫히도록 구현되있어야하는 점 유의 부탁드립니다.

함수를 정의해서 사용 중인데 window 객체 등에 따로 정의를 해서 넘겨야하는지?

window 객체에 따로 정의해서 넘겨주시는 것을 가장 권장드립니다.