@sgrsoft/vpe-react-sdk 0.1.21 → 0.1.23

package/README.md

@@ -114,6 +114,7 @@ export function App() {
 | devTestAppId | string | vpe-core-sdk 기본값 | No | 개발 테스트용 AppId |
 | token | string | vpe-core-sdk 기본값 | No | 스트림 URL 토큰 |
 | override | object | vpe-core-sdk 기본값 | No | 이벤트/동작 오버라이드 |
+| ads | AdOptions | - | No | Pre-roll 광고 설정 (Google IMA) |
 | layout | ControlBarLayout \| Variant \| Responsive | SDK 기본 레이아웃 | No | 컨트롤바 레이아웃 |
 
 참고
@@ -575,6 +576,38 @@ export function App() {
 />
 ```
 
+### ads
+- Pre-roll 광고를 설정합니다. Google IMA SDK 기반으로 동작합니다.
+- `tagUrl`에 VAST 태그 URL을 전달하면 콘텐츠 재생 전에 광고가 자동 재생됩니다.
+- 광고 재생 중 콘텐츠 비디오는 자동으로 일시정지되고, 컨트롤바가 숨겨집니다.
+- 광고 완료/스킵/에러 후 콘텐츠가 자동 재생됩니다.
+```tsx
+<VpePlayer
+    accessKey="YOUR_ACCESS_KEY"
+    hls={Hls}
+    options={{
+        playlist: [
+            {
+                file: "https://CDN_DOMAIN/example.m3u8"
+            }
+        ],
+        autostart: true,
+        muted: true,
+        ads: {
+            tagUrl: "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_preroll_skippable&sz=640x480&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=",
+            enabled: true, // 기본값: true. false로 설정하면 광고 비활성화
+        },
+    }}
+/>
+```
+
+**AdOptions 타입**
+
+| 옵션 | 타입 | 기본값 | 필수 | 설명 |
+| --- | --- | --- | --- | --- |
+| tagUrl | string | - | Yes | VAST/VMAP 광고 태그 URL |
+| enabled | boolean | `true` | No | 광고 활성화 여부 |
+
 ---
 
 ### layout
@@ -800,6 +833,10 @@ playerRef.current?.addPrevSource([
 | skipBack | 뒤로 건너뜀 |
 | playlistChange | 플레이리스트 변경 |
 | error | 오류 발생 |
+| adStart | 광고 재생 시작 |
+| adComplete | 광고 재생 완료 |
+| adSkip | 사용자가 광고 스킵 |
+| adError | 광고 로드/재생 에러 |
 
 ## One Click Multi DRM 예제
 ```ts
@@ -864,3 +901,96 @@ options={{
     ],
 }}
 ```
+
+## Pre-roll 광고 (Google IMA)
+
+Google IMA SDK를 사용한 Pre-roll 영상 광고를 지원합니다.
+`options.ads.tagUrl`에 VAST 태그 URL을 전달하면 콘텐츠 재생 전에 광고가 자동으로 재생됩니다.
+
+- Google IMA SDK는 외부에서 자동 로드됩니다 (번들에 포함되지 않음)
+- 광고 재생 중 콘텐츠 비디오는 자동으로 일시정지되고, 컨트롤바가 숨겨집니다
+- 광고 완료/스킵/에러 후 콘텐츠가 자동 재생됩니다
+- `ads` 옵션이 없으면 기존과 동일하게 동작합니다
+
+### React (ESM) 예제
+
+```tsx
+"use client";
+
+import Hls from "hls.js";
+import { VpePlayer } from "@sgrsoft/vpe-react-sdk";
+
+export default function AdPlayer() {
+    return (
+        <VpePlayer
+            accessKey="YOUR_ACCESS_KEY"
+            hls={Hls}
+            options={{
+                playlist: [
+                    {
+                        file: "https://CDN_DOMAIN/example.m3u8",
+                        poster: "https://CDN_DOMAIN/poster.jpg",
+                    },
+                ],
+                autostart: true,
+                muted: true,
+                ads: {
+                    tagUrl: "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_preroll_skippable&sz=640x480&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=",
+                },
+            }}
+            onEvent={(event) => {
+                switch (event.type) {
+                    case "adStart":
+                        console.log("광고 시작");
+                        break;
+                    case "adComplete":
+                        console.log("광고 완료");
+                        break;
+                    case "adSkip":
+                        console.log("광고 스킵");
+                        break;
+                    case "adError":
+                        console.log("광고 에러", event.data?.message);
+                        break;
+                }
+            }}
+        />
+    );
+}
+```
+
+### UMD 예제
+
+```html
+<script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key=YOUR_ACCESS_KEY"></script>
+<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
+
+<div id="video"></div>
+
+<script>
+    const player = new ncplayer("video", {
+        playlist: [
+            { file: "https://CDN_DOMAIN/example.m3u8" },
+        ],
+        autostart: true,
+        muted: true,
+        ads: {
+            tagUrl: "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_preroll_skippable&sz=640x480&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=",
+        },
+    });
+
+    player.on("adStart", function(e) { console.log("광고 시작"); });
+    player.on("adComplete", function(e) { console.log("광고 완료"); });
+    player.on("adSkip", function(e) { console.log("광고 스킵"); });
+    player.on("adError", function(e) { console.log("광고 에러", e.data?.message); });
+</script>
+```
+
+### 광고 이벤트
+
+| 이벤트 | 설명 |
+| --- | --- |
+| adStart | 광고 재생 시작 |
+| adComplete | 광고 재생 완료 |
+| adSkip | 사용자가 광고 스킵 |
+| adError | 광고 로드/재생 에러 (`event.data.message`에 상세 메시지) |