Buvlor Ads SDK — Publisher integration guide.

Integrate rewarded video across multiple ad partners through one mediation SDK.

1. Overview

The Buvlor SDK embeds into a publisher page and displays rewarded video ads through a single BuvlorAds global. Mediation across multiple ad partners is configured server-side per siteId — the publisher integration is unchanged regardless of how many partners are wired up behind the slot.

This guide walks through prerequisites, the three-line integration, identity attachment, the full API surface, and error handling.

2. Prerequisites

Email ads@buvlor.com with your domain to receive a siteId.
Add the DNS TXT record Buvlor issues on _buvlor.<your-domain> for verification.

Ad partner SDKs are loaded automatically by the Buvlor SDK — no extra integration required on your side.

3. Quick Start

Integration is two steps: install (once per page) and invoke (on user action).

3.1 Install — page `<head>` (once per page)

html

<!-- Load SDK -->
<script src="https://buvlor.com/sdk/v1/ads.js" async></script>

<!-- Initialize -->
<script>
  BuvlorAds.init({ siteId: 'your-site-id' });
</script>

Loads the SDK from the Buvlor CDN, asynchronously.
Initializes the SDK with your siteId. Mediation config is fetched server-side. Call init() once per page.

3.2 Invoke — on user action (anywhere in your product)

BuvlorAds.showRewardedAd() is the trigger that displays the ad. Call it from whatever UI your product needs — a button, a card tap, an end-of-level modal, a programmatic event.

html

<button onclick="BuvlorAds.showRewardedAd({
  slotId: 'your-slot-id',
  onAdLoaded: () => { /* ad loaded and ready — hide your loading spinner, lock user input */ },
  onReward: () => grantUserReward()
})">Watch ad to earn reward</button>

Or from JS:

playAdBtn.addEventListener('click', () => {
  BuvlorAds.showRewardedAd({
    slotId: 'your-slot-id',
    onAdLoaded: () => { /* ad loaded and ready — UI hook */ },
    onReward: () => grantUserReward()
  });
});

Need more than one slot? Call showRewardedAd with a different slotId per placement. The result of each call is delivered through exactly one of three terminal callbacks — onReward, onClose, or onError — described in §5. An optional fourth callback, onAdLoaded, fires when the ad is loaded and ready to display — useful for UI hooks like hiding a loading spinner.

4. Identity

Optional. Without it, the SDK still works — ads are served, callbacks fire as documented. Passing an identity is recommended for better matching but not required for integration.

When you do provide it, pass the device advertising ID (Android AAID / iOS IDFA) into the identity field. The SDK normalizes and SHA-256 hashes the value internally before transmission — plaintext is never stored or transmitted.

BuvlorAds.init({
  siteId: 'your-site-id',
  identity: '<advertising id from the device>'
});

Advertising IDs are not classified as personal data under Apple's and Google's developer policies, so this avoids the privacy considerations that apply to email addresses or account identifiers.

How to obtain the advertising ID, by environment:

Android in-app webview — Call AdvertisingIdClient.getAdvertisingIdInfo() in your native host and hand the value to the webview through your bridge.
iOS in-app webview (WKWebView) — Read ASIdentifierManager.advertisingIdentifier after the user grants ATT consent. If ATT is denied, fall back to a first-party UUID stored inside your app.
Pure web (non in-app) — The advertising ID is not available. Use a first-party UUID persisted in your own storage.

If the identifier is not ready at init() time, call BuvlorAds.setIdentity(value) once it becomes available — calls made before init() are queued and flushed automatically. Use BuvlorAds.clearIdentity() to detach the value on logout.

5. API Reference

`BuvlorAds.init(options)`

Option	Type	Required	Description
`siteId`	string	Yes	Identifier issued by Buvlor.
`identity`	string	No	Per-user unique identifier (auto-hashed).
`primaryDomain`	string	No	Canonical domain for this deployment.
`configUrl`	string	No	Override the default config URL.

`BuvlorAds.setIdentity(value)` / `BuvlorAds.clearIdentity()`

Attach or remove a per-user identifier. Returns Promise<void>. Safe to call before init() — values are queued and flushed automatically.

`BuvlorAds.showRewardedAd(options)`

