Naver Ad Manager SDK 연동

NAM (Naver Ad Manager) Instream SDK를 사용한 Pre-roll 영상 광고를 지원합니다. options.namAds.adScheduleId에 NAM 광고 스케줄 ID를 전달하면 콘텐츠 재생 전에 광고가 자동으로 재생됩니다.

IMA와 병행 가능: ads(IMA)와 namAds(NAM)를 동시에 설정할 수 있으며, 각각 독립적으로 동작합니다.

테스트 플레이어

NAM 광고 스케줄 ID를 입력하고 플레이어를 생성하면 Pre-roll 광고가 연동된 플레이어를 바로 테스트할 수 있습니다.

adScheduleId를 입력하면 플레이어가 표시됩니다

동작 방식

NAM gfp-instream.js SDK는 외부에서 자동 로드됩니다 (번들에 포함되지 않음).
광고 재생 중 콘텐츠 비디오는 자동으로 일시정지되고, 컨트롤바가 숨겨집니다.
광고 완료/스킵/에러 후 콘텐츠가 자동 재생됩니다.
namAds 옵션이 없으면 기존과 동일하게 동작합니다 (회귀 영향 없음).

NamAdOptions 전체 옵션

이름	타입	기본값	설명
adScheduleId	string	required	NAM 광고 스케줄 ID
adSchedulePolicy	object	{ pre: true }	광고 스케줄 정책 (pre/mid/post)
adPlayerType	string	undefined	광고 플레이어 타입 ("HTML5_PC" \| "HTML5_MO" \| "SMART_TV")
contentDuration	number	auto	콘텐츠 길이(초). 미지정 시 자동 감지
customParam	Record<string, string \| string[] \| number>	undefined	광고 타겟팅 파라미터
sdkUrl	string	undefined	gfp-instream.js SDK URL 오버라이드
phase	string	"production"	NAM SDK 환경 ("test" \| "production")

React / UMD 예제

"use client";

import Hls from "hls.js";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

export default function NamAdPlayer() {
    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,
                namAds: {
                    adScheduleId: "YOUR_AD_SCHEDULE_ID",
                },
            }}
            onEvent={(event) => {
                switch (event.type) {
                    case "adBreakStart":
                        console.log("광고 구간 시작");
                        break;
                    case "adBreakEnd":
                        console.log("광고 구간 종료, 콘텐츠 재생");
                        break;
                    case "adLoaded":
                        console.log("광고 로드 완료");
                        break;
                    case "adStarted":
                        console.log("광고 재생 중");
                        break;
                    case "adComplete":
                        console.log("광고 재생 완료");
                        break;
                    case "adSkipped":
                        console.log("광고 스킵됨");
                        break;
                    case "adError":
                        console.log("광고 에러", event.data?.message);
                        break;
                }
            }}
        />
    );
}

NAM 광고 이벤트

이벤트	설명
adBreakStart	광고 구간 시작 (콘텐츠 일시정지)
adBreakEnd	광고 구간 종료 (콘텐츠 재생 재개)
adLoaded	광고 로드 완료
adStarted	개별 광고 재생 시작
adComplete	개별 광고 재생 완료
adSkipped	사용자가 광고 스킵
adError	광고 로드/재생 에러 (event.data.message에 상세 메시지)

고급 설정 예제

NamAdOptions의 전체 옵션을 활용한 예제입니다.

namAds: {
    adScheduleId: "YOUR_AD_SCHEDULE_ID",  // 필수
    adSchedulePolicy: {
        pre: true,      // Pre-roll 활성화 (기본값: true)
        mid: false,     // Mid-roll (기본값: false, 향후 지원)
        post: false,    // Post-roll (기본값: false, 향후 지원)
    },
    adPlayerType: "HTML5_PC",  // "HTML5_PC" | "HTML5_MO" | "SMART_TV"
    contentDuration: 120,      // 콘텐츠 길이(초). 미지정 시 video element에서 자동 감지
    customParam: {             // 광고 타겟팅 파라미터
        category: "entertainment",
        age: "20s",
    },
    phase: "production",       // "test" | "production"
    sdkUrl: "https://custom-cdn.example.com/gfp-instream.js",  // SDK URL 오버라이드 (선택)
}