광고 요청 정보
AdParam
AdParam 클래스는 광고 요청에 필요한 다양한 정보를 담은 객체로서 광고 요청에 반드시 필요한 Ad Unit ID를 비롯하여 광고 타겟팅을 위한 다양한 정보를 포함합니다.
AdParam.Builder를 통해 객체를 생성할 수 있고 생성 예시는 아래와 같습니다.
- Kotlin
- Java
val adParam = AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER") // 광고 Unit ID
.setCurrentPageUrl("https://www.naver.com") // 해당 페이지에 대한 설명 link
.setRefererPageUrl("https://www.naver.com") // referer 정보
.addCustomParam("channelId", "41312") // NAM Admin을 통한 타겟팅 설정 및 리포트 지원
.build()
AdParam adParam = new AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER") // 광고 Unit ID
.setCurrentPageUrl("https://www.naver.com") // 해당 페이지에 대한 설명 link
.setRefererPageUrl("https://www.naver.com") // referer 정보
.addCustomParam("channelId", "41312") // NAM Admin을 통한 타겟팅 설정 및 리포트 지원
.build();
AdParam.Builder의 주요 메서드
setAdUnitId()
Ad Unit ID를 설정합니다. 광고를 요청할 경우 반드시 설정해야 하는 필수값입니다.
- Kotlin
- Java
val adParam = AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER")
.build()
AdParam adParam = new AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER")
.build();
addCustomParam()
타겟팅 목적의 사용자 정의 매개변수를 추가합니다. key와 value 값은 NAM 관리자를 통해 확인 및 협의가 필요합니다.
- Kotlin
- Java
val adParam = AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER")
.addCustomParam("channelId", "41312")
.addCustomParam("category", "sports|news") // 여러 값은 | 기호로 구분
.build()
AdParam adParam = new AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER")
.addCustomParam("channelId", "41312")
.addCustomParam("category", "sports|news") // 여러 값은 | 기호로 구분
.build();
setCustomParam()
타겟팅 목적의 사용자 정의 매개변수를 설정합니다. 복수의 사용자 정의 매개변수를 추가할 때 사용할 수 있습니다.
- Kotlin
- Java
val customParams = mapOf(
"channelId" to "41312",
"category" to "sports",
"age" to "25"
)
val adParam = AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER")
.setCustomParam(customParams)
.build()
Map<String, String> customParams = new HashMap<>();
customParams.put("channelId", "41312");
customParams.put("category", "sports");
customParams.put("age", "25");
AdParam adParam = new AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER")
.setCustomParam(customParams)
.build();
setCurrentPageUrl()
타겟팅 목적의 현재 페이지 URL을 설정합니다.
- Kotlin
- Java
val adParam = AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER")
.setCurrentPageUrl("https://www.example.com/current-page")
.build()
AdParam adParam = new AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER")
.setCurrentPageUrl("https://www.example.com/current-page")
.build();
setRefererPageUrl()
타겟팅 목적의 참조 페이지 URL을 설정합니다.
- Kotlin
- Java
val adParam = AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER")
.setRefererPageUrl("https://www.example.com/referer-page")
.build()
AdParam adParam = new AdParam.Builder()
.setAdUnitId("AOS_TEST_BANNER")
.setRefererPageUrl("https://www.example.com/referer-page")
.build();
SDK의 전역 설정
광고 요청마다 설정하는 AdParam 외에, SDK 관련 설정인 SdkProperties와 타겟팅 등에 사용되는 사용자 관련 설정인 UserProperties를 통해 공통 설정을 할 수 있습니다.
SdkProperties
SDK의 전역 설정을 관리하는 오브젝트로서 광고 요청 타임아웃, 음소거 설정, 광고 공급자 옵션 등을 포함합니다.
SdkPropertiesBuilder를 통해 객체를 생성할 수 있고 생성 예시는 아래와 같습니다.
- Kotlin
- Java
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.addProviderOptions(DfpProviderOptions.Builder().setTestMode(false).build())
.addProviderOptions(FanProviderOptions.Builder().setTestMode(false).build())
.addProviderOptions(UnityProviderOptions.Builder().setTestMode(false).build())
.bannerAdRequestTimeout(60_000L)
.unifiedAdRequestTimeout(60_000L)
.videoAdRequestTimeout(60_000L)
.interstitialAdRequestTimeout(60_000L)
.rewardedAdRequestTimeout(60_000L)
.muteAudio(true)
.theme(ResolvedTheme.SYSTEM)
.build())
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.addProviderOptions(new DfpProviderOptions.Builder().setTestMode(false).build())
.addProviderOptions(new FanProviderOptions.Builder().setTestMode(false).build())
.addProviderOptions(new UnityProviderOptions.Builder().setTestMode(false).build())
.bannerAdRequestTimeout(60_000L)
.unifiedAdRequestTimeout(60_000L)
.videoAdRequestTimeout(60_000L)
.interstitialAdRequestTimeout(60_000L)
.rewardedAdRequestTimeout(60_000L)
.muteAudio(true)
.theme(ResolvedTheme.SYSTEM)
.build());
SdkPropertiesBuilder의 주요 메서드
addProviderOptions()
일부 광고 제공자의 경우, 광고 제공자별로 제공하는 별도의 기능 설정을 할 수 있습니다.
- Kotlin
- Java
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.addProviderOptions(DfpProviderOptions.Builder().setTestMode(false).build())
.addProviderOptions(FanProviderOptions.Builder().setTestMode(false).build())
.addProviderOptions(UnityProviderOptions.Builder().setTestMode(false).build())
.build()
)
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.addProviderOptions(new DfpProviderOptions.Builder().setTestMode(false).build())
.addProviderOptions(new FanProviderOptions.Builder().setTestMode(false).build())
.addProviderOptions(new UnityProviderOptions.Builder().setTestMode(false).build())
.build()
);
DfpProviderOptions, FanProviderOptions, UnityProviderOptions 는 TestMode 설정을 제공하며 해당 ProviderOptions 를 미설정할 경우에는 TestMode 의 기본값인 false 상태로 설정됩니다.
bannerAdRequestTimeout()
GfpBannerAdView를 통해 로드되는 배너 광고의 요청 타임아웃(밀리초 단위)을 설정합니다. 기본값은 60_000 밀리초입니다.
- Kotlin
- Java
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.bannerAdRequestTimeout(30_000L) // 30초로 설정
.build())
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.bannerAdRequestTimeout(30_000L) // 30초로 설정
.build());
unifiedAdRequestTimeout()
GfpAdLoader를 통해 로드되는 광고들의 요청 타임아웃(밀리초 단위)을 설정합니다. 기본값은 60_000 밀리초입니다.
- Kotlin
- Java
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.unifiedAdRequestTimeout(45_000L) // 45초로 설정
.build())
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.unifiedAdRequestTimeout(45_000L) // 45초로 설정
.build());
rewardedAdRequestTimeout()
GfpRewardedAdManager를 통해 로드되는 보상형 광고의 요청 타임아웃(밀리초 단위)을 설정합니다. 기본값은 60_000 밀리초입니다.
- Kotlin
- Java
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.rewardedAdRequestTimeout(90_000L) // 90초로 설정
.build())
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.rewardedAdRequestTimeout(90_000L) // 90초로 설정
.build());
interstitialAdRequestTimeout()
GfpInterstitialAdManager를 통해 로드되는 전면형 광고의 요청 타임아웃(밀리초 단위)을 설정합니다. 기본값은 60_000 밀리초입니다.
- Kotlin
- Java
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.interstitialAdRequestTimeout(75_000L) // 75초로 설정
.build())
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.interstitialAdRequestTimeout(75_000L) // 75초로 설정
.build());
muteAudio()
인스트림 동영상 광고를 제외한 S2S 및 일부 C2S 동영상 광고의 음소거 여부를 설정합니다. 기본값은 true입니다.
- Kotlin
- Java
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.muteAudio(false) // 음소거 해제
.build())
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.muteAudio(false) // 음소거 해제
.build());
theme()
특정 광고에서 적용되는 GfpTheme 값을 설정합니다. 기본값은 ResolvedTheme.LIGHT입니다.
- Kotlin
- Java
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.theme(ResolvedTheme.DARK) // 다크 테마 설정
.build())
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.theme(ResolvedTheme.DARK) // 다크 테마 설정
.build());
bufferDurationsMs()
인스트림 동영상 광고를 제외한 S2S 및 일부 C2S 동영상 광고의 버퍼링을 설정합니다.
- Kotlin
- Java
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.bufferDurationsMs(
BufferDurationsMs(
0, // 뒤로가기를 위한 버퍼 시간 (ms)
2000, // 재생 중 유지할 버퍼의 하한 (ms)
50000, // 재생 중 유지할 버퍼의 상한 (ms)
0, // 재생 시작을 위한 버퍼 시간 (ms)
2000 // 재버퍼링 이후 재개를 위한 버퍼 시간 (ms)
)
)
.build())
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
.bufferDurationsMs(
new BufferDurationsMs(
0, // 뒤로가기를 위한 버퍼 시간 (ms)
2000, // 재생 중 유지할 버퍼의 하한 (ms)
50000, // 재생 중 유지할 버퍼의 상한 (ms)
0, // 재생 시작을 위한 버퍼 시간 (ms)
2000 // 재버퍼링 이후 재개를 위한 버퍼 시간 (ms)
)
)
.build());
UserProperties
사용자 관련 정보를 관리하는 오브젝트로서 사용자의 성별, 출생년도, 국가, 언어, 사용자 ID 등을 포함합니다. 이 값들은 광고 요청 시 타겟팅을 위해 사용됩니다.
UserPropertiesBuilder를 통해 객체를 생성할 수 있고 생성 예시는 아래와 같습니다.
- Kotlin
- Java
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.yob(1987)
.country("KR")
.language("KO")
.gender(GenderType.MALE)
.addCustomParam("aaa", "bbb")
.setCustomParam(mapOf("k1" to "v1", "k2" to "v2"))
.setContentId("test content")
.build())
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.yob(1987)
.country("KR")
.language("KO")
.gender(GenderType.MALE)
.addCustomParam("foo", "bar")
.setContentId("test content")
.build());
UserPropertiesBuilder의 주요 메서드
gender()
사용자의 성별을 설정합니다. 기본값은 null입니다.
- Kotlin
- Java
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.gender(GenderType.MALE) // 또는 GenderType.FEMALE
.build())
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.gender(GenderType.MALE) // 또는 GenderType.FEMALE
.build());
yob()
사용자의 출생년도를 설정합니다. 기본값은 null입니다.
- Kotlin
- Java
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.yob(1990) // 출생년도 설정
.build())
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.yob(1990) // 출생년도 설정
.build());
country()
사용자의 국가를 설정합니다. 기본값은 null입니다. 필요시 DSP에 전달하기 위한 값으로, 대개 사용되지 않습니다.
- Kotlin
- Java
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.country("KR") // ISO 3166-1 alpha-2 코드
.build())
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.country("KR") // ISO 3166-1 alpha-2 코드
.build());
language()
사용자의 언어를 설정합니다. 기기에 설정된 언어값이 아닌 별도로 설정된 언어값을 사용합니다. 기본값은 null이며, ISO 639-1 코드 문자로 입력하십시오.
- Kotlin
- Java
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.language("KO") // ISO 639-1 코드
.build())
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.language("KO") // ISO 639-1 코드
.build());
id()
SDK 로그 추적을 위한 사용자 식별자를 설정합니다.
- Kotlin
- Java
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.id("user123456") // 사용자 식별자
.build())
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.id("user123456") // 사용자 식별자
.build());
addCustomParam() / setCustomParam()
전역적으로 사용되는 사용자 정의 매개변수 (from 6.0.0).
NAM SDK 6.0.0부터 추가된 UserProperties.customParameter는 전역적으로 사용되는 사용자 정의 매개변수로 광고 요청별로 사용되는 AdParam.customParameter와 병합될 수 있습니다.
- Kotlin
- Java
// 개별 매개변수 추가
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.addCustomParam("userLevel", "premium")
.addCustomParam("interests", "sports|music")
.build())
// 여러 매개변수 한번에 설정
val customParams = mapOf(
"userLevel" to "premium",
"interests" to "sports|music"
)
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.setCustomParam(customParams)
.build())
// 개별 매개변수 추가
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.addCustomParam("userLevel", "premium")
.addCustomParam("interests", "sports|music")
.build());
// 여러 매개변수 한번에 설정
Map<String, String> customParams = new HashMap<>();
customParams.put("userLevel", "premium");
customParams.put("interests", "sports|music");
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.setCustomParam(customParams)
.build());
childDirectedTreatment()
아동 온라인 개인정보 보호법(COPPA)에 따라 페이지 또는 앱이 아동 대상 서비스인지 나타냅니다. (from 6.1.0) 필요하지 않거나 알 수 없는 경우 설정하지 않아도 됩니다.
- Kotlin
- Java
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.childDirectedTreatment(true) // 아동 대상 서비스인 경우
.build())
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.childDirectedTreatment(true) // 아동 대상 서비스인 경우
.build());
underAgeOfConsent()
성인이 아닌 사용자에 대한 광고 요청 여부를 나타냅니다. (from 6.1.0) 필요하지 않거나 알 수 없는 경우 설정하지 않아도 됩니다.
- Kotlin
- Java
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.underAgeOfConsent(true) // 성인이 아닌 사용자인 경우
.build())
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.underAgeOfConsent(true) // 성인이 아닌 사용자인 경우
.build());
setContentId()
네아로 API에서 제공하는 Content ID를 설정합니다. (from 7.6.2) 필요시 NAM 담당자와 협의 후 사용하십시오.
- Kotlin
- Java
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.setContentId("YOUR_CONTENT_ID")
.build())
GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
.setContentId("YOUR_CONTENT_ID")
.build());
SdkProperties 및 UserProperties 리셋
NAM SDK 8.4.0 버전부터는 SdkProperties 및 UserProperties를 리셋하는 메서드가 추가되었습니다. 로그인한 사용자가 로그아웃하여 사용자 정보를 초기화하거나, SDK 관련 설정을 초기화해야 할 때는 아래와 같이 처리할 수 있습니다.
- Kotlin
- Java
GfpSdk.resetSdkProperties()
GfpSdk.resetUserProperties()
GfpSdk.resetSdkProperties();
GfpSdk.resetUserProperties();