showRewardedAd() is the function that displays the rewarded video. Call it from any UI element or programmatic trigger your product needs.

Option	Type	Description
`slotId`	string	Slot name defined in your mediation config.
`onAdLoaded`	`() => void`	Optional. Fires when the ad is loaded and ready to display. Use for UI hooks (hide loading spinner, lock user input).
`onReward`	`() => void`	User completed the ad — pay out here.
`onClose`	`() => void`	User dismissed before completion. Do not pay out.
`onError`	`(err) => void`	No demand source filled. `err.code` is a token in §6.
`openUrl`	`(url) => void`	Optional. Opens the ad's landing URL on click. Defaults to `window.open(url, '_blank')`.

openUrl — opening the ad landing

Some ad formats have buvlor open the landing URL on click (SDK-rendered ads handle their own clicks, so this isn't needed there). When it applies, openUrl is invoked; if you don't pass one, it defaults to window.open(url, '_blank'). In environments where window.open doesn't reach an external browser (e.g. native webviews), inject your own function that opens the external browser via your app's bridge.

BuvlorAds.showRewardedAd({
  slotId: 'your-slot-id',
  onReward: () => grantUserReward(),
  openUrl: (url) => nativeBridge.openExternalBrowser(url), // example
});

Typical cases where openUrl fires: click-through banners and interstitials, and native ads that buvlor renders as a card (landing + privacy-policy links).

Callback behavior

Every call to showRewardedAd() resolves through exactly one of the three terminal callbacks — onReward, onClose, or onError — fired once. There are no duplicate, partial, or contradictory callbacks. The SDK guarantees this internally, so you can put your reward-granting code directly inside onReward without worrying about double payouts.

onAdLoaded is an optional lifecycle signal that fires before the terminal callback whenever an ad fetch succeeds and the ad is ready to display. It is independent of the three terminal callbacks.

onAdLoaded() — The ad is loaded and ready to display. Fires at most once per call, and always before onReward / onClose. Does not fire on onError (the ad was never fetched). Use this hook to hide your "loading..." UI and lock user input.
onReward() — The user watched the ad to completion. Grant the reward here.
onClose() — The ad was shown, but the user closed it before completion. Do not grant the reward.
onError(err) — No ad could be displayed at all. Inspect err.code (§6) to decide your fallback: retry later, hide the entry point, fall back to a non-ad reward path, etc.

Ordering guarantees

onAdLoaded always fires before onReward or onClose when an ad fills.
onAdLoaded never fires together with onError.
Exact timing of onAdLoaded varies slightly by mediation tier — it fires when the ad fetch completes and the ad is ready, before the display starts. The ordering relative to all terminal callbacks is always preserved.

UI is yours. showRewardedAd() only handles the ad display and the result callbacks. The button shown in §3 is illustrative — the SDK does not care whether the trigger is a button, a tappable card, an automatic call after a game round, a daily-check-in flow, or a low-balance modal. Design the entry point however fits your product.

`BuvlorAds.preloadRewardedAd({ slotId })`

Optional. Warms the first mediation tier so a subsequent showRewardedAd call renders with minimal latency.

6. Error Codes

onError receives { code, message }. code is one of:

Code	Meaning	Recommended response
`all_unavailable`	Mediation ran through all tiers but none could fill the slot.	Show "Try again in a moment" to the user.
`invalid_slot`	Slot configuration is malformed or missing.	Contact Buvlor — config-side issue.
`init_failed`	The SDK could not load or parse the site config.	Check network connectivity and retry.

7. FAQ

Q. Ads aren't loading. How do I debug? Check three things in order: (1) the ad partner site-script Buvlor provided is loaded in your page <head> and reaches readyState: complete; (2) the browser console for errors emitted by BuvlorAds (init failures and slot errors log with a [BuvlorAds] prefix); (3) the onError callback code against §6. If all three look clean, send the siteId, slot name, and console log to ads@buvlor.com.

Q. When should I call setIdentity()? Pass the advertising ID directly into init({siteId, identity}) if it is available at page load — that is the recommended path. Only call setIdentity(value) separately when the identifier arrives later (for example, an asynchronous native-bridge call, or a first-party UUID generated on first visit). Calls made before init() are automatically queued and flushed once init completes.

Q. How do I add a new domain to my site? Email ads@buvlor.com with the new domain. Buvlor registers it server-side and issues a fresh DNS TXT record for _buvlor.<new-domain>. Once the record propagates, the same siteId works on the new domain — no code change required.

Q. Can Buvlor Ads run alongside other ad SDKs? Yes. Buvlor Ads is rewarded-only and isolated to its own globals. Display, native, and other rewarded SDKs on the same page are not affected.

Q. Do I have to use a button to call showRewardedAd? No. The <button> in §3 is just an example. Call showRewardedAd() from any UI element, lifecycle hook, or programmatic trigger your product uses — an end-of-level reward popup, a daily check-in tap, a low-coin modal, a tappable card on a home screen, or a fully scripted flow. The SDK is responsible for displaying the ad; your code decides when and where to invoke it.

Q. When does onAdLoaded fire? Can I use it to hide a loading spinner? Yes — that is the intended use case. onAdLoaded fires once when the ad fetch completes and the ad is ready to display, before onReward or onClose. It does not fire on onError. Show your loading spinner immediately after calling showRewardedAd(), and hide it inside onAdLoaded. The ordering guarantee (onAdLoaded → terminal callback) always holds, so your spinner-hide will never run after your reward grant.

8. Contact

Integration & support: ads@buvlor.com
siteId requests: include your site domain, contact name, and the rewarded slot names you plan to implement. Staging config and debug tokens are provisioned on request.

1. 개요

Buvlor SDK는 매체 페이지에 임베드되어 BuvlorAds 글로벌을 통해 리워드 비디오 광고를 표시합니다. 여러 광고 파트너에 걸친 미디에이션 설정은 siteId 단위로 서버에서 관리되므로, 매체 측 통합 코드는 파트너 수와 무관하게 동일합니다.

본 문서는 사전 준비, 3줄 통합, 사용자 식별 부착, 전체 API, 에러 처리 순서로 구성되어 있습니다.

2. 사전 준비

ads@buvlor.com으로 도메인을 보내 siteId를 발급받습니다.
Buvlor가 발급한 DNS TXT 레코드를 _buvlor.<도메인>에 등록해 도메인을 검증합니다.

광고 파트너 SDK는 Buvlor SDK가 자동으로 로드하므로 매체 측 추가 통합은 필요 없습니다.

3. 통합 (Quick Start)

통합은 두 단계입니다 — 설치(페이지당 1회) + 호출(사용자 액션 시점).

3.1 설치 — 페이지 `<head>` (1회)

html

<!-- SDK 로드 -->
<script src="https://buvlor.com/sdk/v1/ads.js" async></script>

<!-- 초기화 -->
<script>
  BuvlorAds.init({ siteId: 'your-site-id' });
</script>

Buvlor CDN에서 SDK를 비동기로 로드합니다.
siteId로 SDK를 초기화합니다. 미디에이션 설정은 서버에서 자동 적용. init()은 페이지당 1회만 호출.

3.2 호출 — 사용자 액션 시점 (어디서든)

BuvlorAds.showRewardedAd()는 광고를 실제로 표시하는 트리거 함수입니다. 매체가 원하는 UI(버튼, 카드 탭, 라운드 종료 모달, 코드 내 자동 호출 등) 어디서든 호출할 수 있습니다.

html

<button onclick="BuvlorAds.showRewardedAd({
  slotId: 'your-slot-id',
  onAdLoaded: () => { /* 광고 로드 완료 — 로딩 스피너 숨김, 사용자 입력 잠금 등 UI 처리 */ },
  onReward: () => grantUserReward()
})">광고 보고 리워드 받기</button>

