WebPage Side 연동

Android, iOS SDK 를 탑재하지 않을 경우 애드팝콘 광고는 노출되지 않습니다.

SPA (Single Page Application) 를 지원하지 않습니다.

1. Web SDK 라이브러리 로드

HTML 문서에 다음을 추가하여 라이브러리를 로드합니다

HTML

<head>
	<!-- v1.0.10 -->
	<script async src="https://ssp.igaw.io/sdk/apsspads.js"></script>
</head>

이 코드는 https://ssp.igaw.io/sdk/apsspads.js에서 라이브러리를 로드합니다. 라이브러리가 완전히 로드되면 apsspads 객체의 대기 중인 명령어를 처리합니다.

SDK는 페이지 로드 시 최초 1회 만 로드 되어야 합니다.

SRI(Subresource Integrity)를 통한 스크립트변조 여부 식별(Optional)

HTML

<head>
	<!-- integrity, crossorigin 값을 설정하지 않아도 정상 동작합니다. -->
	<!-- SDK 업데이트 시 integrity 값이 변경될 수 있습니다. -->
	<script async src="https://ssp.igaw.io/sdk/apsspads.js" integrity="sha256-7l6hFHFBsgz1ss6zuztfDlFAimT3Wou4oWydmEPJxfI=" crossorigin="anonymous"></script>
</head>

하위 자원 무결성 확인을 위한 SRI(Subresource Integrity)를 통해 스크립트가 변조 되었는지 여부를 식별할 수 있습니다.

변조 됐을 경우 브라우저가 오류 메세지와 함께 Web SDK가 차단됩니다.

(integrity 값을 넣지 않아도 스크립트는 정상 동작하고, SDK 업데이트 시 integrity 값이 변경될 수 있습니다.)

※ Web SDK 경우 latest 버전으로 제공하고 있으며 업데이트 시 integrity 값이 변경되기에, 꼭 적용해야 할 경우 SDK를 다운 받아 사용할 수 있습니다.

2. 광고 슬롯 정의

apsspads.setConfig, apsspads.defineAdUnits 메서드를 사용하여 광고 슬롯을 정의하고 객체를 초기화합니다.

HTML

<head>
	<script async src="https://ssp.igaw.io/sdk/apsspads.js"></script>
	<script>
		window.apsspads = window.apsspads || { cmd: [] }; 
		apsspads.cmd.push(function() {
			apsspads.setConfig({ pubId: "TEST_APP_KEY" }); // 애드팝콘 앱키
			apsspads.defineAdUnits({
				code: "div-1",  // 광고 노출 영역 (HTML Element)의 Id (광고 게재 위치 지정 참고)
				plcmtId: "TEST_BANNER_PLACEMENT_ID",  // 애드팝콘 지면 Id
				size: [300, 250]  // 크기 (네이티브 광고일 경우 정의하지 않습니다)
			});
			apsspads.requestBids(); // 광고 요청
		});
	</script>
</head>

이 코드는 먼저 apsspads 객체를 사용하여광고 슬롯을 구성하고 명령을 대기열에 추가합니다. 이때 사용되는 API는 apsspads의 명령어 대기열 (apsspads.cmd)에 추가된 함수 내에서 사용되어야 합니다.

이 예의 광고 슬롯은 TEST_BANNER_PLACEMENT_ID 지면에 300x250 크기의 광고를 로드합니다. 광고는 페이지 본문에 있는 <div id="div-1"> 요소에 표시되며 다음에 추가됩니다.

TEST_PLACEMENT_ID는 임의로 지정된 지면 Id 입니다. 실제 적용 시에는 관리자를 통해 발급 받은 지면 Id를 설정해야 합니다.

네이티브 광고 슬롯의 경우 size 속성을 정의하지 않습니다.

현재 size 는 NAM 과의 호환성 문제로 인해 [300,250] 만 사용 가능합니다.

광고 슬롯이 여러 개 인 경우

동일한 code, plcmtId 여러 번 사용할 수 없습니다.

