본문으로 건너뛰기

광고 요청 정보

1. 광고 요청 정보​

각 광고 형태에 맞는 광고 요청시에는 광고 요청에 필요한 정보를 담은 AdParam 객체를 생성해야 합니다.

세부적인 타겟팅 및 리포팅은 customParam 에 적용된 항목으로 적용됩니다.

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") // GFP Admin 을 통한 타겟팅 설정 및 리포트 지원
    .build()

Parameter 설명​

광고 요청시에 사용되는 AdParam 내의 parameter 들은 각각의 역할이 있습니다.

이하 S2S의 경우 Server to Server의 약자로, NDA 모듈을 통해 NAM이 제공하는 광고 공급자 연동 방식을 말합니다.

  • Ad Unit ID (required)

    필수적인 param 으로 광고 Unit ID 에 해당됩니다.

  • Current Page URL (optional)

    현재 화면을 표현하는 page 의 url 에 해당됩니다.

    해당 값은 타겟팅 목적의 parameter 로 S2S 광고 요청시에 사용됩니다.

  • RefererPageUrl (optional)

    타겟팅 목적의 parameter 로 S2S 광고 요청시에 사용됩니다.

  • Custom Parameter (optional)

    DFP 및 S2S 에서 사용되는 parameter 로 세부적인 타게팅 및 리포팅을 위해서 사용됩니다.

    key, value 값은 NAM 담당자를 통해 확인 & 협의 부탁드립니다.

    Map<String, String> 형태의 collection 을 이용해서 setCustomParam() 에 할당하거나 addCustomParam(String, String) 를 사용해서 복수개의 keyword 를 할당할 수 있습니다.

    DFP 매뉴얼의 예시를 참고해 주세요.

    1개의 key로 여러 개의 value를 전달해야 한다면 “|“으로 구분하여 전달할 수 있습니다.

  • 동영상 관련 파라미터 (required in video)

    video 광고에서 필요한 메타 정보입니다.

    • vsi: 비디오 스케줄 아이디 (Video ad Schedule Id)

      vri: 비디오 스케줄 요청 아이디 (Video ad schedule Request id)

      vcl: 비디오 켄텐츠 길이 (Video Content Length)

      vsd: 비디오 전/중/후 여부 (Video StartDelay)

      vrr: 비디오 리마인드 광고 요청 여부 (Video ad Request a Remind ad)

  • Keyword (optional in video)

    현재 화면과 관련된 keyword 값에 해당됩니다.

    해당 keyword 값들은 IMA 에서 세부적인 타게팅 및 리포팅을 위해서 사용됩니다.

2. SDK 의 Global 설정​

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

2-1. SDK 관련​

SDK 관련된 설정 가능한 목록은 아래와 같습니다.

2-1-1. ProviderOption​

  • addProviderOptions(GfpProviderOptions) 일부 DSP의 경우 테스트 광고를 받기 위해서 TestMode 설정이 필요한 경우가 있습니다.

    (DfpProviderOptions, FanProviderOptions, UnityProviderOptions, NdaProviderOptions)

    설정하지 않을 경우 각 광고제공자의 TestMode 는 기본 값인 Off 상태입니다.

2-1-2. 광고 요청 Timeout 관련​

광고 요청 Timeout 과 관련된 API 목록은 다음과 같습니다. 설정시 넘겨지는 long 값은 양수의 millis 값으로 설정해야만 합니다.

기본적으로 60초가 설정되어 있습니다.

이름설명
bannerAdRequestTimeout(long)배너 광고(GfpBannerAdView)의 타임아웃값을 설정.
videoAdRequestTimeout(long)동영상 광고의 타임아웃값을 설정.
unifiedAdRequestTimeout(long)광고 로더(GfpAdLoader)를 통해서 호출하는 광고의 타임아웃값을 설정.
rewardedAdRequestTimeout(long)리워드형 광고(GfpRewardedAdManager)의 타임아웃값을 설정.
interstitialAdRequestTimeout(long)전면형 광고(GfpInterstitialAdManager)의 타임아웃값을 설정.
2-1-3. 음소거 옵션​