또는 JS에서:

playAdBtn.addEventListener('click', () => {
  BuvlorAds.showRewardedAd({
    slotId: 'your-slot-id',
    onAdLoaded: () => { /* 광고 로드 완료 — UI 처리 */ },
    onReward: () => grantUserReward()
  });
});

여러 슬롯이 필요하면 위치마다 slotId를 다르게 지정해 showRewardedAd를 호출하세요. 각 호출 결과는 onReward / onClose / onError 세 종결 콜백 중 정확히 하나로 전달됩니다 — 자세한 동작은 §5에서 설명합니다. 광고 로드가 완료되어 표시 준비가 됐을 때 발화하는 선택적 콜백 onAdLoaded도 함께 제공되며, 로딩 스피너 숨김 같은 UI 처리에 유용합니다.

4. Identity (디바이스 광고ID)

선택 사항입니다. identity를 전달하지 않아도 SDK는 정상 동작합니다 — 광고는 송출되고 콜백도 문서대로 발화합니다. 매칭률 향상을 위해 identity 전달을 권장하지만, 통합 자체에 필수는 아닙니다.

전달하는 경우 identity 필드에 디바이스 광고ID(Android AAID / iOS IDFA)를 넣으세요. SDK가 내부에서 normalize 후 SHA-256 해시 처리하여 전송하며, 평문은 저장되거나 전송되지 않습니다.