<head>
	<script async src="https://ssp.igaw.io/sdk/apsspads.js"></script>
	<script>
		windows.apsspads = window.apsspads || { cmd: [] };
		apsspads.cmd.push(function() {
			apsspads.setConfig({ pubId: "TEST_APP_KEY" }); // 앱키
			apsspads.defineAdUnits([
				{
					code: "div-1",// 광고 노출 영역 (HTML Element)의 Id (광고 게재 위치 지정 참고)
					plcmtId: "TEST_BANNER_PLACEMENT_ID",// 지면 Id
					size: [300, 250] // 크기 (네이티브 광고일 경우 정의하지 않습니다)
				},
				{
					code: "div-2",// 광고 노출 영역 (HTML Element)의 Id
					plcmtId: "TEST_NATIVE_PLACEMENT_ID",// 지면 Id
				}
			]);
			apsspads.requestBids(); // 광고 요청
		});
	</script>
</head>

3. 광고 게재 위치 지정

HTML 문서의 <body></body>에 다음 코드를 추가하여 광고가 게재되는 위치를 지정합니다.

id는 광고 슬롯을 생성할 때 정의한 code 값과 동일해야 합니다.

광고 슬롯이 여러 개 일 경우 DIV Element 의 id는 중복되지 않도록 해야 합니다.

HTML

<body>
    <div id="div-1"></div> <!-- 예제, 변경가능 -->
</body>

4. NAM(Naver Ad Manager) 패스백 설정

apsspads.setConfig 메서드에 nam을 사용 여부를 정의합니다.

HTML

<head>
	<script async src="https://ssp.igaw.io/sdk/apsspads.js"></script>
	<script>
		window.apsspads = window.apsspads || { cmd: [] };
		apsspads.cmd.push(function() {
			apsspads.setConfig({ 
				pubId: "TEST_APP_KEY" // 애드팝콘 앱키, 
				nam: true // *** NAM 패스백 사용 ***
			});
			apsspads.defineAdUnits({
				code: "div-1",  // 광고 노출 영역 (HTML Element)의 Id
				plcmtId: "TEST_BANNER_PLACEMENT_ID",  // 애드팝콘 지면 Id
				size: [300, 250],  // 크기 (네이티브 광고일 경우 정의하지 않습니다)
				fallback: {
					nam: {
						adUnitId: "WEB_nw_??????????"  // NAM 광고 유닛 ID
					}
				}
				// 또는 fallback: { nam: "WEB_nw_??????????" }
			});
			apsspads.requestBids(); // 광고 요청
		});
	</script>
</head>

NAM 광고 중복 제어 적용하기

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

<head>
	<script async src="https://ssp.igaw.io/sdk/apsspads.js"></script>
	<script>
		window.apsspads = window.apsspads || { cmd: [] };
		apsspads.cmd.push(function() {
			apsspads.setConfig({ 
				pubId: "TEST_APP_KEY" /* 애드팝콘 앱키 */, 
				nam: true /* NAM 패스백 사용 */,
				namAdDedup: true /* NAM 광고 중복 제어 적용 */
			});
			apsspads.defineAdUnits([
						{
							code: "div-1",  // 광고 노출 영역 (HTML Element)의 Id
							plcmtId: "TEST_BANNER_PLACEMENT_ID",  // 애드팝콘 지면 Id
							size: [300, 250],  // 크기 (네이티브 광고일 경우 정의하지 않습니다)
							fallback: {
								nam: {
									adUnitId: "WEB_nw_??????????"  // NAM 광고 유닛 ID
								}
							}
							// 또는 fallback: { nam: "WEB_nw_??????????" }
						},
						{
							code: "div-2",  // 광고 노출 영역 (HTML Element)의 Id
							plcmtId: "TEST_BANNER_PLACEMENT_ID_2",  // 애드팝콘 지면 Id
							size: [300, 250],  // 크기 (네이티브 광고일 경우 정의하지 않습니다)
							fallback: {
								nam: {
									adUnitId: "WEB_nw_??????????"  // NAM 광고 유닛 ID
								}
							}
							// 또는 fallback: { nam: "WEB_nw_??????????" }
						}
				]);
				apsspads.requestBids(); // 광고 요청
		});
	</script>
</head>

5. 광고 클릭 커스텀

광고 클릭 시 링크 새창 활성이 불가능할 경우 핸들러를 설정할 수 있습니다.

