본문으로 건너뛰기

광고 요청 정보

AdParam​

AdParam 클래스는 광고 요청에 필요한 다양한 정보를 담은 객체로서 광고 요청에 반드시 필요한 Ad Unit ID를 비롯하여 광고 타겟팅을 위한 다양한 정보를 포함합니다.

AdParam.Builder를 통해 객체를 생성할 수 있고 생성 예시는 아래와 같습니다.

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.Builder의 주요 메서드​

setAdUnitId()​

Ad Unit ID를 설정합니다. 광고를 요청할 경우 반드시 설정해야 하는 필수값입니다.

val adParam = AdParam.Builder()
    .setAdUnitId("AOS_TEST_BANNER")
    .build()

addCustomParam()​

타겟팅 목적의 사용자 정의 매개변수를 추가합니다. key와 value 값은 NAM 관리자를 통해 확인 및 협의가 필요합니다.

val adParam = AdParam.Builder()
    .setAdUnitId("AOS_TEST_BANNER")
    .addCustomParam("channelId", "41312")
    .addCustomParam("category", "sports|news") // 여러 값은 | 기호로 구분
    .build()

setCustomParam()​

타겟팅 목적의 사용자 정의 매개변수를 설정합니다. 복수의 사용자 정의 매개변수를 추가할 때 사용할 수 있습니다.

val customParams = mapOf(
    "channelId" to "41312",
    "category" to "sports",
    "age" to "25"
)

val adParam = AdParam.Builder()
    .setAdUnitId("AOS_TEST_BANNER")
    .setCustomParam(customParams)
    .build()

setCurrentPageUrl()​

타겟팅 목적의 현재 페이지 URL을 설정합니다.

val adParam = AdParam.Builder()
    .setAdUnitId("AOS_TEST_BANNER")
    .setCurrentPageUrl("https://www.example.com/current-page")
    .build()

setRefererPageUrl()​

타겟팅 목적의 참조 페이지 URL을 설정합니다.

val adParam = AdParam.Builder()
    .setAdUnitId("AOS_TEST_BANNER")
    .setRefererPageUrl("https://www.example.com/referer-page")
    .build()

SDK의 전역 설정​

광고 요청마다 설정하는 AdParam 외에, SDK 관련 설정인 SdkProperties와 타겟팅 등에 사용되는 사용자 관련 설정인 UserProperties를 통해 공통 설정을 할 수 있습니다.

SdkProperties​

SDK의 전역 설정을 관리하는 오브젝트로서 광고 요청 타임아웃, 음소거 설정, 광고 공급자 옵션 등을 포함합니다.

SdkPropertiesBuilder를 통해 객체를 생성할 수 있고 생성 예시는 아래와 같습니다.

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())

SdkPropertiesBuilder의 주요 메서드​

addProviderOptions()​

일부 광고 제공자의 경우, 광고 제공자별로 제공하는 별도의 기능 설정을 할 수 있습니다.

GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
    .addProviderOptions(DfpProviderOptions.Builder().setTestMode(false).build())
    .addProviderOptions(FanProviderOptions.Builder().setTestMode(false).build())
    .addProviderOptions(UnityProviderOptions.Builder().setTestMode(false).build())
    .build()
)
정보

DfpProviderOptions, FanProviderOptions, UnityProviderOptions 는 TestMode 설정을 제공하며 해당 ProviderOptions 를 미설정할 경우에는 TestMode 의 기본값인 false 상태로 설정됩니다.

bannerAdRequestTimeout()​

GfpBannerAdView를 통해 로드되는 배너 광고의 요청 타임아웃(밀리초 단위)을 설정합니다. 기본값은 60_000 밀리초입니다.

GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
    .bannerAdRequestTimeout(30_000L) // 30초로 설정
    .build())

unifiedAdRequestTimeout()​

GfpAdLoader를 통해 로드되는 광고들의 요청 타임아웃(밀리초 단위)을 설정합니다. 기본값은 60_000 밀리초입니다.

GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
    .unifiedAdRequestTimeout(45_000L) // 45초로 설정
    .build())

rewardedAdRequestTimeout()​

GfpRewardedAdManager를 통해 로드되는 보상형 광고의 요청 타임아웃(밀리초 단위)을 설정합니다. 기본값은 60_000 밀리초입니다.

GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
    .rewardedAdRequestTimeout(90_000L) // 90초로 설정
    .build())

interstitialAdRequestTimeout()​

GfpInterstitialAdManager를 통해 로드되는 전면형 광고의 요청 타임아웃(밀리초 단위)을 설정합니다. 기본값은 60_000 밀리초입니다.

GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
    .interstitialAdRequestTimeout(75_000L) // 75초로 설정
    .build())

muteAudio()​

인스트림 동영상 광고를 제외한 S2S 및 일부 C2S 동영상 광고의 음소거 여부를 설정합니다. 기본값은 true입니다.

GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
    .muteAudio(false) // 음소거 해제
    .build())

theme()​

특정 광고에서 적용되는 GfpTheme 값을 설정합니다. 기본값은 ResolvedTheme.LIGHT입니다.

GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
    .theme(ResolvedTheme.DARK) // 다크 테마 설정
    .build())

bufferDurationsMs()​

인스트림 동영상 광고를 제외한 S2S 및 일부 C2S 동영상 광고의 버퍼링을 설정합니다.

GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
    .bufferDurationsMs(
        BufferDurationsMs(
            0, // 뒤로가기를 위한 버퍼 시간 (ms)
            2000, // 재생 중 유지할 버퍼의 하한 (ms)
            50000, // 재생 중 유지할 버퍼의 상한 (ms)
            0, // 재생 시작을 위한 버퍼 시간 (ms)
            2000 // 재버퍼링 이후 재개를 위한 버퍼 시간 (ms)
        )
    )    
    .build())

UserProperties​

사용자 관련 정보를 관리하는 오브젝트로서 사용자의 성별, 출생년도, 국가, 언어, 사용자 ID 등을 포함합니다. 이 값들은 광고 요청 시 타겟팅을 위해 사용됩니다.

UserPropertiesBuilder를 통해 객체를 생성할 수 있고 생성 예시는 아래와 같습니다.

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())

UserPropertiesBuilder의 주요 메서드​

gender()​

사용자의 성별을 설정합니다. 기본값은 null입니다.

GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
    .gender(GenderType.MALE) // 또는 GenderType.FEMALE
    .build())

yob()​

사용자의 출생년도를 설정합니다. 기본값은 null입니다.

GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
    .yob(1990) // 출생년도 설정
    .build())

country()​

사용자의 국가를 설정합니다. 기본값은 null입니다. 필요시 DSP에 전달하기 위한 값으로, 대개 사용되지 않습니다.

GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
    .country("KR") // ISO 3166-1 alpha-2 코드
    .build())

language()​

사용자의 언어를 설정합니다. 기기에 설정된 언어값이 아닌 별도로 설정된 언어값을 사용합니다. 기본값은 null이며, ISO 639-1 코드 문자로 입력하십시오.

GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
    .language("KO") // ISO 639-1 코드
    .build())

id()​

SDK 로그 추적을 위한 사용자 식별자를 설정합니다.

GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
    .id("user123456") // 사용자 식별자
    .build())

addCustomParam() / setCustomParam()​

전역적으로 사용되는 사용자 정의 매개변수 (from 6.0.0).

정보

NAM SDK 6.0.0부터 추가된 UserProperties.customParameter는 전역적으로 사용되는 사용자 정의 매개변수로 광고 요청별로 사용되는 AdParam.customParameter와 병합될 수 있습니다.

// 개별 매개변수 추가
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())

childDirectedTreatment()​

아동 온라인 개인정보 보호법(COPPA)에 따라 페이지 또는 앱이 아동 대상 서비스인지 나타냅니다. (from 6.1.0) 필요하지 않거나 알 수 없는 경우 설정하지 않아도 됩니다.

GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
    .childDirectedTreatment(true) // 아동 대상 서비스인 경우
    .build())

underAgeOfConsent()​

성인이 아닌 사용자에 대한 광고 요청 여부를 나타냅니다. (from 6.1.0) 필요하지 않거나 알 수 없는 경우 설정하지 않아도 됩니다.

GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
    .underAgeOfConsent(true) // 성인이 아닌 사용자인 경우
    .build())

setContentId()​

네아로 API에서 제공하는 Content ID를 설정합니다. (from 7.6.2) 필요시 NAM 담당자와 협의 후 사용하십시오.

GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
    .setContentId("YOUR_CONTENT_ID")
    .build())

SdkProperties 및 UserProperties 리셋​

NAM SDK 8.4.0 버전부터는 SdkProperties 및 UserProperties를 리셋하는 메서드가 추가되었습니다. 로그인한 사용자가 로그아웃하여 사용자 정보를 초기화하거나, SDK 관련 설정을 초기화해야 할 때는 아래와 같이 처리할 수 있습니다.

GfpSdk.resetSdkProperties()
GfpSdk.resetUserProperties()