BuvlorAds.init({
  siteId: 'your-site-id',
  identity: '<디바이스 광고ID>'
});

광고ID는 Apple과 Google의 개발자 정책상 개인정보로 분류되지 않으므로, 이메일이나 계정 ID 대비 개인정보 처리 부담 없이 사용할 수 있습니다.

환경별 회수 방법:

Android in-app webview — 네이티브 호스트에서 AdvertisingIdClient.getAdvertisingIdInfo()로 회수한 뒤 브리지로 웹뷰에 전달.
iOS in-app webview (WKWebView) — ATT 동의 후 ASIdentifierManager.advertisingIdentifier 읽기. ATT 거부 시 앱에 저장한 1st-party UUID로 fallback.
순수 웹 (in-app 아님) — 광고ID 회수 불가. 자체 스토리지에 보관한 1st-party UUID 사용.

init() 시점에 광고ID가 아직 준비되지 않았다면, 확보된 뒤 BuvlorAds.setIdentity(value)로 늦게 전달해도 됩니다 — init() 이전 호출은 자동으로 큐잉되어 초기화 시점에 반영됩니다. 로그아웃 시에는 BuvlorAds.clearIdentity()로 해제하세요.

5. API 레퍼런스

`BuvlorAds.init(options)`

옵션	타입	필수	설명
`siteId`	string	Yes	Buvlor가 발급한 식별자.
`identity`	string	No	사용자별 유니크 식별자(자동 해시).
`primaryDomain`	string	No	이 배포의 정식 도메인.
`configUrl`	string	No	기본 설정 URL을 오버라이드.

`BuvlorAds.setIdentity(value)` / `BuvlorAds.clearIdentity()`

사용자 식별자를 부여하거나 제거합니다. Promise<void> 반환. init() 이전 호출은 자동으로 큐잉되어 초기화 시점에 반영됩니다.

`BuvlorAds.showRewardedAd(options)`

showRewardedAd()는 리워드 비디오를 실제로 표시하는 함수입니다. 매체가 원하는 어떤 UI 요소나 코드 시점에서도 호출할 수 있습니다.

옵션	타입	설명
`slotId`	string	미디에이션 설정에 정의된 슬롯명.
`onAdLoaded`	`() => void`	선택. 광고 로드가 완료되어 표시 준비된 시점에 발화. UI 후처리(로딩 스피너 숨김, 사용자 입력 잠금)에 사용.
`onReward`	`() => void`	광고 완주. 리워드를 지급해야 하는 시점.
`onClose`	`() => void`	사용자가 완주 전에 닫음. 리워드 지급 X.
`onError`	`(err) => void`	어떤 광고 파트너도 채우지 못함. `err.code`는 §6의 토큰 중 하나.
`openUrl`	`(url) => void`	선택. 광고 클릭 시 랜딩 URL을 여는 함수. 미지정 시 `window.open(url, '_blank')`.

openUrl — 광고 랜딩 열기

일부 광고 유형은 클릭 시 랜딩 URL을 buvlor가 직접 엽니다(SDK 자체 렌더 광고는 파트너가 처리하므로 불필요). 이때 openUrl이 호출되며, 미지정 시 기본값은 window.open(url, '_blank')입니다. 네이티브 웹뷰 등 window.open으로 외부 브라우저가 열리지 않는 환경에서는 매체의 브릿지로 외부 브라우저를 여는 함수를 직접 주입하세요.

