애드팝콘 홈페이지
애드팝콘 SSP 콘솔 바로가기

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.9.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

Y

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

placement_id

string

Y

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

log_enabled

boolean

N

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

false

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

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

플랫폼
속성
Type
필수
설명
default

Android

adid

string

Y

Android 광고 식별자

iOS

idfa

string

Y

iOS 광고 식별자

iOS

idfv

string

N(Y)

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

공통

network

string

N

네트워크. wifi or mobile

""

공통

carrier

string

N

통신사

""

공통

model

string

N

모델명

""

공통

manufacturer

string

N

제조사

""

공통

os_version

string

N

플랫폼 OS 버전

"0"

공통

tag_for_child

0 | 1

N

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

0

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

N

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

공통

placement_id

string

N

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

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

user_landing_enabled

boolean

N

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

true

인스턴스 함수 정의

광고타입
함수 명
설명

공통

display

광고 요소를 화면에 표시

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

terminateAd

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

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

함수 명
속성 명
Type
필수
설명

display

id

string

Y

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

terminateAd

id

string

Y

광고 인벤토리가 구성된 요소의 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>

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.9.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>

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.9.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

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

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

속성 명
Type
필수
설명

app_key

string

N

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

placement_id

string

N

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

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

주의사항

네이티브 광고 로딩 성공 후 리포트 수집을 위해 아래 함수를 필수로 호출해야 합니다.

함수 명
설명

reportImpression

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

reportClick

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

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

      // 네이티브 광고 호출
      native.loadAd();
      
      // ❗️광고 호출 결과 광고가 있는 경우, 아래 함수를 시점에 맞춰 필수 호출
      // 광고 호출 결과 수신용 adLoadCompleted 이벤트 리스너 사용법은 연동 가이드의 4. 광고 이벤트 처리 참조
      const reportNativeAdImpression = () => {
        // 네이티브 광고 노출 시점에 호출
        native.reportImpression();
      };
      
      const reportNativeAdClick = () => {
        // 네이이브 광고 클릭 시점에 호출
        native.reportClick();
      }
    });
  </script>
</body>

4. SDK 이벤트 처리

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

이벤트 정의

광고타입
이벤트 타입
이벤트 설명
이벤트 객체(e) 유,무

공통

sdkError

SDK 연동 실패 시 발생

O

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

adInventoryRendered

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

O

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

adClosed

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

X

전면/배너

adClicked

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

X

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

adClickthrough

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

O

리워드 비디오

adPlaybackCompleted

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

X

네이티브

adLoadCompleted

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

O

이벤트 객체 속성 정의

속성 명
Type
필수
설명

code

string

Y

이벤트 코드

message

string

Y

이벤트 코드 설명

isNoAd

boolean

Y

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

adData

string

N

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

clickthroughURL

string

N

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

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

속성 명
Type
필수
설명

ctaText

string

Y

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

desc

string

Y

광고 설명

iconImageURL

string

Y

광고 아이콘 이미지

landingURL

string

Y

광고 클릭시, 랜딩될 주소

mainImageURL

string

Y

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

privacyPolicyImageURL

string

Y

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

privacyPolicyURL

string

Y

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

title

string

Y

광고 타이틀

광고 데이터(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>

Previous콘텐츠 광고Next테스트 코드

Last updated