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.4.0.min.js"
    ></script>
</head>

2. SDK 초기화 및 설정

SDK를 초기화하고 config를 설정해야 합니다. init함수를 호출하여 app_keyplacement_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 값을 필수로 전달해야 한다)

Android

android_opt_out_enabled

boolean

N

Android 광고 추적 거부 여부

true

iOS

ios_ifa_tracking_enabled

boolean

N

iOS 광고 추적 여부

false

공통

network

string

N

네트워크. wifi or mobile

""

공통

carrier

string

N

통신사

""

공통

model

string

N

모델명

""

공통

manufacturer

string

N

제조사

""

공통

os_version

string

N

플랫폼 OS 버전

""

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. 광고 연동

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

1) 광고 노출

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

인스턴스 생성 함수 정의

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

함수 명설명

createInterstitial

전면 광고 인스턴스 생성용

createInterstitialVideo

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

createBannerSize300x250

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

createBannerSize320x50

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

createBannerSize320x100

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

createRewardVideo

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

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

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

속성 명Type필수설명default

app_key

string

N

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

placement_id

string

N

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

display 함수 전달용 파라미터 속성 정의

속성 명Type필수설명default

id

string

N

광고 인벤토리를 구성할 요소의 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) 패스백 (구글 -> 애드팝콘)

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.4.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) 패스백 (애드팝콘 -> rCPC)

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.4.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;
      // iframe 클릭 중복 발생 방지용 dataset 설정
      iframeAdElement.dataset.clicked = "false";     
      
      // passback 광고 노출 위치 기본 스타일 설정
      Object.assign(bannerAd.style, {
        border: "none",
        width: "320px",
        height: "100px",
      });

      // ❗️발급받은 iframe rCPC 스크립트 uid의 query parameter 값으로 adid 또는 Idfa를 전달
      // ex) const bannerAdContent = `<iframe class="adpopcorn-ads" src="https://ssp.igaw.io/sdk/html/mediation.html?placementId=placementId&uid=${adidOrIdfa}" width="320px" height="100px" marginwidth="0" marginheight="0" frameborder="0" scrolling="no"></iframe>`
      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시 rCPC 패스백 광고 호출
        if (e.isNoAd) {
          const passbackBannerAdId = "rCPC-banner-ad-inventory-frame";
          setPassbackBannerAd(bannerAdInventoryFrameId, passbackBannerAdId);
        }
      });
      
      banner.addEventListener("adClicked", () => {
        // ❗️ 애드팝콘 배너 클릭 이벤트 처리 위치
        console.log("adpopcorn ad clicked");
      });

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

4. 광고 이벤트 처리

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

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

공통

sdkError

SDK 연동 실패 시 발생

e.code: number e.message: string e.isNoAd: true

공통

adInventoryRendered

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

e.code: number e.message: string e.isNoAd: boolean

전면, 배너

adClicked

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

-

리워드 비디오

adPlaybackCompleted

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

-

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

adClosed

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

-

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>

Last updated