BuvlorAds.showRewardedAd({
  slotId: 'your-slot-id',
  onReward: () => grantUserReward(),
  openUrl: (url) => nativeBridge.openExternalBrowser(url), // 예시
});

openUrl이 호출되는 대표 케이스: 클릭형 배너·전면 광고, 그리고 buvlor가 카드를 직접 렌더하는 네이티브 광고(랜딩·개인정보처리방침 링크).

콜백 동작

showRewardedAd() 호출 한 번당 세 종결 콜백(onReward / onClose / onError) 중 정확히 하나만 1회 실행됩니다. 중복 호출·부분 호출·상반 콜백은 발생하지 않으며, 이는 SDK 내부에서 보장됩니다. 따라서 onReward에 리워드 지급 코드를 그대로 넣어도 이중 지급 걱정은 없습니다.

onAdLoaded는 선택적인 라이프사이클 콜백으로, 광고 fetch가 완료되어 표시 준비가 됐을 때 종결 콜백 이전에 발화합니다. 세 종결 콜백과는 별개로 동작합니다.

onAdLoaded() — 광고 로드 완료, 표시 준비 완료. 호출당 최대 1회 발화하며, 항상 onReward / onClose 이전에 발화합니다. onError 시에는 발화 하지 않습니다(광고가 fetch되지 않았으므로). "로딩 중..." UI 숨김, 사용자 입력 잠금 등 UI 후처리에 사용하세요.
onReward() — 사용자가 광고를 끝까지 시청 완료. 이 시점에 리워드를 지급하세요.
onClose() — 광고는 표시됐지만 사용자가 완주 전에 닫음. 리워드 지급 X.
onError(err) — 광고 자체가 표시되지 못함. err.code(§6)를 보고 재시도 / 진입점 숨김 / 대체 리워드 경로 등 후속 처리를 결정하세요.

순서 보장

광고가 fill될 때 onAdLoaded는 항상 onReward / onClose보다 먼저 발화합니다.
onAdLoaded는 onError와 함께 발화하지 않습니다.
onAdLoaded는 광고 fetch 완료 시점에 발화하며, 표시 시작 전에 보장됩니다. 모든 종결 콜백 대비 순서는 항상 보장됩니다.

UI는 매체의 자유. showRewardedAd()는 광고 표시와 결과 콜백만 책임집니다. §3 예시의 버튼은 단순 예시일 뿐 — 버튼이든, 탭 가능한 카드든, 게임 라운드 종료 후 자동 호출이든, 일일 출석 플로우든, 코인 부족 모달이든 매체가 자유롭게 디자인할 수 있습니다.

`BuvlorAds.preloadRewardedAd({ slotId })`

선택. 첫 번째 미디에이션 티어를 사전 준비해 이후 showRewardedAd 호출의 지연을 최소화합니다.

6. 에러 코드

onError는 { code, message }를 전달받습니다. code는 아래 중 하나입니다.

Code	의미	매체 권장 대응
`all_unavailable`	미디에이션이 모든 티어를 시도했으나 채우지 못함.	"잠시 후 다시 시도해 주세요" 안내 노출.
`invalid_slot`	슬롯 설정이 잘못되었거나 누락됨.	Buvlor에 문의 — 설정 측 이슈.
`init_failed`	SDK가 사이트 설정을 로드/파싱하지 못함.	네트워크 연결 확인 후 재시도.

7. FAQ

Q. 광고가 안 떠요. 어떻게 디버깅하나요? 순서대로 세 가지를 확인하세요. (1) Buvlor가 전달한 광고 파트너 site-script가 페이지 <head>에 로드되어 있고 readyState: complete까지 도달했는지, (2) 브라우저 콘솔에 [BuvlorAds] 프리픽스로 찍히는 init 실패·슬롯 에러 로그가 있는지, (3) onError 콜백의 code가 §6의 어떤 토큰인지. 세 가지가 모두 정상이면 siteId, 슬롯명, 콘솔 로그를 ads@buvlor.com으로 보내주세요.

