Web SDK

이 문서는 애드팝콘 SSP Web SDK를 사용하여 광고를 노출하고 이벤트를 처리하는 방법에 대한 연동 가이드입니다.

1. SDK 라이브러리 로드

연동이 필요한 페이지에 아래 SDK 스크립트를 추가합니다.

HTML

<head>
   <script
      async
      src="https://webapi.adpopcorn.com/ssp/web-sdk/ap-ssp-web-sdk-1.14.0.min.js"
    ></script>
</head>

2. SDK 초기화 및 설정

SDK를 초기화하고 config를 설정해야 합니다. init함수를 호출하여 app_key와 placement_id를 설정하고, setConfig함수를 사용하여 Android 또는 iOS 플랫폼에 따라 해당 운영 체제에 맞는 config를 구성합니다.

1) init 함수 전달용 객체 속성 정의

속성

Type

필수

설명

default

app_key

string

매체용으로 발급 된 광고 앱 키

placement_id

string

매체용으로 발급 된 광고 지면 아이디

log_enabled

boolean

sdk 세부 로그 출력 유, 무(설정하지 않을 경우, 에러 레벨의 로그만 출력 됩니다.)

false

2) setConfig 함수 전달용 객체 속성 정의

광고 물량은 전달 가능한 파라미터 범위에 따라 달라질 수 있습니다. 가능한 범위 내 최대한 전달해주시길 바랍니다.

플랫폼 기준 공통으로 적용하는 항목 외에는 각 OS에 맞게 전달해 주시기 바랍니다.

플랫폼

속성

Type

필수

설명

default

Android

adid

string

Android 광고 식별자

iOS

idfa

string

iOS 광고 식별자

iOS

idfv

string

N(Y)

벤더 식별자 (단, 광고 추적 미동의로 idfa를 전달할 수 없는 경우, idfv 값을 필수로 전달)

공통

network

string

네트워크(wifi or mobile)

공통

carrier

string

통신사

공통

model

string

모델명

공통

manufacturer

string

제조사

공통

os_version

string

플랫폼 OS 버전

"0"

공통

tag_for_child

0 | 1

만 14세 미만 연령 제한 플래그 (기본값: 비활성화, 활성화 시 광고 미송출)

HTML

<head>
  <script>
    window.AdPopcornSSPWebSDK = window.AdPopcornSSPWebSDK || { cmd: [] };
    AdPopcornSSPWebSDK.cmd.push(() => {
      AdPopcornSSPWebSDK.init({
        app_key: "...",
        placement_id: "...",
        ...optional,
      });
      
      // android용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        adid: "...",
        ...optional,
      });

      // iOS용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        idfa: "...",
        ...optional,
      });
    });
  </script>
</head>

3-1. 광고 연동 (기본)

광고를 노출할 div 요소에 id attribute를 포함하여 HTML에 추가합니다. 설정한 id를 display 함수 인자로 전달하면 해당 요소에 광고가 삽입되어 노출됩니다. 실행 스크립트는 <body> 요소의 하단에 삽입하는 것을 권장합니다.

1) 적용 방식

아래 코드는 광고를 표시할 요소(광고 인벤토리 영역)와 실행 코드를 포함하고 있습니다. SDK에서 제공하는 인스턴스 생성 함수를 사용하여 광고 타입별 인스턴스를 생성하고, display 함수를 사용하여 광고를 표시합니다.

인스턴스 생성 함수 정의

앱키, 지면 아이디를 인스턴스에 전달하면 SDK init 설정과 별개로 인스턴스 개별 설정을 사용할 수 있습니다.

함수 명

설명

createInterstitial

전면 광고 인스턴스 생성용

createInterstitialVideo

전면 비디오 광고 인스턴스 생성용

createBannerSize300x250

배너 광고 인스턴스 생성용(사이즈: 300x250)

createBannerSize320x50

배너 광고 인스턴스 생성용(사이즈: 320x50)

createBannerSize320x100

배너 광고 인스턴스 생성용(사이즈: 320x100)

createRewardVideo

리워드 비디오 광고 인스턴스 생성용

인스턴스 생성 함수(create-) 전달용 객체 속성 정의

광고타입

속성 명

Type

필수

설명

default

공통

app_key

string

매체용으로 발급된 광고 앱 키

공통

placement_id

string

매체용으로 발급된 광고 지면 아이디

전면 비디오/ 리워드 비디오

user_landing_enabled

boolean

광고 클릭 시, 랜딩 페이지로 이동 허용 여부

true

인스턴스 함수 정의

광고타입

함수 명

설명

공통

display

광고 요소를 화면에 표시

전면 비디오/ 리워드 비디오

terminateAd

구성된 광고 요소의 재생 중단 및 즉시 종료

인스턴스 함수 전달용 파라미터 속성 정의

함수 명

속성 명

Type

필수

설명

display

string

광고 인벤토리를 구성할 요소의 id 속성명

terminateAd

string

광고 인벤토리가 구성된 요소의 id 속성명

HTML

