> For the complete documentation index, see [llms.txt](https://adpopcornssp.gitbook.io/ssp-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adpopcornssp.gitbook.io/ssp-sdk/sdk/web-sdk.md). # 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 %} {% 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 %}