클릭 핸들러 실행 시 광고의 기본 랜딩은 동작하지 않습니다. (콜백 함수 내에 랜딩 로직 구현이 필요합니다.)

애드팝콘, NAM에 동일하게 적용되며, 일부 DSP의 광고는 클릭 핸들러가 동작하지 않을 수 있습니다.

HTML

<head>
	<script async src="https://ssp.igaw.io/sdk/apsspads.js"></script>
	<script>
		window.apsspads = window.apsspads || { cmd: [] };
		apsspads.cmd.push(function() {
			apsspads.setConfig({ 
				pubId: "TEST_APP_KEY", // 애드팝콘 앱키
			});
			apsspads.defineAdUnits({
				code: "div-1",  // 광고 노출 영역 (HTML Element)의 Id
				plcmtId: "TEST_BANNER_PLACEMENT_ID",  // 애드팝콘 지면 Id
				size: [300, 250]  // 크기 (네이티브 광고일 경우 정의하지 않습니다, NAM 광고 크기 X)
			});
			apsspads.setClickHandler(function(code, curl) { // 광고 클릭 시 실행
				// code: 광고 노출 영역 (HTML Element)의 Id
				// curl: 클릭 URL
				console.log(code, curl);
			});
			apsspads.requestBids(); // 광고 요청
		});
	</script>
</head>

6. 패스백 커스텀

애드팝콘 또는 NAM 광고가 광고 슬롯 등록 실패, NO AD, 타임아웃 등의 이유로 노출되지 않을 때 호출할 패스백을 설정할 수 있습니다. (콜백 함수 내에 패스백 로직 구현이 필요합니다.)

stat: 2 에러코드는 no ad (광고 없음)을 뜻합니다.

HTML

<head>
	<script async src="https://ssp.igaw.io/sdk/apsspads.js"></script>
	<script>
		window.apsspads = window.apsspads || { cmd: [] };
		apsspads.cmd.push(function() {
			apsspads.setConfig({ 
				pubId: "TEST_APP_KEY", // 애드팝콘 앱키
			});
			apsspads.defineAdUnits({
				code: "div-1",  // 광고 노출 영역 (HTML Element)의 Id
				plcmtId: "TEST_BANNER_PLACEMENT_ID",  // 애드팝콘 지면 Id
				size: [300, 250]  // 크기 (네이티브 광고일 경우 정의하지 않습니다, NAM 광고 크기 X)
			});
			apsspads.addEventListener("error", function(obj) { // 광고 미 노출 시 호출
				// providerName: 광고 미 노출 공급자명
				// code: 광고 노출 영역 (HTML Element)의 Id
				// stat: 에러 코드 (0: error (invalid ad unit id, ...), 2: no ad, 3: timeout)
				console.log(obj); // {providerName: "apssp|nam", code: "div-1", stat: 2}
			});
			apsspads.requestBids(); // 광고 요청
		});
	</script>
</head>

7. 광고 이벤트 리스너 추가/삭제

apsspads.addEventListener(), apsspads.removeEventListener()를 사용하여 광고 슬롯 렌더링 중에 발생하는 이벤트에 대해 이벤트 리스너를 추가/삭제할 수 있습니다.

이벤트 명

이벤트

설명

loaded

광고 로드

광고 슬롯에 광고 로드 시 발생

impressed

광고 노출

광고 슬롯에 렌더링된 소재 노출 기준 만족 시 발생

clicked

광고 클릭

광고 슬롯에 렌더링된 소재 클릭 시 발생

error

에러

광고 로드 실패 또는 실행 에러 시 발생

HTML

<!-- 광고 로드 시 화면에 출력 -->

