# Web SDK ## 1. SDK 라이브러리 로드 연동이 필요한 페이지에 아래 SDK 스크립트를 추가합니다. {% code title="HTML" %} ```html ``` {% endcode %} ## 2. SDK 초기화 및 설정 SDK를 초기화하고 config를 설정해야 합니다. `init`함수를 호출하여 `app_key`와 `placement_id`를 설정하고, `setConfig`함수를 사용하여 Android 또는 iOS 플랫폼에 따라 해당 운영 체제에 맞는 config를 구성합니다. ### 1) init 함수 전달용 객체 속성 정의
속성Type필수설명default
app_keystringY매체용으로 발급 된 광고 앱 키
placement_idstringY매체용으로 발급 된 광고 지면 아이디
log_enabledbooleanNsdk 세부 로그 출력 유, 무(설정하지 않을 경우, 에러 레벨의 로그만 출력 됩니다.)false
### 2) setConfig 함수 전달용 객체 속성 정의 {% hint style="info" %} 광고 물량은 전달 가능한 파라미터 범위에 따라 달라질 수 있습니다. 가능한 범위 내 최대한 전달해주시길 바랍니다. {% endhint %} {% hint style="info" %} 플랫폼 기준 공통으로 적용하는 항목 외에는 각 OS에 맞게 전달해 주시기 바랍니다. {% endhint %}
플랫폼속성Type필수설명default
AndroidadidstringYAndroid 광고 식별자
iOSidfastringYiOS 광고 식별자
iOSidfvstringN(Y)벤더 식별자 (단, 광고 추적 미동의로 idfa를 전달할 수 없는 경우, idfv 값을 필수로 전달)
공통networkstringN네트워크(wifi or mobile)""
공통carrierstringN통신사""
공통modelstringN모델명""
공통manufacturerstringN제조사""
공통os_versionstringN플랫폼 OS 버전"0"
공통tag_for_child0 | 1N만 14세 미만 연령 제한 플래그 (기본값: 비활성화, 활성화 시 광고 미송출)0
{% code title="HTML" %} ```html ``` {% endcode %} ## 3-1. 광고 연동 (기본) 광고를 노출할 `div` 요소에 `id` attribute를 포함하여 HTML에 추가합니다. 설정한 `id`를 `display` 함수 인자로 전달하면 해당 요소에 광고가 삽입되어 노출됩니다. 실행 스크립트는 `` 요소의 하단에 삽입하는 것을 권장합니다. ### 1) 적용 방식 아래 코드는 광고를 표시할 요소(광고 인벤토리 영역)와 실행 코드를 포함하고 있습니다. SDK에서 제공하는 인스턴스 생성 함수를 사용하여 광고 타입별 인스턴스를 생성하고, `display` 함수를 사용하여 광고를 표시합니다. #### 인스턴스 생성 함수 정의 {% hint style="danger" %} iOS 전면 비디오 또는 리워드 비디오 사용 시 **전체 화면 노출 방지**를 위해 아래 주의 사항을 참고해주시기 바랍니다.\ \ \- Web SDK v1.11.0 버전 이상 적용\ \- 앱 내 다음 코드 추가 (rel. [Apple Developer Guide](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/allowsinlinemediaplayback))\ `configuration.allowsInlineMediaPlayback = true` {% endhint %} {% hint style="info" %} 앱키, 지면 아이디를 인스턴스에 전달하면 SDK init 설정과 별개로 인스턴스 개별 설정을 사용할 수 있습니다. {% endhint %}
함수 명설명
createInterstitial전면 광고 인스턴스 생성용
createInterstitialVideo전면 비디오 광고 인스턴스 생성용
createBannerSize300x250배너 광고 인스턴스 생성용(사이즈: 300x250)
createBannerSize320x50배너 광고 인스턴스 생성용(사이즈: 320x50)
createBannerSize320x100배너 광고 인스턴스 생성용(사이즈: 320x100)
createRewardVideo리워드 비디오 광고 인스턴스 생성용
#### 인스턴스 생성 함수(create-) 전달용 객체 속성 정의
광고타입속성 명Type필수설명defaultdefault
공통app_keystringN매체용으로 발급된 광고 앱 키
공통placement_idstringN매체용으로 발급된 광고 지면 아이디
전면 비디오/ 리워드 비디오user_landing_enabledbooleanN광고 클릭 시, 랜딩 페이지로 이동 허용 여부true
#### 인스턴스 함수 정의
광고타입함수 명설명
공통display광고 요소를 화면에 표시
전면 비디오/ 리워드 비디오terminateAd구성된 광고 요소의 재생 중단 및 즉시 종료
#### 인스턴스 함수 전달용 파라미터 속성 정의
함수 명속성 명Type필수설명default
displayidstringY광고 인벤토리를 구성할 요소의 id 속성명
terminateAdidstringY광고 인벤토리가 구성된 요소의 id 속성명
{% tabs %} {% tab title="배너" %} {% code title="HTML" %} ```html ``` {% endcode %} {% endtab %} {% tab title="전면" %} {% code title="HTML" %} ```html
``` {% endcode %} {% endtab %} {% tab title="전면 비디오" %} {% code title="HTML" %} ```html
``` {% endcode %} {% endtab %} {% tab title="리워드 비디오" %} **\[ setUserId 함수 전달용 파라미터 속성 정의 ]** {% hint style="warning" %} **주의사항** 1. 1명의 유저는 1개의 고유한 유저식별값을 가져야하며, 가변적인 값을 사용해서는 안됩니다. 2. 개인정보(이메일, 이름, 전화번호, 식별가능한 유저아이디 등)이 포함되어서는 안됩니다. 3. 비디오 광고 노출 함수 실행 전에 설정되어야 합니다. {% endhint %} {% hint style="info" %} CS 처리 기능을 위해 유저식별값(userId)을 필수로 설정해주세요. {% endhint %}
속성명Type필수
userIdstringY리워드 비디오 시청 완료 시 완료 유저를 식별하기 위해 사용되는 값
{% code title="HTML" %} ```html
``` {% endcode %} {% endtab %} {% endtabs %} ### 2) 패스백 (구글 -> Web SDK) {% tabs %} {% tab title="배너" %} {% code title="HTML" %} ```html
``` {% endcode %} {% endtab %} {% tab title="전면" %} {% code title="HTML" %} ```html
``` {% endcode %} {% endtab %} {% tab title="전면 비디오" %} {% code title="HTML" %} ```html
``` {% endcode %} {% endtab %} {% tab title="리워드 비디오" %} {% code title="HTML" %} ```html
``` {% endcode %} {% endtab %} {% endtabs %} ### 3) 패스백 (Web SDK → Reward Banner) {% tabs %} {% tab title="배너" %} {% code title="HTML" %} ```html
``` {% endcode %} {% endtab %} {% tab title="전면" %} {% code title="HTML" %} ```html ``` {% endcode %} {% endtab %} {% tab title="전면 비디오" %} {% code title="HTML" %} ``` ``` {% endcode %} {% endtab %} {% tab title="리워드 비디오" %} {% code title="HTML" %} ```html ``` {% endcode %} {% endtab %} {% endtabs %} ## 3-2. 광고 연동 (네이티브) 사용자가 커스텀하게 광고를 구성할 수 있도록 광고 데이터를 제공합니다. 실행 스크립트는 요소의 하단에 삽입하는 것을 권장합니다. ### 1) 적용 방식 아래 코드는 광고를 호출하는 실행 코드를 포함하고 있습니다. SDK에서 제공하는 Native 인스턴스 생성 함수를 사용하여 인스턴스를 생성하고, `loadAd` 함수를 실행하여 광고를 호출합니다. {% hint style="warning" %} **주의사항** loadAd 호출에 대한 결과 광고 수신에 실패한 경우, loadAd를 재호출하면 안됩니다. 과도한 광고 호출 요청은 Block 사유가 됩니다. {% endhint %} #### 인스턴스 생성 함수 정의
함수 명설명
createNative네이티브 광고 인스턴스 생성용
createNativeTemplate네이티브 템플릿 광고 인스턴스 생성용
#### 인스턴스 생성 함수 전달용 객체 속성 정의
속성 명Type필수설명default
app_keystringN매체용으로 발급된 광고 앱 키
placement_idstringN매체용으로 발급된 광고 지면 아이디
#### 네이티브 인스턴스 함수 정의 {% hint style="warning" %} **주의사항** 네이티브 광고 로딩 성공 후 리포트 수집을 위해 아래 함수를 필수로 호출해야 합니다. \ 단, 네이티브 템플릿은 \[ 1) 광고 호출 ] 의 reportImpression, reportClick을 내장하고 있어 별도 호출이 필요하지 않습니다. {% endhint %}
함수 명설명
reportImpression광고 로딩에 성공 후, 광고 데이터를 화면에 노출한 경우에 광고 노출 측정
reportClick구성한 네이티브 광고를 클릭한 경우에 클릭 측정
{% tabs %} {% tab title="네이티브" %} ```html
``` {% endtab %} {% tab title="네이티브 템플릿" %} ```html
``` {% endtab %} {% endtabs %} ### 2) 패스백 (Web SDK → NAM) {% tabs %} {% tab title="네이티브" %} 
<head>
  <!-- 스크립트 추가 -->
  <!-- Web SDK -->
  <script
      async
      src="https://webapi.adpopcorn.com/ssp/web-sdk/ap-ssp-web-sdk-1.14.1.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', // 배너 광고를 표시할 요소
        };

        // Case 1. 기본 적용
        window.gladsdk.defineAdSlot(adSlotInfo);
        window.gladsdk.displayAd('native-ad-inventory-frame');
        
        -----------------------------
        
        // Case 2. 커스텀 핸들러 적용
        // ref. https://naver.github.io/nam-sdk-guide/web/advanced/click_handler/
        const adSlot = window.gladsdk.defineAdSlot(adSlotInfo);
        
        adSlot.setClickHandler(function (curl, furl, extra) {
          console.debug('curl', curl, 'furl', furl, 'ext', ext, 'type', ext.type);
        });
        
        window.gladsdk.displayAd('native-ad-inventory-frame');
        });
    };
  </script>
</body>
{% endtab %} {% tab title="네이티브 템플릿" %} ```html
``` {% endtab %} {% endtabs %}
NAM 광고 중복 제어 적용하기 페이지에 여러 개의 광고 슬롯이 있을 때 각각의 광고는 독립적으로 요청되기 때문에 동일한 광고가 노출될 수 있습니다. 동일한 광고를 제공하고 싶지 않을 때 중복 제어를 적용하여 중복된 광고를 제공하지 않을 수 있습니다.\ \ **참고 문서**\ [NAM SDK > 광고 중복 제어](https://naver.github.io/nam-sdk-guide/web/advanced/deduplication/) ```html // e.g.노출하고자 하는 NAM 광고 영역이 4개일 때
```
## 4. SDK 이벤트 처리 광고 노출 함수(display) / 광고 호출 함수(loadAd) 실행 전, 광고 인스턴스의 `addEventListener`함수를 등록하여 광고 이벤트를 감지하고 필요한 작업을 수행할 수 있습니다. #### 이벤트 정의
광고타입이벤트 타입이벤트 설명이벤트 객체(e) 유,무
공통sdkErrorSDK 연동 실패 시 발생O
전면/전면비디오/배너/리워드 비디오adInventoryRenderedSDK 연동이 성공한 상황에서 광고 인벤토리 렌더링 실행 후 발생O
전면/전면 비디오/ 리워드 비디오adClosed광고 인벤토리 닫기 클릭시 발생X
전면/배너adClicked광고 인벤토리의 광고 클릭시 최초 1회 발생X
전면 비디오/ 리워드 비디오adClickthroughuser_landing_enabled가 false인 환경에서 광고 인벤토리 클릭시 발생O
리워드 비디오adPlaybackCompleted리워드 비디오 광고 재생 완료시 발생X
네이티브adLoadCompletedSDK 연동이 성공한 상황에서 네이티브 광고 API 호출 후 발생O
#### 이벤트 객체 속성 정의
속성 명Type필수설명default
codestringY이벤트 코드
messagestringY이벤트 코드 설명
isNoAdbooleanY광고 요청 결과에 따른 광고 유,무
adDatastringN네이티브 광고 호출 성공 시 전달되는 광고 데이터
adElementElementN네이티브 템플릿 광고 호출 성공 시 전달되는 광고 엘리먼트
clickthroughURLstringNuser_landing_enabled가 false인 환경에서 비디오형(전면 비디오/리워드 비디오) 광고 클릭 시, 랜딩될 주소
#### 광고 데이터(adData) 객체 속성 정의
속성 명Type필수설명default
ctaTextstringY광고 CTA(call to action) 버튼 텍스트
descstringY광고 설명
iconImageURLstringY광고 아이콘 이미지
landingURLstringY광고 클릭시, 랜딩될 주소
mainImageURLstringY광고 메인 이미지(기본 사이즈: 1200x628)
privacyPolicyImageURLstringY개인 정보 아이콘 이미지 다운로드 주소
privacyPolicyURLstringY개인정보 아이콘 클릭시 랜딩될 주소
titlestringY광고 타이틀
#### 광고 데이터(adData) 예시 ```javascript { 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" }; ``` {% tabs %} {% tab title="전면" %} {% code title="HTML" %} ```html ``` {% endcode %} {% endtab %} {% tab title="전면 비디오" %} 
<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>
{% endtab %} {% tab title="배너" %} ```html ``` {% endtab %} {% tab title="리워드 비디오" %} ```html ``` {% endtab %} {% tab title="네이티브" %} ```html ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://adpopcornssp.gitbook.io/ssp-sdk/sdk/web-sdk.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.