애드팝콘 SSP SDK for Onestore

이 가이드는 애드팝콘 SSP Android SDK에서 원스토어 전용으로 사용되는 광고 타입 연동을 위한 가이드 문서입니다.

애드팝콘 SSP v3.0.12부터 지원하는 기능이므로, 연동 전 반드시 버전 확인을 부탁 드립니다.

1. SDK Grandle 설치

gradle을 이용하여 SDK 설정이 가능합니다.

프로젝트 수준 build.gradle 예시

allprojects {
    repositories {
        mavenCentral()
    }
}

앱 수준 build.gradle 예시

2. SDK 수동 다운로드 및 설치

위 Gradle 설정을 이용하지 않고 수동으로 SDK 다운로드 하고자 할 경우 아래 다운로드 링크를 통해 최신 안드로이드 SDK 패키지를 다운로드 합니다.

[애드팝콘 SSP SDK 다운로드]

다운로드 받은 .zip 파일을 압축해제하여 AdPopcornSSP~*.aar 파일을 안드로이드 스튜디오 프로젝트로 복사한 후 gradle 을 업데이트합니다.

SDK 복사 후 아래와 같이 build.gradle 에 dependiencies 를 추가하고 업데이트 합니다.

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile(name: 'AdPopcornSSP_3.0.13a', ext: 'aar')
    repositories { flatDir { dirs 'libs' } }
}

3. 매니페스트 설정

애드팝콘 SSP를 이용하기 위한 내용을 AndroidManifest.xml 파일에 추가합니다.

1) 앱 키 추가

애드팝콘 SSP 콘솔 페이지 앱 등록 후 발급받은 앱 키를 <application></application> 태그 안에 추가합니다.

XML

<application>
... 
<meta-data android:name="adpopcorn_ssp_app_key" android:value="이곳에_앱키를_입력하세요" /> 
...
</application>

2) 퍼미션 추가

<manifest></manifest> 태그 안에 필수 퍼미션을 추가합니다.

XML

<manifest>
... 
<uses-permission android:name="android.permission.INTERNET" /> 
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
...
</manifest>

4. 필수 연동

애드팝콘 SSP에서는 광고 타입 별 연동을 진행하기 전에 기본 API를 이용하여 초기화 작업을 해야 합니다.

1) SSP SDK 초기화

init API를 어플리케이션 실행 후 최초로 로드되는 activity 혹은 SSP 광고를 노출하고자 하는 activity에서 호출하여 SDK를 초기화합니다.

단, init 중복 호출 시, 그 사이에 세팅된 광고가 초기화 됨으로 중복 호출을 방지하고자 할 때에는 isInitialized API를 통해 초기화 작업이 완료된 상태인지 체크하시기 바랍니다.

JAVA

if(AdPopcornSSP.isInitialized(MyDisplayAdSampleActivity.this){
	// Already SSP SDK initialized
}
else{
	AdPopcornSSP.init(MyDisplayAdSampleActivity.this);
}

2) 리소스 해제

destroy API를 이용하여 어플리케이션이 종료될 때 메모리에 할당된 SSP 관련 리소스(View,Memory)를 해제합니다.

앱이 종료될 때 호출되는 activity의 onDestroy()에서 호출합니다.

JAVA

@Override
protected void onDestroy() {	
		// TODO Auto-generated method stub	
		super.onDestroy();	

		AdPopcornSSP.destroy();
}

3) 안드로이드 9.0 HTTP 통신 대응

Android P 부터 일반 텍스트 트래픽(암호화 되지 않은 HTTP)은 기본적으로 차단 됩니다.

SSP에서 취급하는 광고는 기본적으로 HTTPS를 사용하고 있으나 미디에이션 광고에서는 HTTPS 사용 여부를 확신할 수 없기 때문에 AndroidManifest.xml파일에 아래 설정을 추가 부탁 드립니다.

XML

<manifest> 
<application android:networkSecurityConfig="@xml/network_security_config"> 
     ... 
</application>
</manifest>

4) 네트워크 보안 구성 파일 추가

네트워크 보안 구성 기능은 res/xml/network_security_config.xml 파일에 아래 설정을 추가 부탁 드립니다.

XML

<?xml version="1.0" encoding="utf-8"?>
<network-security-config> <base-config cleartextTrafficPermitted="true" />
</network-security-config>

5. 원스토어 광고

원스토어 광고는 원스토어 커스텀 대응을 위해 생성한 광고 형식입니다.

1) 원스토어 광고 인스턴스 생성

JAVA

import com.igaworks.ssp.part.custom.OneStoreAd;
import com.igaworks.ssp.part.custom.listener.ICustomAdListener;
import com.igaworks.ssp.part.custom.listener.IOneStoreAdEventCallbackListener;

private OneStoreAd onestoreAd; 

@Override 
protected void onCreate(Bundle savedInstanceState) { 
      onestoreAd= new OneStoreAd (context);
}

2) Placement ID 설정