<body>
  <!-- 전면 배너 광고를 표시할 요소 -->
  <div id="banner-300-250-ad-inventory-frame"></div>
  <div id="banner-320-50-ad-inventory-frame"></div>
  <div id="banner-320-100-ad-inventory-frame"></div>
  <!-- 광고 실행 코드(body 최하단 삽입 권장) -->
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      // 개별 설정 미사용시, 배너 광고 인스터스 생성
      const banner300x250 = AdPopcornSSPWebSDK.createBannerSize300x250();
      const banner320x50 = AdPopcornSSPWebSDK.createBannerSize320x50();
      const banner320x100 = AdPopcornSSPWebSDK.createBannerSize320x100();      
      
      // 개별 설정 사용시, 배너 광고 인스턴스 생성
      const banner300x250 = AdPopcornSSPWebSDK.createBannerSize300x250({
        app_key: "...",
        placement_id: "..."
      });
      const banner320x50 = AdPopcornSSPWebSDK.createBannerSize320x50({
        app_key: "...",
        placement_id: "..."
      });
      const banner320x100 = AdPopcornSSPWebSDK.createBannerSize320x100({
        app_key: "...",
        placement_id: "..."
      });        

      // 배너 광고 노출
      banner300x250.display("banner-300-250-ad-inventory-frame");
      banner320x50.display("banner-320-50-ad-inventory-frame");
      banner320x100.display("banner-320-100-ad-inventory-frame");
    });
  </script>
</body>

HTML

<body>
  <!-- 전면 광고를 표시할 요소 -->
  <div id="interstitial-ad-inventory-frame"></div>
  <!-- 광고 실행 코드(body 최하단 삽입 권장) -->
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      // 개별 설정 미사용시, 전면 광고 인스터스 생성
      const interstitial = AdPopcornSSPWebSDK.createInterstitial();      
      
      // 개별 설정 사용시, 전면 광고 인스턴스 생성
      const interstitial = AdPopcornSSPWebSDK.createInterstitial({
        app_key: "...",
        placement_id: "..."
      });

      // 전면 광고 노출
      interstitial.display("interstitial-ad-inventory-frame");
    });
  </script>
</body>

HTML

<body>
  <!-- 전면 비디오 광고를 표시할 요소 -->
  <div id="interstitial-video-ad-inventory-frame"></div>
  <!-- 광고 실행 코드(body 최하단 삽입 권장) -->
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      // 개별 설정 미사용시, 전면 광고 인스터스 생성
      const interstitialVideo = AdPopcornSSPWebSDK.createInterstitialVideo();      
      
      // 개별 설정 사용시, 전면 광고 인스턴스 생성
      const interstitialVideo = AdPopcornSSPWebSDK.createInterstitialVideo({
        app_key: "...",
        placement_id: "...",
        user_landing_enabled: "..."
      });

      // 전면 비디오 광고 노출
      interstitial.display("interstitial-video-ad-inventory-frame");
      
      // 전면 비디오 광고 강제 제거 필요시 실행
      interstitial.terminateAd("interstitial-video-ad-inventory-frame");
    });
  </script>
</body>

[ setUserId 함수 전달용 파라미터 속성 정의 ]

주의사항

1명의 유저는 1개의 고유한 유저식별값을 가져야하며, 가변적인 값을 사용해서는 안됩니다.
개인정보(이메일, 이름, 전화번호, 식별가능한 유저아이디 등)이 포함되어서는 안됩니다.
비디오 광고 노출 함수 실행 전에 설정되어야 합니다.

CS 처리 기능을 위해 유저식별값(userId)을 필수로 설정해주세요.

속성명

Type

필수

userId

string

리워드 비디오 시청 완료 시 완료 유저를 식별하기 위해 사용되는 값

HTML

<body>
  <!-- 전면 배너 광고를 표시할 요소 -->
  <div id="reward-video-ad-inventory-frame"></div>
  <!-- 광고 실행 코드(body 최하단 삽입 권장) -->
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      // 개별 설정 미사용시, 리워드 비디오 광고 인스터스 생성
      const rewardVideo = AdPopcornSSPWebSDK.createRewardVideo();
      
      // 개별 설정 사용시, 리워드 비디오 광고 인스턴스 생성
      const rewardVideo = AdPopcornSSPWebSDK.createRewardVideo({
        app_key: "...",
        placement_id: "...",
        user_landing_enabled: "..."
      });
      
      // 리워드 비디오 CS 처리 기능을 위한 유저 식별값 필수 설정
      rewardVideo.setUserId("...")     

      // 리워드 비디오 광고 노출
      rewardVideo.display("reward-video-ad-inventory-frame");
      
      // 리워드 비디오 광고 강제 제거 필요시 실행
      rewardVideo.terminateAd("reward-video-ad-inventory-frame");
    });
  </script>
</body>

2) 패스백 (구글 -> Web SDK)

HTML

<head>
  <!-- 스크립트 추가 -->
  <script
    async
    src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"
  ></script>
  <script
    async
    src="https://webapi.adpopcorn.com/ssp/web-sdk/ap-ssp-web-sdk-1.14.0.min.js"
  ></script>
  <!-- 스크립트 초기화 및 설정 -->
  <script>
    window.googletag = window.googletag || { cmd: [] };
    window.AdPopcornSSPWebSDK = window.AdPopcornSSPWebSDK || { cmd: [] };

    AdPopcornSSPWebSDK.cmd.push(() => {
      AdPopcornSSPWebSDK.init({
        app_key: "...",
        placement_id: "...",
        ...optional,
      });

      // android용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        adid: "...",
        ...optional,
      });

      // iOS용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        idfa: "...",
        ...optional,
      });
    });
  </script>
