/
BuzzBenefit Web 개발 연동 가이드

BuzzBenefit Web 개발 연동 가이드

Owned by theo.park
Last updated: Dec 31, 2024 by Mason Yun
2 min read

웹뷰 연동 개발

BuzzBenefit Web 연동 개발을 위해 필요한 JS 인터페이스, 디자인 선택사항(가이드) 등을 버즈빌 담당자에게 전달해 주시면 버즈빌에서 지면을 개발해서 웹 뷰 URL을 전달드리는 방식으로 연동이 진행됩니다.

도메인 연동

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의 요청을 받아보실 수 있도록 예외 처리를 해주세요.

    • 13.231.21.93

    • 18.179.158.39

    • 52.68.114.43

FAQ

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

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

 

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

pc로 보자면 크롬내에 새로운 탭 or 크롬으로 새창 띄우기와 같은 개념입니다. (단,둘다 인앱 웹뷰여야합니다.)

외부브라우저로 새 창을 띄우는 개념은 아닙니다.

* 만약 브라우저 히스토리가 없는 경우, 히스토리 백 하면 웹뷰가 닫히도록 구현되있어야하는 점 유의 부탁드립니다.

 

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

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