리워드형 광고에 대해서 동영상 소재의 음소거 옵션을 제공합니다. 다만 이 옵션은 In-Stream 광고에는 사용되지 않습니다.

2-1-4. 샘플​
GfpSdk.setSdkProperties(GfpSdk.getSdkProperties().buildUpon()
    .addProviderOptions(DfpProviderOptions.Builder().setTestMode(false).build())
    .addProviderOptions(FanProviderOptions.Builder().setTestMode(false).build())
    .addProviderOptions(NdaProviderOptions.Builder().setTheme(ResolvedTheme.SYSTEM).build())
    .addProviderOptions(UnityProviderOptions.Builder().setTestMode(false).build())
    .bannerAdRequestTimeout(60_000L)
    .unifiedAdRequestTimeout(60_000L)
    .videoAdRequestTimeout(60_000L)
    .interstitialAdRequestTimeout(60_000L)
    .rewardedAdRequestTimeout(60_000L)
    .build())
)

2-2. 유저(타겟팅) 관련​

광고 타게팅에 사용되는 설정 목록은 다음과 같습니다.

속성설명
gender()사용자의 성별값을 설정. 미설정시 기본값은 null 입니다. 판별하기 어려운 경우 GenderType.UNKNOWN 을 설정해주시면 됩니다.
yob()사용자의 출생년도를 설정. 미설정시 기본값은 null 입니다.
country()사용자의 국가값을 설정. 미설정시 기본값은 null 입니다. 필요시 DSP에 전달하기 위한 값으로, 대개 사용되지 않습니다.
language()사용자의 언어값을 설정. 기기에 설정된 언어값이 아닌 서비스에서 별도로 설정되는 언어값이 있을 경우 사용합니다. 미설정시 기본값은 null 로, ISO 639-1 코드의 문자를 넣어주시면 되고 대개 사용되지 않습니다.
id()SDK 로그 추적을 위해 사용될 수 있는 매체쪽 유저 식별자 값을 설정.
customParameter()전역적으로 사용되는 custom parameter (from 6.0.0)
childDirectedTreatment(Boolean)아동 온라인 개인정보 보호법 (COPPA) 에 의거하여 페이지 또는 앱이 아동 대상 서비스로 취급 되어야 하는지 여부를 나타냅니다. (from 6.1.0) 알 수 없거나 불 필요한 경우 설정하지 않으면 됩니다.
underAgeOfConsent(Boolean)성인이 아닌 사용자에 대한 광고 요청 여부를 나타냅니다. (from 6.1.0) 알 수 없거나 불 필요한 경우 설정하지 않으면 됩니다.
contentId(String)네아로 API에서 제공하는 Content ID 설정 (from 7.6.2) 네아로 API를 사용하지 않는 경우 설정하지 않으면 됩니다. 필요시 NAM 담당자와 협의 후 사용 부탁드립니다.
정보

NAM SDK 6.0.0 부터 추가된 UserProperties.customParameter 는 전역적으로 사용되는 custom parameter 로써 광고 요청별로 사용되는 AdParam.customParameter 와 병합되어서 사용될 수 있습니다.

GfpSdk.getUserProperties().clearCustomParameter()

GfpSdk.setUserProperties(GfpSdk.getUserProperties().buildUpon()
                            // .id() 광고 로그 추적을 위해서 사용될 수 있는 매체쪽 유저 식별자값
                            .yob(1987)
                            .country("KR")
                            .language("KO")
                            .gender(GenderType.MALE)
                            .addCustomParam("aaa", "bbb")
                            .setCustomParam(mapOf("k1" to "v1", "k2" to "v2"))
                            .setContentId("test content")
                            .build())