</head>
<body>
  <!-- 구글 배너 광고를 표시할 요소  -->
  <div id="google-banner-ad-inventory-frame"></div>
  <!-- 애드팝콘 광고를 표시할 요소  -->
  <div id="adpopcorn-ad-inventory-frame"></div>
  <script>
    // 구글 스크립트 연동
    
    googletag.cmd.push(() => {
      // 광고 슬롯 정의 및 서비스 추가
      const googleSlotElementId = 'google-banner-ad-inventory-frame';
      googletag.defineSlot(
        "...",
        [300,250],
        googleSlotElementId
      )
      .addService(googletag.pubads());
      
      // 이벤트 리스너 추가
      googletag.pubads().addEventListener("slotRenderEnded", (event) => {
        // 구글 스크립트 실행 결과, 광고가 없을 경우 애드팝콘 패스백 처리
        if (event.slot.getSlotElementId() === googleSlotElementId && event.isEmpty) {
          // 애드팝콘 스크립트 연동
          AdPopcornSSPWebSDK.cmd.push(() => {
            // 연동 가이드의 3.광고 연동 > 1)광고 노출, 4. 광고 이벤트 처리 참조
            // [필수] 1.광고 인스턴스 생성
            // [옵션] 2 [리워드비디오] 유저 식별값 설정
            // [옵션] 3.광고 이벤트 처리
            // [필수] 4.광고 노출
          });
        }
      });
      
      // 광고 서비스 설정 및 활성화
      googletag.pubads().enableSingleRequest();
      googletag.pubads().set("page_url", "...");
      googletag.enableServices();
      
      // 광고 노출
      googletag.display("google-banner-ad-inventory-frame");
    });
  </script>
</body>

HTML

<head>
  <!-- 스크립트 추가 -->
  <script
    async
    src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"
  ></script>
  <script
    async
    src="https://webapi.adpopcorn.com/ssp/web-sdk/ap-ssp-web-sdk-1.14.0.min.js"
  ></script>
  <!-- 스크립트 초기화 및 설정 -->
  <script>
    window.googletag = window.googletag || { cmd: [] };
    window.AdPopcornSSPWebSDK = window.AdPopcornSSPWebSDK || { cmd: [] };

    AdPopcornSSPWebSDK.cmd.push(() => {
      AdPopcornSSPWebSDK.init({
        app_key: "...",
        placement_id: "...",
        ...optional,
      });

      // android용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        adid: "...",
        ...optional,
      });

      // iOS용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        idfa: "...",
        ...optional,
      });
    });
  </script>
</head>
<body>
  <!-- 애드팝콘 광고를 표시할 요소  -->
  <div id="adpopcorn-ad-inventory-frame"></div>
  <script>
    // 구글 스크립트 연동
    googletag.cmd.push(() => {
      // 광고 슬롯 정의 및 서비스 추가
      const interstitialSlot = googletag.defineOutOfPageSlot(
        "...",
        googletag.enums.OutOfPageFormat.INTERSTITIAL
      );

      if (interstitialSlot) {
        interstitialSlot.addService(googletag.pubads()).setConfig({
          interstitial: {
            triggers: {
              unhideWindow: true,
            },
          },
        });
      }
      
      // 이벤트 리스너 추가
      googletag.pubads().addEventListener("slotRenderEnded", (event) => {
        // 구글 스크립트 실행 결과, 광고가 없을 경우 애드팝콘 패스백 처리
        if (event.isEmpty) {
          // 애드팝콘 스크립트 연동
          AdPopcornSSPWebSDK.cmd.push(() => {
            // 3.광고 연동 > 1)광고 노출, 4. 광고 이벤트 처리 연동 가이드 참조
            // [필수] 1.광고 인스턴스 생성
            // [옵션] 2 [리워드비디오] 유저 식별값 설정
            // [옵션] 3.광고 이벤트 처리
            // [필수] 4.광고 노출
          });
        }
      });
      
      // 광고 서비스 설정 및 활성화
      googletag.pubads().enableSingleRequest();
      googletag.pubads().set("page_url", "...");
      googletag.enableServices();
      
      // 광고 노출
      googletag.display(interstitialSlot);
    });
  </script>
</body>

HTML

<head>
  <!-- 스크립트 추가 -->
  <script
    async
    src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"
  ></script>
  <script
    async
    src="https://webapi.adpopcorn.com/ssp/web-sdk/ap-ssp-web-sdk-1.14.0.min.js"
  ></script>
  <!-- 스크립트 초기화 및 설정 -->
  <script>
    window.googletag = window.googletag || { cmd: [] };
    window.AdPopcornSSPWebSDK = window.AdPopcornSSPWebSDK || { cmd: [] };

    AdPopcornSSPWebSDK.cmd.push(() => {
      AdPopcornSSPWebSDK.init({
        app_key: "...",
        placement_id: "...",
        ...optional,
      });

      // android용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        adid: "...",
        ...optional,
      });

      // iOS용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        idfa: "...",
        ...optional,
      });
    });
  </script>
