BuzzBenefit Web 개발 연동 가이드
- theo.park
- Arthur Lee
- Luke Hwang
웹뷰 연동 개발
BuzzBenefit Web 연동 개발을 위해 필요한 JS 인터페이스, 디자인 선택사항(가이드) 등을 버즈빌 담당자에게 전달해 주시면 버즈빌에서 지면을 개발해서 웹 뷰 URL을 전달드리는 방식으로 연동이 진행됩니다.
도메인 연동
Staging(테스트환경)
https://pointhub-staging.buzzvil.com/buzzbenefit/[버즈빌 발급 앱아이디]?pquery
Prod
https://pointhub.buzzvil.com/buzzbenefit/[버즈빌 발급 앱아이디]?pquery
예시
https://pointhub-staging.buzzvil.com/buzzbenefit/[버즈빌 발급 앱아이디]?p=JTdCJTIycHVpZCUyMiUzQSUy[…]U5QyUyMCVFQSVCMCU5NSVFQiU4MiVBOCVFQSVCNSVBQyUyMiU3RA==
URL
url : {domain}?p=JTdCJTIyaWZhJTIyJTNBJTIyRVRFR0RHUkVHLTExQUFBLUJCQjIyMzQ1JTIyJTJDJTIyYWdlJTIyJTNBMzAlMkMlMjJzZXglMjIlM0ElMjJNJTIyJTJDJTIycGxhdGZvcm0lMjIlM0ElMjJBJTIyJTJDJTIyY2FycmllciUyMiUzQSUyMmt0JTIyJTJDJTIyZGV2aWNlX25hbWUlMjIlM0ElMjJTSFYtRTI1MFMlMjIlMkMlMjJyZWdpb24lMjIlM0ElMjIlRUMlODQlOUMlRUMlOUElQjglRUQlOEElQjklRUIlQjMlODQlRUMlOEIlOUMlMjAlRUElQjAlOTUlRUIlODIlQTglRUElQjUlQUMlMjIlN0Q=
p쿼리 값 생성하는법(예시는 자바스크립트)
포함되어야하는 정보
[ puid - 매체사 암호화 유저ID, ifa - 광고 ID, birthday: 생년월일 또는(year_of_birth - 출생년도), gender - 성별, platform - OS정보, carrier - 통신사, device_name - 단말기기, region - 지역 ]
birthday의 우선순위가 year_of_birth보다 높습니다.(만나이 계산을 위함)
JSON string 생성
'{“puid”: “매체사 암호화 유저ID”,"ifa":”a31752d2-5d7e-4f41-a45c-af4d39d2fb2d",”birthday”:“yyyy-mm-dd“,"year_of_birth":”1989”,"sex":"M | F","platform":"A | I","carrier":"kt | skt | lgt | null","device_name":"SHV-E250S","region":"서울특별시 강남구"}'
uri인코딩 encodeURIComponent → base64encdoe : btoa(encodeURIComponent( json스트링값 ))
p쿼리에 포함해야하는 정보가 누락되면 광고가 정상적으로 할당되지 않을 수 있습니다.
JSON String에는 공백이 포함되면 안됩니다.
예시
{ key: value }X{key:value}O{"key":"value 내부에는 공백이 허용되는 경우도 있습니다."}O
웹뷰 JS 인터페이스 버즈빌로 전달
광고 참여와 CS 처리를 위해 웹뷰를 동작시키는 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);
}
}
}
추가로, 어뷰징 방지를 위해 앱에서 연 브라우저인지 체크하는 기능 제공이 필요합니다.
만약 제공되지 않는다면, 앱에서 연 브라우저인지 구분할 수 없어 웹뷰 진입이 막힙니다.
앱에서 띄운 웹뷰가 맞는지 체크하는 js 인터페이스 제공 필요.
만약 해당 인터페이스 제공이 어렵다면, 웹브라우저 user-agent에서 매체사 웹뷰를 구분할 수 있도록 사용하는 방식이 있는지 확인 필요
예시
const isBuzzvilWebview = () => /BUZZVIL\//.test(window?.navigator.userAgent);
포인트 적립을 위한 적립 포스트백 API 연동
적립 포스트백 API 연동가이드
포인트 적립 포스트백 API 연동 문서를 참고해서 API를 연동해 주세요. (필독 : 가이드 링크)
ip 화이트리스팅 - 보안을 위한 인바운드 IP 화이트리스팅을 하고 계시다면, 아래 버즈빌 IP의 요청을 받아보실 수 있도록 예외 처리를 해주세요.
18.179.158.39
52.68.114.43
FAQ
웹뷰 JS 인터페이스 중 ‘웹뷰 열기’ 기능은 왜 필요한가요?
광고 상세 페이지 등 다른 페이지로 이동할때, 다른 도메인을 거쳐서 redirect되는 경우가 많습니다. 이럴 경우 페이지 이동후 백버튼이 정상동작하지 못하거나, 웹뷰사이드의 클라리언트 데이터들이 없어지기때문에 웹뷰 안에서 새로운 ‘웹뷰 열기’가 필요합니다.
웹뷰를 띄울 때 반드시 새탭으로 띄워야 한다고 나와있는데, 새창으로 띄우는 것과 차이가 있을까요?
pc로 보자면 크롬내에 새로운 탭 or 크롬으로 새창 띄우기와 같은 개념입니다. (단,둘다 인앱 웹뷰여야합니다.)
외부브라우저로 새 창을 띄우는 개념은 아닙니다.
* 만약 브라우저 히스토리가 없는 경우, 히스토리 백 하면 웹뷰가 닫히도록 구현되있어야하는 점 유의 부탁드립니다.
함수를 정의해서 사용 중인데 window 객체 등에 따로 정의를 해서 넘겨야하는지?
window 객체에 따로 정의해서 넘겨주시는 것을 가장 권장드립니다.