웹뷰 연동

콘텐츠사(Web -> WebView)

콘텐츠 웹에서 매체사 네이티브 앱(웹뷰 호스트)을 호출하기 위한 자바스크립트 인터페이스 명세입니다.

초기설정

데이터는 단일 데이터의 경우 해당 값을 String으로 전달. 다중 데이터는 JSON 형태의 String으로 전달한다.

javascript

// 네이티브 요청 함수
function callNative(method, message) {
  // Android — @JavascriptInterface 직접 호출
  if (window.addedBridge?.[method]) {
    addedBridge[method](message || '');
    return;
  }

  // iOS
  if (window.webkit?.messageHandlers?.addedBridge) {
    window.webkit.messageHandlers.addedBridge.postMessage({
      method: method,
      message: message || ''
    });
    return;
  }

  // Flutter
  if (window.addedBridge?.postMessage) {
    addedBridge.postMessage(JSON.stringify({
      method: method,
      message: message || ''
    }));
    return;
  }
}

callNative('interfaceName','value');

// 요청 데이터 받기
window.addedBridgeCallback = {};

addedBridgeCallback.interfaceName = function (data) {
	console.log( 'addedBridgeCallback :: ' + data);
};

필수

`openExternalBrowser()`

콘텐츠사에서 요청 받은 URL을 외부 브라우저로 연결합니다.
@param {string} url

javascript

callNative('openExternalBrowser','Https://...');

`finish()`

현재 웹뷰를 종료합니다.

javascript

callNative('finish');

`registerBackKey()`

시스템 뒤로가기(제스처/버튼)가 호출되면 네이티브에서 addedBridgeCallback.onBackKeyListener() 를 호출합니다.
@param {string} true|false

javascript

addedBridgeCallback.onBackKeyListener = function () {
	console.log( 'addedBridgeCallback :: onBackButtonListener()');
	if (history.length > 1) {
		history.back();
	} else {
		callNative('finish'); //필수연동 finish()
	}
};

`registerBackButton()`

앱바 영역에 백버튼이 존재하는 경우에만 필요합니다.
앱바의 백버튼이 터치되면 네이티브에서 addedBridgeCallback.onBackButtonListener() 를 호출합니다.
@param {string} true|false

javascript

addedBridgeCallback.onBackButtonListener = function () {
	console.log( 'addedBridgeCallback :: onBackButtonListener()');

	if (history.length > 1) {
		history.back();
	} else {
		callNative('finish'); //필수연동 finish()
	}
};

선택

`getAppVersion()`

네이티브 앱의 현재 버전 정보를 조회합니다.
응답은 addedBridgeCallback.getAppVersion(version) 으로 전달됩니다.

javascript

//호출
callNative('getAppVersion');

//콜백
addedBridgeCallback.getAppVersion = function (data) {
	console.log( 'addedBridgeCallback :: getAppVersion() -> ' + data);
};

`getADID()`

디바이스 광고 식별값(ADID)을 조회합니다.
응답은 addedBridgeCallback.getADID(adId) 으로 전달됩니다.

javascript

//호출
callNative('getADID');

//콜백
addedBridgeCallback.getADID = function (data) {
	console.log( 'addedBridgeCallback :: getADID() -> ' + data);
	// ex) XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
};

`getIsAgeUnder14()`

유저의 나이가 14세 미만인지 여부를 조회합니다.
구글/네이버 등 광고 정책으로 14세 미만에게는 타겟 광고 노출이 불가능합니다.
응답은 addedBridgeCallback.getIsAgeUnder14(isUnder14)으로 전달됩니다. ("true" | "false")

javascript

//호출
callNative('getIsAgeUnder14');

//콜백
addedBridgeCallback.getIsAgeUnder14 = function (data) {
	console.log( 'addedBridgeCallback :: getIsAgeUnder14() -> ' + data);
	// "true" (14세 미만) | "false"
};

`getDeviceInfo()`

기기 정보(network / model / manufacturer / osVersion)를 조회합니다.
응답은 addedBridgeCallback.getDeviceInfo(deviceInfoJson) 으로 전달됩니다.
ex) {"network":"wifi","model":"SM-S911N","manufacturer":"Samsung","osVersion":"14"}

javascript

//호출
callNative('getDeviceInfo');

//콜백
addedBridgeCallback.getDeviceInfo = function (data) {
	const info = JSON.parse(data);
	console.log(info.network, info.model, info.manufacturer, info.osVersion);
};

`pushUrl()`

현재 웹뷰를 재사용하여 URL을 변경합니다.
@param {string} JSON string { url, replace? }

javascript

callNative('pushUrl', JSON.stringify({
	url: 'https://...',
	replace: false
}));

`openInternalBrowser()`

새로운 앱 화면(Activity / UIViewController)에 웹뷰를 띄우는 인터페이스.
@param {string} url

javascript

callNative('openInternalBrowser', 'https://...');