</head>
<body>
  <!-- 애드팝콘 광고를 표시할 요소  -->
  <div id="adpopcorn-ad-inventory-frame"></div>
  <script>
    // 구글 스크립트 연동
    googletag.cmd.push(() => {
      // 광고 슬롯 정의 및 서비스 추가
      const interstitialVieoSlot = googletag.defineOutOfPageSlot(
        "...",
        googletag.enums.OutOfPageFormat.REWARDED
      );

      if (interstitialVieoSlot) {
        interstitialVieoSlot.addService(googletag.pubads());
      }
      
      // 이벤트 리스너 추가
      googletag.pubads().addEventListener("slotRenderEnded", (event) => {
        // 구글 스크립트 실행 결과, 광고가 없을 경우 애드팝콘 패스백 처리
        if (event.isEmpty) {
          // 애드팝콘 스크립트 연동
          AdPopcornSSPWebSDK.cmd.push(() => {
            // 3.광고 연동 > 1)광고 노출, 4. 광고 이벤트 처리 연동 가이드 참조
            // [필수] 1.광고 인스턴스 생성
            // [옵션] 2 [리워드비디오] 유저 식별값 설정
            // [옵션] 3.광고 이벤트 처리
            // [필수] 4.광고 노출
          });
        }
      });
      
      googletag.pubads().addEventListener("rewardedSlotReady", (e) => {
        // 광고가 준비되었을 때, 광고 슬롯의 visible 속성 변경
        e.makeRewardedVisible();
      });
      googletag.pubads().addEventListener("rewardedSlotClosed", () => {
        // 광고 닫기 이벤트가 감지되었을 때, 광고 슬롯 제거
        googletag.destroySlots([interstitialVideoSlot]);
      });
      
      // 광고 서비스 설정 및 활성화
      googletag.pubads().enableSingleRequest();
      googletag.pubads().set("page_url", "...");
      googletag.enableServices();
      
      // 광고 노출
      googletag.display(interstitialVieoSlot);
    });
  </script>
</body>

HTML

<head>
  <!-- 스크립트 추가 -->
  <script
    async
    src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"
  ></script>
  <script
    async
    src="https://webapi.adpopcorn.com/ssp/web-sdk/ap-ssp-web-sdk-1.14.0.min.js"
  ></script>
  <!-- 스크립트 초기화 및 설정 -->
  <script>
    window.googletag = window.googletag || { cmd: [] };
    window.AdPopcornSSPWebSDK = window.AdPopcornSSPWebSDK || { cmd: [] };

    AdPopcornSSPWebSDK.cmd.push(() => {
      AdPopcornSSPWebSDK.init({
        app_key: "...",
        placement_id: "...",
        ...optional,
      });

      // android용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        adid: "...",
        ...optional,
      });

      // iOS용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        idfa: "...",
        ...optional,
      });
    });
  </script>
</head>
<body>
  <!-- 애드팝콘 광고를 표시할 요소  -->
  <div id="adpopcorn-ad-inventory-frame"></div>
  <script>
    // 구글 스크립트 연동
    googletag.cmd.push(() => {
      // 광고 슬롯 정의 및 서비스 추가
      const rewardVideoSlot = googletag.defineOutOfPageSlot(
        "...",
        googletag.enums.OutOfPageFormat.REWARDED
      );

      if (rewardVideoSlot) {
        rewardVideoSlot.addService(googletag.pubads());
      }
      
      // 이벤트 리스너 추가
      googletag.pubads().addEventListener("slotRenderEnded", (event) => {
        // 구글 스크립트 실행 결과, 광고가 없을 경우 애드팝콘 패스백 처리
        if (event.isEmpty) {
          // 애드팝콘 스크립트 연동
          AdPopcornSSPWebSDK.cmd.push(() => {
            // 3.광고 연동 > 1)광고 노출, 4. 광고 이벤트 처리 연동 가이드 참조
            // [필수] 1.광고 인스턴스 생성
            // [옵션] 2 [리워드비디오] 유저 식별값 설정
            // [옵션] 3.광고 이벤트 처리
            // [필수] 4.광고 노출
          });
        }
      });
      
      googletag.pubads().addEventListener("rewardedSlotReady", (e) => {
        // 광고가 준비되었을 때, 광고 슬롯의 visible 속성 변경
        e.makeRewardedVisible();
      });
      googletag.pubads().addEventListener("rewardedSlotClosed", () => {
        // 광고 닫기 이벤트가 감지되었을 때, 광고 슬롯 제거
        googletag.destroySlots([rewardVideoSlot]);
      });
      googletag.pubads().addEventListener('rewardedSlotGranted', (e) => {
        // 리워드 지급 조건에 부합했을 때, 리워드 정보 감지
        const reward = event.payload
      });
      
      // 광고 서비스 설정 및 활성화
      googletag.pubads().enableSingleRequest();
      googletag.pubads().set("page_url", "...");
      googletag.enableServices();
      
      // 광고 노출
      googletag.display(rewardVideoSlot);
    });
  </script>
</body>

3) 패스백 (Web SDK → Reward Banner)

HTML

<head>
  <!-- 스크립트 추가 -->
  <script
    async
    src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"
  ></script>
  <script
    async
    src="https://webapi.adpopcorn.com/ssp/web-sdk/ap-ssp-web-sdk-1.14.0.min.js"
  ></script>
  <!-- 스크립트 초기화 및 설정 -->
  <script>
    window.googletag = window.googletag || { cmd: [] };
    window.AdPopcornSSPWebSDK = window.AdPopcornSSPWebSDK || { cmd: [] };

    AdPopcornSSPWebSDK.cmd.push(() => {
      AdPopcornSSPWebSDK.init({
        app_key: "...",
        placement_id: "...",
        ...optional,
      });

      // android용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        adid: "...",
        ...optional,
      });

      // iOS용 config 설정
      AdPopcornSSPWebSDK.setConfig({
        idfa: "...",
        ...optional,
      });
    });
  </script>
