본문으로 건너뛰기

광고 요청 정보

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())
    .addProviderOptions(TeadsProviderOptions.Builder().setTestMode(false).setValidationMode(false).build())
    .build()
)
정보

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

Teads 테스트 옵션​

TeadsProviderOptions 는 아래 두 가지 테스트 옵션을 제공합니다. (nam-teads 6.1.0.3 / NAM SDK 8.18.1 이상)

  • setTestMode(true): Teads SDK 의 테스트 모드와 플레이스먼트 디버그 로그를 함께 켭니다. 네트워크 호출, 구성된 광고 요청, 발생한 에러가 콘솔 로그로 출력됩니다. 광고 요청 자체는 변경되지 않으므로 실제 광고를 그대로 받으면서 동작을 확인할 때 사용합니다.
  • setValidationMode(true): Teads 검증 도구(validation) 세션으로 광고 호출을 전환합니다.
경고

setValidationMode(true) 는 화면을 가리는 동작을 포함합니다. 광고 요청마다 닫을 수 없는 Teads 다이얼로그가 표시되며, 데스크톱 브라우저에서 검증 세션을 시작하거나 중단해야 진행됩니다. 중단할 경우 렌더 에러가 전달되어 광고 영역이 비게 되고, 노출되는 크리에이티브도 플레이스먼트의 실제 크리에이티브가 아닌 Teads 검증용 크리에이티브입니다. Teads 검증 세션에서만 사용하고 스토어 배포 빌드에는 포함하지 마십시오.

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