Naver Ad Manager SDK 연동

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

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

동작 방식

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

기본 사용법

const player = new ncplayer("video", {
    playlist: [
        { file: "https://CDN_DOMAIN/example.m3u8" },
    ],
    autostart: true,
    muted: true,
    namAds: {
        adScheduleId: "YOUR_AD_SCHEDULE_ID",
    },
});

// 광고 이벤트 수신
player.on("adBreakStart", function(e) { console.log("광고 구간 시작"); });
player.on("adBreakEnd", function(e) { console.log("광고 구간 종료"); });
player.on("adLoaded", function(e) { console.log("광고 로드"); });
player.on("adStarted", function(e) { console.log("광고 재생"); });
player.on("adComplete", function(e) { console.log("광고 완료"); });
player.on("adSkipped", function(e) { console.log("광고 스킵"); });
player.on("adError", function(e) { console.log("광고 에러", e.data?.message); });

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")

NAM 광고 이벤트

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

고급 설정 예제

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

const player = new ncplayer("video", {
    playlist: [
        { file: "https://CDN_DOMAIN/example.m3u8" },
    ],
    autostart: true,
    muted: true,
    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"
    },
});

전체 HTML 예제

<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>VPE Player - NAM 광고</title>
    <script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key=YOUR_ACCESS_KEY"></script>
</head>
<body>
    <div id="video" style="max-width: 800px; margin: 0 auto;"></div>

    <script>
        const player = new ncplayer("video", {
            playlist: [
                {
                    file: "https://CDN_DOMAIN/example.m3u8",
                    poster: "https://CDN_DOMAIN/poster.jpg",
                },
            ],
            autostart: true,
            muted: true,
            namAds: {
                adScheduleId: "YOUR_AD_SCHEDULE_ID",
            },
        });

        player.on("adBreakStart", function(e) {
            console.log("광고 구간 시작");
        });
        player.on("adBreakEnd", function(e) {
            console.log("광고 구간 종료, 콘텐츠 재생");
        });
        player.on("adStarted", function(e) {
            console.log("광고 재생 중");
        });
        player.on("adComplete", function(e) {
            console.log("광고 재생 완료");
        });
        player.on("adSkipped", function(e) {
            console.log("광고 스킵됨");
        });
        player.on("adError", function(e) {
            console.log("광고 에러", e.data?.message);
        });
    </script>
</body>
</html>