</head>
<body>
  <!-- 배너 광고를 표시할 요소  -->
  <div id="adpopcorn-banner-ad-inventory-frame"></div>
  <script>
      const setPassbackBannerAd = (bannerAdInventoryFrameId, bannerAdId) => {
      
      // passback 광고를 표시할 요소 정의
      const bannerInventoryFrame = document.getElementById(
        bannerAdInventoryFrameId
      );
      
      // passback 광고 컨텐츠용 요소 정의
      const bannerAd = document.createElement("iframe");
      bannerAd.id = bannerAdId;
      
      // passback 광고 클릭 중복 발생 방지용 dataset 설정
      bannerAd.dataset.clicked = "false";     
      
      // passback 광고 노출 위치 기본 스타일 설정
      Object.assign(bannerAd.style, {
        border: "none",
        width: "320px",
        height: "100px",
      });

      // ❗️발급받은 iframe Reward Banner 스크립트를 사용 환경에 따라 셋팅한 뒤, bannerAdContent로 전달
      const bannerAdContent = "...";
      bannerInventoryFrame.appendChild(bannerAd);

      const bannerAdDocument =
        bannerAd.contentDocument || bannerAd.contentWindow?.document;

      if (bannerAdDocument) {
        bannerAdDocument.open();
        bannerAdDocument.write(bannerAdContent);
        bannerAdDocument.close();

        bannerAd.addEventListener("load", () => {
          bannerAdDocument.body.style.margin = "0";

          window.addEventListener("blur", () =>
            iframeClickEventHandler(bannerAd)
          );

          // 광고 로드 완료 시점에 iframe focus를 초기화
          window.focus();
        });
      }
    };

    const iframeClickEventHandler = (adElement) => {
      // 포커스된 요소가 iframe인지 확인
      if (
        !document.activeElement ||
        document.activeElement.tagName !== "IFRAME"
      )
        return;
        
      // 이미 클릭된 광고인지 확인
      if (adElement.dataset.clicked === "true") return;    

      const activeIframeId = document.activeElement.id;
      const adElementId = adElement.id;

      // 포커스된 iframe 요소가 광고 요소의 id와 일치하는지 확인
      if (activeIframeId === adElementId) {
        // 광고 클릭 중복 발생 방지용 dataset 설정
        adElement.dataset.clicked = "true";
        
        // ❗️패스백 배너 클릭 이벤트 처리 위치
        console.log("passback ad clicked");
      }

      // 광고 요소 클릭으로 창이 이동되었을 때 window 포커스 초기화
      window.addEventListener("visibilitychange", () => {
        window.focus();
      });
    };

    AdPopcornSSPWebSDK.cmd.push(() => {
      const bannerAdInventoryFrameId = "adpopcorn-banner-ad-inventory-frame";
      
      // 배너 사이즈 300x250 기준
      const banner = AdPopcornSSPWebSDK.createBannerSize320x100();

      banner.addEventListener("adInventoryRendered", (e) => {
        // 애드팝콘 NoAd시, Reward Banner 패스백 광고 호출
        if (e.isNoAd) {
          const passbackBannerAdId = "reward-banner-ad-inventory-frame";
          setPassbackBannerAd(bannerAdInventoryFrameId, passbackBannerAdId);
        }
      });
      
      banner.addEventListener("adClicked", () => {
        // ❗️ 애드팝콘 배너 클릭 이벤트 처리 위치
        console.log("adpopcorn ad clicked");
      });

      banner.display(bannerAdInventoryFrameId);
    });
  </script>
</body>

3-2. 광고 연동 (네이티브)

사용자가 커스텀하게 광고를 구성할 수 있도록 광고 데이터를 제공합니다. 실행 스크립트는 요소의 하단에 삽입하는 것을 권장합니다.

1) 적용 방식

아래 코드는 광고를 호출하는 실행 코드를 포함하고 있습니다. SDK에서 제공하는 Native 인스턴스 생성 함수를 사용하여 인스턴스를 생성하고, loadAd 함수를 실행하여 광고를 호출합니다.

주의사항

loadAd 호출에 대한 결과 광고 수신에 실패한 경우, loadAd를 재호출하면 안됩니다.

과도한 광고 호출 요청은 Block 사유가 됩니다.

인스턴스 생성 함수 정의

함수 명

설명

createNative

네이티브 광고 인스턴스 생성용

createNativeTemplate

네이티브 템플릿 광고 인스턴스 생성용

인스턴스 생성 함수 전달용 객체 속성 정의

속성 명

Type

필수

설명

app_key

string

매체용으로 발급된 광고 앱 키

placement_id

string

매체용으로 발급된 광고 지면 아이디

네이티브 인스턴스 함수 정의

주의사항

네이티브 광고 로딩 성공 후 리포트 수집을 위해 아래 함수를 필수로 호출해야 합니다. 단, 네이티브 템플릿은 [ 1) 광고 호출 ] 의 reportImpression, reportClick을 내장하고 있어 별도 호출이 필요하지 않습니다.

함수 명

설명

reportImpression

광고 로딩에 성공 후, 광고 데이터를 화면에 노출한 경우에 광고 노출 측정

reportClick

구성한 네이티브 광고를 클릭한 경우에 클릭 측정

<body>
  <!-- 광고 게재 위치 -->
  <div id="native-ad-inventory-frame"></div>

  <!-- 광고 실행 코드(body 최하단 삽입 권장) -->
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      // 개별 설정 미사용시, 네이티브 광고 인스턴스 생성
      const native = AdPopcornSSPWebSDK.createNative();
      
      // 개별 설정 사용시, 네이티브 광고 인스턴스 생성
      const native = AdPopcornSSPWebSDK.createNative({
        app_key: '[APP_KEY]',
        placement_id: '[PLACEMENT_ID]',
      });

      native.addEventListener('sdkError', (event) => {
        // 에러 케이스 대응
      });
    
      native.addEventListener('adLoadCompleted', (data) => {
        const { isNoAd, adData } = data; 
        
        if (isNoAd) {
          // no ad 케이스 대응
        }
                    
        // 마크업 작성 후 광고 요소(native-ad-inventory-frame)에 추가
      });
    
      native.loadAd();
      
      // ❗️광고 호출 결과 광고가 있는 경우, 아래 함수를 시점에 맞춰 필수 호출
      // 광고 호출 결과 수신용 adLoadCompleted 이벤트 리스너 사용법은 연동 가이드의 4. 광고 이벤트 처리 참조
      const reportNativeAdImpression = () => {
        // 네이티브 광고 노출 시점에 호출
        native.reportImpression();
      };
      
      const reportNativeAdClick = () => {
        // 네이티브 광고 클릭 시점에 호출
        native.reportClick();
      }
    });
  </script>