<head>
	<script async src="https://ssp.igaw.io/sdk/apsspads.js"></script>
	<script>
		window.apsspads = window.apsspads || { cmd: [] };
		apsspads.cmd.push(function() {
			apsspads.setConfig({ 
				pubId: "TEST_APP_KEY", // 애드팝콘 앱키
			});
			apsspads.defineAdUnits({
				code: "div-1",  // 광고 노출 영역 (HTML Element)의 Id
				plcmtId: "TEST_BANNER_PLACEMENT_ID",  // 애드팝콘 지면 Id
				size: [300, 250]  // 크기 (네이티브 광고일 경우 정의하지 않습니다, NAM 광고 크기 X)
			});
			apsspads.addEventListener("loaded", function(obj) { // 광고 슬롯에 광고 로드시 호출
				// providerName: 공급자명
				// code: 광고 노출 영역 (HTML Element)의 Id
				// console.log(obj); // {providerName: "apssp|nam", code: "div-1"}

				// 아래 코드는 광고 노출 전 영역을 숨겼다가 광고가 로드되면 화면에 보이는 예제로 필요하지 않을 경우 적용하지 않아도 됩니다.
				var el = document.querySelector(`#{obj.code}`);
				if (el) {
					el.style.display = "block";
				}
			});
			apsspads.requestBids(); // 광고 요청
		});
	</script>
</head>
<body>
	<div id="div-1" style="display:none"></div>
</body>

8. 배경색 변경

네이티브 광고의 배경색을 변경할 수 있습니다. (기본값 #F8F8F8)

HTML

<head>
	<script async src="https://ssp.igaw.io/sdk/apsspads.js"></script>
	<script>
		window.apsspads = window.apsspads || { cmd: [] };
		apsspads.cmd.push(function() {
			apsspads.setConfig({ 
				pubId: "TEST_APP_KEY", // 애드팝콘 앱키,
				backgroundColor: "#F3F3F3", // 배경색 (기본값: #F8F8F8)
			});
			apsspads.defineAdUnits({
				code: "div-1",  // 광고 노출 영역 (HTML Element)의 Id
				plcmtId: "TEST_BANNER_PLACEMENT_ID",  // 애드팝콘 지면 Id
				size: [300, 250]  // 크기 (네이티브 광고일 경우 정의하지 않습니다, NAM 광고 크기 X)
			});
			apsspads.requestBids(); // 광고 요청
		});
	</script>
</head>

9. 테두리/인포마크 제거

HTML

<head>
	<script async src="https://ssp.igaw.io/sdk/apsspads.js"></script>
	<script>
		window.apsspads = window.apsspads || { cmd: [] };
		apsspads.cmd.push(function() {
			apsspads.setConfig({ 
				pubId: "TEST_APP_KEY", // 애드팝콘 앱키,
				noBorder: true, // 테두리 제거
				noPrivacy: true, // 인포마크 제거
			});
			apsspads.defineAdUnits({
				code: "div-1",  // 광고 노출 영역 (HTML Element)의 Id
				plcmtId: "TEST_BANNER_PLACEMENT_ID",  // 애드팝콘 지면 Id
				size: [300, 250]  // 크기 (네이티브 광고일 경우 정의하지 않습니다, NAM 광고 크기 X)
			});
			apsspads.requestBids(); // 광고 요청
		});
	</script>
</head>

10. 광고 영역 라운드 처리

광고 영역에 border-radius, overflow 를 적용합니다.

iOS 에서 Stacking context 이슈로 라운드 처리가 동작하지 않을 경우: z-index: 0 또는 isolation: isolate 또는 -webkit-mask-image: -webkit-radial-gradient(white, black) 를 적용합니다.

HTML

<div id="div-1" style="overflow:hidden;border-radius:3px"></div>

11. 기타

애드팝콘 WEB SDK가 로드되어 호출할 준비가 되었는지 확인할 수 있습니다.

JavaScript

if (window.apsspads && apsspads.isReady) {
	// 애드팝콘 SDK 로드 완료
}

JavaScript

apsspads.version; // 1.0.10

카카오 간편로그인 사용으로 인해 userAgent의 wv 값을 제거해야 할 경우, 웹뷰 여부를 확인할 수 없기 때문에 애드팝콘 광고를 노출하지 않습니다. 아래와 같이 설정할 경우 웹뷰 확인 단계를 건너뛸 수 있습니다.

JavaScript

window.apsspads_wv = false; // 웹뷰 확인 안함
window.apsspads = window.apsspads || { cmd: [] };

Previous네이티브 Side 연동(iOS)Next광고 ID 수동 세팅

Last updated 2 months ago