아래 코드를 추가하여 광고의 PLACEMENT ID 를 설정합니다.

JAVA

onestoreAd.setPlacementId("원스토어AD_PLACEMENT_ID");

3) BappList 설정

아래 코드를 추가하여 해당 광고 지면에서 block할 app List를 설정합니다.

JAVA

List<String> bappList = new ArrayList<String>();
bappList.add("com.test1");
bappList.add("com.test2");
oneStoreAd.setBAppList(bappList);

4) BcatList 설정

아래 코드를 추가하여 해당 광고 지면에서 block할 category List를 설정합니다.

JAVA

List<String> bcatList= new ArrayList<String>();
bcatList.add("IAB23");
bcatList.add("IAB25");
oneStoreAd.setBCatList(bcatList);

5) Tag ID 설정

아래 코드를 추가하여 해당 광고 지면의 tagId를 설정합니다.

Default 값은 placementId 입니다.

JAVA

// default : placementId
oneStoreAd.setTagId("testTag");

6) 광고 요청 개수(Plcmtcnt) 설정

아래 코드를 추가하여 해당 광고 지면에서 요청할 광고 수를 설정합니다.

Default 값은 20 입니다.

JAVA

oneStoreAd.setPlcmtcnt(10);

7) 이벤트 리스너

원스토어 광고 요청 후 발생하는 이벤트에 대한 리스너를 설정합니다. 제공되는 리스너와 구현 예시는 다음과 같습니다.

이벤트	설명	비고
OnLoadSuccess	광고 로딩 성공	광고 로딩 성공 시, 미리 협의한 대로, onestore의 AID 정보를 List 형태로 전달함.
OnLoadFailed	광고 로딩 실패	전달되는 에러코드는 아티클 하단의 테이블 참고

8) 광고 요청

원스토어 광고 노출을 원하는 시점에 loadAd() API 를 호출하여 서버에 광고를 요청합니다.

JAVA

oneStoreAd.loadAd();

9) 광고 노출 수집

광고 로딩 성공 후, 전달 받은 AID에 해당하는 광고가 노출될 경우, 각 광고마다 impression API를 호출하여, 노출이 정상적으로 집계 되도록 합니다.

JAVA

oneStoreAd.onImpression("노출된 AID");

10) 광고 클릭 수집

유저가 광고를 클릭 한 경우, 클릭된 광고의 AID에 대해 click API를 호출하여, 클릭이 정상적으로 집계 되도록 합니다.

JAVA

oneStoreAd.onClick("클릭된 AID");

11) 샘플 코드

JAVA

import com.igaworks.ssp.part.custom.OneStoreAd;
import com.igaworks.ssp.part.custom.listener.ICustomAdListener;
import com.igaworks.ssp.part.custom.listener.IOneStoreAdEventCallbackListener;

private OneStoreAd onestoreAd; 
private List<String> mOnestoreAIDList;

public class MainActivity extends Activity{
		@Override 
		protected void onCreate(Bundle savedInstanceState) { 			
			onestoreAd= new OneStoreAd (context);
				
			onestoreAd.setPlacementId("원스토어AD_PLACEMENT_ID");
		
			List<String> bappList = new ArrayList<String>();
       		        bappList.add("com.test1");
		        bappList.add("com.test2");
	                oneStoreAd.setBAppList(bappList);
		
		        List<String> bcatList = new ArrayList<String>();
		        bcatList.add("IAB23");
		        bcatList.add("IAB25");
		        oneStoreAd.setBCatList(bcatList);
		
		        oneStoreAd.setEventListener(new IOneStoreAdEventCallbackListener(){
		             @Override
		             public void OnLoadSuccess(List<String> onestoreAIDList) {
		                  Log.d("Sample", "OnLoadSuccess");
				  mOnestoreAIDList = onestoreAIDList;
		             }
		
		             @Override
		             public void OnLoadFailed(SSPErrorCode errorCode) {
		             Log.d("Sample", "OnLoadFailed");
		             }
		         });
				
		         oneStoreAd.loadAd();
				
				
		         // AID List의 0 번째 index의 광고가 클릭된 시점
		         oneStoreAd.onClick(mOnestoreAIDList.get(0));
		}
		
		private void impression(int index){
			 // AID List의 index 번째 광고가 노출된 시점
			 oneStoreAd.onImpression(mOnestoreAIDList.get(index));
		}
		
		
		private void click(int index){
			 // AID List의 index 번째 광고가 클릭된 시점
			 oneStoreAd.onClick(mOnestoreAIDList.get(index));
		}
}

6. 응답 에러 코드

Code	Message	설명
200	Exception	일반 SDK 에러
1000	Invalid Parameter	잘못된 파라미터
9999	Unknown Server Error	알려지지 않은 서버 에러
2000	Invalid App Key	잘못된 앱키
2030	Invalid Placement Id	잘못된 지면 키
2100	Empty Campaign	광고 없음
5001	Load Ad Failed	광고 로드 실패
5002	No Ad	광고 없음