</body>

<body>
  <!-- 광고 게재 위치 -->
  <div id="native-ad-360x80"></div>

  <!-- 광고 실행 코드(body 최하단 삽입 권장) -->
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      // 개별 설정 미사용시, 네이티브 광고 인스턴스 생성
      const native = AdPopcornSSPWebSDK.createNativeTemplate();
      
      // 개별 설정 사용시, 네이티브 광고 인스턴스 생성
      const native = AdPopcornSSPWebSDK.createNativeTemplate({
        app_key: '[APP_KEY]',
        placement_id: '[PLACEMENT_ID]',
      });

      native.addEventListener('sdkError', (event) => {
        // 에러 케이스 대응
      });
      
      native.addEventListener('adLoadCompleted', (data) => {
        const { isNoAd, adElement } = data;
        
        if (isNoAd) {
           // no ad 케이스 대응
        }
        
        //❗️아래 기능은 필요한 경우 템플릿에 적용
        // 1. 인포마크 제거
        adElement.dataset.noPrivacy = 'true';

        // 2. 테두리 제거
        adElement.dataset.noBorder = 'true';
  
        // 3. 배경색 변경
        adElement.style.backgroundColor = '#F6F6F6';

        // 4. 라운드 처리
        adElement.style.borderRadius = '10px';
        
        // 광고 게재 위치에 템플릿 등록             
        native.displayTemplate(adElement, 'native-ad-360x80');
      });

      // 광고 호출
      native.loadAd();
    });
  </script>
</body>

2) 패스백 (Web SDK → NAM)

<head>
  <!-- 스크립트 추가 -->
  <!-- Web SDK -->
  <script
      async
      src="https://webapi.adpopcorn.com/ssp/web-sdk/ap-ssp-web-sdk-1.14.0.min.js"
    ></script>
  <!-- NAM -->
  <script async src="https://ssl.pstatic.net/tveta/libs/glad/prod/gfp-core.js"></script>
</head>
<body>
  <!-- 광고 게재 위치 -->
  <div id="native-ad-inventory-frame"></div>
    
  <!-- Web SDK -->
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      const native = AdPopcornSSPWebSDK.createNative({
        app_key: '[APP_KEY]',
        placement_id: '[PLACEMENT_ID]',
      });
    
      native.addEventListener('sdkError', (event) => {
        // 에러 케이스 대응
      });
    
      native.addEventListener('adLoadCompleted', (data) => {
        const { isNoAd, adData } = data; 
        
        if (isNoAd) {
            // ❗️ Web SDK 광고 응답이 없을 경우 NAM 호출
            loadNAMAd();
            return;
        }
                    
        // 마크업 작성 후 광고 요소(native-ad-inventory-frame)에 추가
      });
    
      native.loadAd();
    });
  </script>
  
  <!-- NAM -->
  <script>
    const loadNAMAd = () => {
      const namDiv = document.getElementById('native-ad-inventory-frame');

      namDiv.style.display = 'block';

      window.gladsdk = window.gladsdk || { cmd: [] };
      window.gladsdk.cmd.push(() => {
        const adSlotInfo = {
          adUnitId: '[AD_UNIT_ID]', // NAM에서 발급받은 adUnitId
          adSlotElementId: 'native-ad-inventory-frame', // 배너 광고를 표시할 요소
        };

        window.gladsdk.defineAdSlot(adSlotInfo);
        window.gladsdk.displayAd('native-ad-inventory-frame');
        });
    };
  </script>
</body>

<head>
  <!-- 스크립트 추가 -->
  <!-- Web SDK -->
  <script
      async
      src="https://webapi.adpopcorn.com/ssp/web-sdk/ap-ssp-web-sdk-1.14.0.min.js"
    ></script>
  <!-- NAM -->
  <script async src="https://ssl.pstatic.net/tveta/libs/glad/prod/gfp-core.js"></script>
</head>
<body>
  <!-- 광고 게재 위치 -->
  <div id="native-ad-360x80"></div>

  <!-- Web SDK -->
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      // 개별 설정 미사용시, 네이티브 광고 인스턴스 생성
      const native = AdPopcornSSPWebSDK.createNativeTemplate();
      
      // 개별 설정 사용시, 네이티브 광고 인스턴스 생성
      const native = AdPopcornSSPWebSDK.createNativeTemplate({
         app_key: '[APP_KEY]',
         placement_id: '[PLACEMENT_ID]',
      });

      native.addEventListener('sdkError', (event) => {
        // 에러 케이스 대응
      });
      
      native.addEventListener('adLoadCompleted', (data) => {
        const { isNoAd, adElement } = data;
        
        if (isNoAd) {
           // ❗️ Web SDK 광고 응답이 없을 경우 NAM 호출
           loadNAMAd();
           return;
        }
                    
        // 광고 게재 위치에 템플릿 등록             
        native.displayTemplate(adElement, 'native-ad-360x80');
      });

      // 광고 호출
      native.loadAd();
    });
  </script>
  
  <!-- NAM -->
  <script>
    const loadNAMAd = () => {
      const namDiv = document.getElementById('native-ad-360x80');

      namDiv.style.display = 'block';

      window.gladsdk = window.gladsdk || { cmd: [] };
      window.gladsdk.cmd.push(() => {
        const adSlotInfo = {
          adUnitId: '[AD_UNIT_ID]', // NAM에서 발급받은 adUnitId
          adSlotElementId: 'native-ad-360x80', // 배너 광고를 표시할 요소
        };

        window.gladsdk.defineAdSlot(adSlotInfo);
        window.gladsdk.displayAd('native-ad-360x80');
      });
    };
  </script>