Q. setIdentity는 언제 호출해야 하나요? 광고ID가 페이지 로드 시점에 확보돼 있으면 init({siteId, identity}) 옵션에 바로 넘기는 것이 권장 경로입니다. 네이티브 브리지 비동기 호출, 1st-party UUID 지연 생성 등으로 식별자가 늦게 확보되는 경우에만 setIdentity(value)를 별도로 호출하세요. init 이전에 호출된 setIdentity()는 자동으로 큐잉되어 init 완료 시점에 반영됩니다.

Q. 새 도메인을 추가하려면 어떻게 하나요? ads@buvlor.com으로 새 도메인을 보내주세요. Buvlor가 서버 측에 등록하고 _buvlor.<새 도메인>용 DNS TXT 레코드를 새로 발급합니다. 레코드가 전파되면 동일한 siteId가 새 도메인에서도 작동합니다 — 매체 측 코드 변경은 필요하지 않습니다.

Q. 다른 광고 SDK와 함께 써도 되나요? 가능합니다. Buvlor Ads는 리워드 비디오 전용이며 자체 글로벌 네임스페이스로 격리되어 있어, 같은 페이지의 디스플레이/네이티브/타사 리워드 SDK와 충돌하지 않습니다.

Q. 꼭 버튼으로만 showRewardedAd를 호출해야 하나요? 아닙니다. §3의 <button>은 단순 예시입니다. 게임 라운드 종료 팝업, 일일 출석 탭, 코인 부족 모달, 홈 화면의 카드 영역, 또는 코드 내 자동 호출 등 매체가 원하는 어떤 UI / 시점 / 방식으로도 호출할 수 있습니다. 광고 표시는 SDK가 담당하고, 언제 어디서 호출할지는 매체가 결정합니다.

Q. onAdLoaded는 언제 발화하나요? 로딩 스피너 숨김에 써도 되나요? 네, 그게 의도된 사용 사례입니다. onAdLoaded는 광고 fetch가 완료되어 표시 준비가 됐을 때 발화합니다 — 광고가 화면에 실제로 나타나기 직전, onReward / onClose보다 먼저 1회 발화합니다. onError 시에는 발화하지 않습니다. showRewardedAd() 호출 직후 로딩 스피너를 띄우고, onAdLoaded에서 숨기는 패턴을 사용하세요. 순서 보장(onAdLoaded → 종결 콜백)은 항상 유지되므로, 스피너 숨김 코드가 리워드 지급 코드보다 늦게 실행되는 일은 없습니다.

8. 문의 / Contact

통합 / 지원: ads@buvlor.com
siteId 발급 요청: 사이트 도메인, 담당자명, 도입하려는 리워드 슬롯명을 함께 알려주세요. 스테이징 설정과 디버그 토큰은 요청 시 발급해 드립니다.

Buvlor Ads SDK — Publisher integration guide.

1. Overview

2. Prerequisites

3. Quick Start

3.1 Install — page <head> (once per page)

3.2 Invoke — on user action (anywhere in your product)

4. Identity

5. API Reference

BuvlorAds.init(options)

BuvlorAds.setIdentity(value) / BuvlorAds.clearIdentity()

BuvlorAds.showRewardedAd(options)

BuvlorAds.preloadRewardedAd({ slotId })

6. Error Codes

7. FAQ

8. Contact

1. 개요

2. 사전 준비

3. 통합 (Quick Start)

3.1 설치 — 페이지 <head> (1회)

3.2 호출 — 사용자 액션 시점 (어디서든)

4. Identity (디바이스 광고ID)

5. API 레퍼런스

BuvlorAds.init(options)

BuvlorAds.setIdentity(value) / BuvlorAds.clearIdentity()

BuvlorAds.showRewardedAd(options)

BuvlorAds.preloadRewardedAd({ slotId })

6. 에러 코드

7. FAQ

8. 문의 / Contact

3.1 Install — page `<head>` (once per page)

`BuvlorAds.init(options)`

`BuvlorAds.setIdentity(value)` / `BuvlorAds.clearIdentity()`

`BuvlorAds.showRewardedAd(options)`

`BuvlorAds.preloadRewardedAd({ slotId })`

3.1 설치 — 페이지 `<head>` (1회)

`BuvlorAds.init(options)`

`BuvlorAds.setIdentity(value)` / `BuvlorAds.clearIdentity()`

`BuvlorAds.showRewardedAd(options)`

`BuvlorAds.preloadRewardedAd({ slotId })`