`setTitle()`

앱바 영역을 앱에서 관리하고, 해당 영역에 타이틀이 존재하는 경우 사용합니다.
앱바 영역 타이틀을 수정합니다.
@param {string} title

javascript

callNative('setTitle', '제목');

보상형 광고

AdMob 보상형(rewarded) 광고를 호출하는 인터페이스입니다. 전체 화면과 닫기 UI 를 AdMob SDK 가 소유하므로, 웹은 네이티브 오버레이와 달리 자리(rect)를 넘길 필요가 없습니다. 광고가 닫히면 onAdClosed, 보상 조건을 충족하면 onAdRewarded 로 통지받습니다. 비동기 응답은 requestId 로 상관(correlate)합니다.

대부분 라이브러리가 자동 처리

콘텐츠는 보통 @blomics/added-mediation 라이브러리를 통해 광고를 호출하며, 아래 브릿지 메서드 호출과 콜백 등록은 라이브러리가 내부에서 수행합니다. 이 명세는 그 원시 인터페이스를 참고용으로 정리한 것입니다.

`adInit()`

부팅 시 1회. 호스트가 받은 네트워크 SDK(AdMob 등)를 초기화합니다.
@param {string} JSON string { test, networks }

javascript

// 부팅 시 1회 — 호스트 광고 SDK 초기화
callNative('adInit', JSON.stringify({
  test: false,
  networks: [
    { key: 'admob', surface: 'bridge', app: { appId: 'ca-app-pub-XXXX~YYYY' } }
  ]
}));

`adLoad()`

광고 1개를 로드합니다. format 으로 종류를 지정하며('rewarded'), 화면에 표시하지 않고 로드만 합니다.
결과는 addedBridgeCallback.onAdLoaded / onAdFailed 로 전달됩니다.
@param {string} JSON string { requestId, network, format, ids }

javascript

// 광고 1개 로드 (아직 화면에 표시하지 않음) — format 으로 종류 지정
// 'rewarded' 보상형 광고
callNative('adLoad', JSON.stringify({
  requestId: 'ad_1',
  network: 'admob',
  format: 'rewarded',
  ids: { adUnitId: 'ca-app-pub-XXXX/ZZZZ' }
}));

// 로드 결과 (호스트 → 웹)
addedBridgeCallback.onAdLoaded = function (data) {
  const { requestId } = typeof data === 'string' ? JSON.parse(data) : data;
  // fill 성공 → 이어서 adShowRewarded 호출
};
addedBridgeCallback.onAdFailed = function (data) {
  const { requestId, stage, code } = typeof data === 'string' ? JSON.parse(data) : data;
  // stage:'load' 실패(NO_FILL 등) → 다음 후보로
};

`adShowRewarded()`

로드된 보상형 광고를 표시합니다. 보상 조건을 충족하면 onAdRewarded, 광고가 닫히면 onAdClosed 로 전달됩니다.
onAdRewarded 는 클라이언트 신호이므로 실제 보상 지급은 서버(S2S) 검증 후 처리해야 합니다.
@param {string} JSON string { requestId }

javascript

// 로드된 보상형 광고를 표시
callNative('adShowRewarded', JSON.stringify({ requestId: 'ad_1' }));

addedBridgeCallback.onAdRewarded = function (data) {
  const { requestId, type, amount } = typeof data === 'string' ? JSON.parse(data) : data;
  // 보상 조건 충족(예: 영상 끝까지 시청)
  // ⚠️ 이는 클라이언트 신호일 뿐입니다 — 실제 보상 지급은 서버(S2S) 검증 후 처리하세요.
};
addedBridgeCallback.onAdClosed = function (data) {
  const { requestId } = typeof data === 'string' ? JSON.parse(data) : data;
  // 광고 종료 (보상 획득 여부와 무관하게 호출)
};

닫힘 · 보상 콜백 요약

보상형 광고는 전체 화면과 닫기 UI 를 AdMob SDK 가 소유합니다. 광고가 닫히면 onAdClosed, 보상 조건을 충족하면 onAdRewarded 가 전달됩니다. (자리만 빌려 쓰는 네이티브 오버레이와 달리 닫힘·보상 콜백이 존재합니다.)

초기설정

필수

openExternalBrowser()

finish()

registerBackKey()

registerBackButton()

선택

getAppVersion()

getADID()

getIsAgeUnder14()

getDeviceInfo()

pushUrl()

openInternalBrowser()

setTitle()

보상형 광고

adInit()

adLoad()

adShowRewarded()

관련 문서

`openExternalBrowser()`

`finish()`

`registerBackKey()`

`registerBackButton()`

`getAppVersion()`

`getADID()`

`getIsAgeUnder14()`

`getDeviceInfo()`

`pushUrl()`

`openInternalBrowser()`

`setTitle()`

`adInit()`

`adLoad()`

`adShowRewarded()`