</body>

NAM 광고 중복 제어 적용하기

페이지에 여러 개의 광고 슬롯이 있을 때 각각의 광고는 독립적으로 요청되기 때문에 동일한 광고가 노출될 수 있습니다. 동일한 광고를 제공하고 싶지 않을 때 중복 제어를 적용하여 중복된 광고를 제공하지 않을 수 있습니다. 참고 문서 NAM SDK > 광고 중복 제어

// e.g.노출하고자 하는 NAM 광고 영역이 4개일 때

<body>
    <!-- 광고 영역 -->
    <div id="division_1"></div>
    <div id="division_2"></div>
    <div id="division_3"></div>
    <div id="division_4"></div>
    
    <script>
      const loadWebSDKAd = () => {
        AdPopcornSSPWebSDK.cmd.push(() => {
          const native = AdPopcornSSPWebSDK.createNative({
            app_key: '[APP_KEY]',
            placement_id: '[PLACEMENT_ID]',
          });
  
          native.addEventListener('sdkError', (e) => {
            console.log('native sdkError event:', e);
          });
  
          native.addEventListener('adLoadCompleted', (e) => {
            console.log('native adLoadCompleted event:', e);
  
            if (e.isNoAd) {
              // Web SDK 광고 응답이 없을 경우 NAM 호출
              loadNAMAd();
            }
  
            // no ad가 아닌 경우 각 광고 영역 (division 1~4)에 해당하는 마크업 제작 후 추가
          });
  
          native.loadAd();
        });
      };
    </script>

    <script>
      const loadNAMAd = () => {
        const dedupReqId = 'deduplicationRequestId';
        const maxDedupReqCount = 3;
  
        window.gladsdk = window.gladsdk || { cmd: [] };
  
        window.gladsdk.cmd.push(() => {
          const adSlotInfo1 = {
            adUnitId: '[AD_UNIT_ID]', // NAM에서 발급받은 adUnitId 1
            adSlotElementId: 'division_1',
          };
  
          const adSlotInfo2 = {
            adUnitId: '[AD_UNIT_ID]', // NAM에서 발급받은 adUnitId 2 
            adSlotElementId: 'division_2',
          };
  
          const adSlotInfo3 = {
            adUnitId: '[AD_UNIT_ID]', // NAM에서 발급받은 adUnitId 3
            adSlotElementId: 'division_3',
          };
  
          const adSlotInfo4 = {
            adUnitId: '[AD_UNIT_ID]', // NAM에서 발급받은 adUnitId 4
            adSlotElementId: 'division_4',
          };
  
          const adSlot1 = window.gladsdk.defineAdSlot(adSlotInfo1);
          const adSlot2 = window.gladsdk.defineAdSlot(adSlotInfo2);
          const adSlot3 = window.gladsdk.defineAdSlot(adSlotInfo3);
          const adSlot4 = window.gladsdk.defineAdSlot(adSlotInfo4);
  
          const adDedupManager = window.gladsdk.setAdDeduplication(dedupReqId, maxDedupReqCount);
  
          adDedupManager.displayAds([adSlot1, adSlot2, adSlot3, adSlot4]);
        });
      }
    </script>
</body>

4. SDK 이벤트 처리

광고 노출 함수(display) / 광고 호출 함수(loadAd) 실행 전, 광고 인스턴스의 addEventListener함수를 등록하여 광고 이벤트를 감지하고 필요한 작업을 수행할 수 있습니다.

이벤트 정의

광고타입

이벤트 타입

이벤트 설명

이벤트 객체(e) 유,무

공통

sdkError

SDK 연동 실패 시 발생

전면/전면비디오/배너/리워드 비디오

adInventoryRendered

SDK 연동이 성공한 상황에서 광고 인벤토리 렌더링 실행 후 발생

전면/전면 비디오/ 리워드 비디오

adClosed

광고 인벤토리 닫기 클릭시 발생

전면/배너

adClicked

광고 인벤토리의 광고 클릭시 최초 1회 발생

전면 비디오/ 리워드 비디오

adClickthrough

user_landing_enabled가 false인 환경에서 광고 인벤토리 클릭시 발생

리워드 비디오

adPlaybackCompleted

리워드 비디오 광고 재생 완료시 발생

네이티브

adLoadCompleted

SDK 연동이 성공한 상황에서 네이티브 광고 API 호출 후 발생

이벤트 객체 속성 정의

속성 명

Type

필수

설명

code

string

이벤트 코드

message

string

이벤트 코드 설명

isNoAd

boolean

광고 요청 결과에 따른 광고 유,무

adData

string

네이티브 광고 호출 성공 시 전달되는 광고 데이터

adElement

Element

네이티브 템플릿 광고 호출 성공 시 전달되는 광고 엘리먼트

clickthroughURL

string

user_landing_enabled가 false인 환경에서 비디오형(전면 비디오/리워드 비디오) 광고 클릭 시, 랜딩될 주소

광고 데이터(adData) 객체 속성 정의

속성 명

Type

필수

설명

ctaText

string

광고 CTA(call to action) 버튼 텍스트

desc

string

광고 설명

iconImageURL

string

광고 아이콘 이미지

landingURL

string

광고 클릭시, 랜딩될 주소

mainImageURL

string

광고 메인 이미지(기본 사이즈: 1200x628)

privacyPolicyImageURL

string

개인 정보 아이콘 이미지 다운로드 주소

privacyPolicyURL

string

개인정보 아이콘 클릭시 랜딩될 주소

title

string

광고 타이틀

광고 데이터(adData) 예시

{
  ctaText: "Click",
  desc: "Adpopcorn SSP description sample",
  iconImageURL: "https://ap-ssp-be-static.s3.ap-northeast-1.amazonaws.com/test_campaign/80x80_icon.jpg",
  landingURL: "https://www.adpopcorn.com/",
  mainImageURL: "https://ap-ssp-be-static.s3.ap-northeast-1.amazonaws.com/test_campaign/1200x627.jpg",
  privacyPolicyImageURL: "https://ap-ssp-be-static.s3.ap-northeast-1.amazonaws.com/default_image/info-ico.png",
  privacyPolicyURL: "https://www.adpopcorn.com/policy/privacy",
  title: "Title sample"
};

HTML

<body>
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      const interstitial = AdPopcornSSPWebSDK.createInterstitial();

      // SDK 연동 실패
      interstitial.addEventListener("sdkError", (e) => {
        // SDK 연동 실패시, 이벤트 처리
      });

      // 광고 렌더링 결과
      interstitial.addEventListener("adInventoryRendered", (e) => {
        // 광고 렌더링 결과에 따른 이벤트 처리
      });

      // 광고 클릭
      interstitial.addEventListener("adClicked", () => {
        // 광고 클릭시, 이벤트 처리        
      });
      
      // 광고 닫기 클릭
      interstitial.addEventListener("adClosed", () => {
        // 광고 닫기 클릭시, 이벤트 처리        
      });
      
      interstitial.display("...");
    });
  </script>
</body>

HTML

<body>
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      const interstitialVideo = AdPopcornSSPWebSDK.createInterstitialVideo();

      // SDK 연동 실패
      interstitialVideo.addEventListener("sdkError", (e) => {
        // SDK 연동 실패시, 이벤트 처리
      });

      // 광고 렌더링 결과
      interstitialVideo.addEventListener("adInventoryRendered", (e) => {
        // 광고 렌더링 결과에 따른 이벤트 처리
      });
      
      // user_landing_enabled가 false인 환경에서 광고 클릭
      interstitialVideo.addEventListener("adClickthrough", (e) => {
        // 광고 클릭 후, 이벤트 처리
      });
      
      // 광고 닫기 클릭
      interstitialVideo.addEventListener("adClosed", () => {
        // 광고 닫기 클릭시, 이벤트 처리        
      });
      
      interstitialVideo.display("...");
    });
  </script>
</body>

<body>
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      const banner = AdPopcornSSPWebSDK.createBanner000x000();

      // SDK 연동 실패
      banner.addEventListener("sdkError", (e) => {
        // SDK 연동 실패시, 이벤트 처리
      });

      // 광고 렌더링 결과
      banner.addEventListener("adInventoryRendered", (e) => {
        // 광고 렌더링 결과에 따른 이벤트 처리
      });

      // 광고 클릭
      banner.addEventListener("adClicked", () => {
        // 광고 클릭시, 이벤트 처리        
      });
            
      banner.display("...");
    });
  </script>
</body>

<body>
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      const rewardVideo = AdPopcornSSPWebSDK.createRewardVideo();

      // SDK 연동 실패
      rewardVideo.addEventListener("sdkError", (e) => {
        // SDK 연동 실패시, 이벤트 처리
      });

      // 광고 렌더링 결과
      rewardVideo.addEventListener("adInventoryRendered", (e) => {
        // 광고 렌더링 결과에 따른 이벤트 처리
      });

      // 광고 재생 완료
      rewardVideo.addEventListener("adPlaybackCompleted", () => {
        // 광고 재생 완료시, 이벤트 처리        
      });
      
      // user_landing_enabled가 false인 환경에서 광고 클릭
      rewardVideo.addEventListener("adClickthrough", (e) => {
        // 광고 클릭 후, 이벤트 처리
      });
      
      // 광고 닫기 클릭
      rewardVideo.addEventListener("adClosed", () => {
        // 광고 닫기 클릭시, 이벤트 처리        
      });
      
      rewardVideo.display('...');
    });
  </script>
</body>

<body>
  <script>
    AdPopcornSSPWebSDK.cmd.push(() => {
      const native = AdPopcornSSPWebSDK.createNative();

      // SDK 연동 실패
      native.addEventListener("sdkError", (e) => {
        // SDK 연동 실패시, 이벤트 처리
      });

      
      // 광고 호출 결과
      native.addEventListener("adLoadCompleted", (e) => {
        // 광고 호출 결과에 따른 이벤트 처리
        if (e.isNoAd) {
          // 광고 응답이 없을 경우
        }
         
        // 이벤트 객체 내 adData로 네이티브 배너 구성
      });
      
      native.loadAd();
    });
  </script>
</body>

Previous보상형 광고 플러스 연동 Next하이브리드 앱- Web(Adfit)

Last updated 5 days ago

Was this helpful?