4-3. 배너 광고 : Banner ADs

배너는 가장 일반적인 광고 형태로 앱의 하단이나 상단에 노출되는 띠 형태의 광고입니다.(Banners are the most common form of advertising, typically exposed at the top or bottom of an app as a strip.)

배너 생성(Creating a Banner)

배너는 두 가지 방식 , 선언형 또는 명령형으로 구현할 수 있습니다. (Banners can be implemented in two ways: declaratively or imperatively.)

XML 선언형(XML Declarative)

배너 광고가 노출될 뷰를 사용 중인 Layout.xml 파일에 추가합니다. (Add the banner ad view to your layout.xml file where the banner ad will be exposed.)

<LinearLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="#ffffff"
    android:orientation="vertical"> 
        <!-- Banner View -->         
       <com.oneadmax.global.OAMBanner
            android:id="@+id/banner"
            android:layout_width="match_parent"
            android:layout_height="wrap_content" />
</LinearLayout>

xml에서 형성된 인스턴스를 추가합니다. (Add the instance created from xml.)

private OAMBanner banner;
 
@Override
protected void onCreate( Bundle savedInstanceState ){
    ...
    banner = (OAMBanner)findViewById(R.id.banner);
    ...
}

명령형(코드) 방식(Imperative (Code) Method)

xml 없이 명령어를 통해 소스코드 맥락에서 배너 광고를 생성할 수 있습니다. 아래의 코드를 참고하세요. (Without xml, create the banner ad within the source code context using the command method. Refer to the code below:)

private OAMBanner banner;
 
@Override
protected void onCreate( Bundle savedInstanceState ){
    ...
    // 베너 광고가 보이게 될 Activity와, 상단 또는 하단에 생성할지를 전달합니다.
    banner = new OAMBanner( MyActivity.this, Gravity.TOP|Gravity.CENTER );
    ...
}

배너 PLACEMENT ID (Banner PLACEMENT ID)

배너광고의 PLACEMENT ID 를 설정합니다. 배너 PLACEMENT ID 는 ONE AdMax 콘솔에서 생성이 가능합니다. (Set the PLACEMENT ID for your banner ad. The banner PLACEMENT ID can be created in the ONE AdMax console.)

banner.setPlacementId( PLACEMENT_ID );

배너 사이즈(Banner Size)

배너 사이즈는 3 가지 옵션이 있으며, ONE AdMax 콘솔에서 배너 광고 생성 시 지정한 값이 동일하게 세팅되야만 합니다. (There are three options for banner size, which must be set to match the value specified when creating the banner ad in the ONE AdMax console.)

public enum Size {
    BANNER_320x50, BANNER_300x250, BANNER_320x100,
}
 
banner.setSize( OAMBanner.Size.BANNER_320x50 );

배너 갱신 주기(Banner Refresh Rate)

배너 광고의 갱신주기를 설정합니다. 설정가능 범위는 15~300초이며, -1 로 설정 시 갱신 되지 않습니다. (Set the refresh rate for the banner ad. The possible range is 15-300 seconds, and Settings it to -1 means it will not refresh.)

banner.setRefreshTime( 60 ); // default 60 sec

배너 네트워크 스케쥴 타임아웃(Banner Network Schedule Timeout)

배너 광고에 대한 네트워크 스케쥴 타임아웃을 설정합니다. 배너 광고 로딩 시 각 네트워크( 미디에이션 업체 )별로 타임아웃 시간을 주어 해당 시간 안에 광고를 받지 못할 경우 , 다음 네트워크로 넘어가게 됩니다 (Set the network schedule timeout for the banner ad. If an ad is not received within the timeout period for each network (mediation company), it moves on to the next network.)

banner.setNetworkScheduleTimeout( 5 ); // default 5 sec

배너 애니메이션(Banner Animation)

배너 광고는 다음의 애니메이션을 제공합니다. (Banner ads offer the following animation options:)

public enum AnimType{
    NONE,          
    FADE_IN,       
    SLIDE_LEFT,    
    SLIDE_RIGHT,
    TOP_SLIDE,
    BOTTOM_SLIDE,
    CIRCLE,
}
 
banner.setAnimType( OAMBanner.AnimType.FADE_IN ); // default : NONE

배너 배경색( Default : true )(Banner Background Color (Default: true))

배너 광고가 나오는 뷰의 빈 공간에 광고에 맞는 최적화된 배경색을 채울 수 있습니다. (You can fill the empty space of the view where the banner ad appears with an optimized background color that matches the ad.)

banner.setAutoBgColor( true );  // default true

배너 요청(Banner Request)

배너가 화면에 노출되기 원하는 시점에 load() api 를 호출합니다. loading이 완료되면, onLoaded() 이벤트가 전달되며, 자동으로 화면에 나타나게 됩니다. (Call the load() API when you want the banner to be exposed on the screen. Once loading is complete, the onLoaded() event is delivered, and the banner will automatically appear on the screen.)

banner.load();

* load() 호출에 대한 결과로 광고 수신에 실패한 경우에는 load() 재호출 하시면 안됩니다. 과도한 load() api 호출은 block 사유가 됩니다. (Note: If you fail to be receive the ad upon calling load(), do not recall load() as excessive API calls can lead to blocks.)

배너 중단(Banner Suspension)

배너 광고를 중단하고 싶은 시점에 호출합니다. 일반적으로 배너가 노출된 activity 나 fragment 가 destroy 할 때 호출합니다. (Call this when you want to stop the banner ad, typically when the activity or fragment exposing the banner is about to be destroyed.)

banner.stop();

* 단 onPause 상태 진입 시 stop() 를 호출할 경우 클릭 리포트 수치가 누락되는 경우가 발생하므로 해당 배너뷰가 포함된 activity 나 fragment 가 destroy 진입 시 호출하는 것이 좋습니다. (Note: It is advisable to call stop() when entering the destroy state of the activity or fragment containing the banner view, as calling stop() upon entering onPause may result in missing click reports.)

배너 노출 여부(Banner Visibility)

다른 광고 타입과 달리 배너는 Load되면 자동으로 화면에 보여지므로, 다음 함수를 사용하여 노출 유무를 판단할수 있습니다. (Unlike other ad types, banners are automatically exposed on the screen once loaded, so use the following function to determine visibility.)

banner.isLoaded();

배너 이벤트 리스너(Banner Event Listener)

배너를 불러올 때 발생하는 이벤트에 대한 리스너를 설정합니다. 제공되는 리스너와 구현 예시는 다음과 같습니다. (Set up listeners for events that occur when loading the banner. The provided listeners and implementation examples are as follows:)

banner.setEventListener( new IOAMBannerEventListener(){
    @Override
    public void onLoaded(){                     // banner loading 성공
        Log.d( Tag, "onBannerAdLoaded" );
    }
 
    @Override
    public void onLoadFailed( OAMError error ){ // banner loading 실패
        Log.d( Tag, "onLoadFailed : " + error.toString() );
    }
     
    @Override
    public void onClicked(){                    // banner click.
        Log.d( Tag, "onBannerAdLoaded" );
    }
});

* OAMError 는 (링크) 를 참고하세요 (Note: For OAMError, please refer to link)

배너 onPause / onResume(Banner onPause / onResume)

배너 광고가 노출되고 있는 Activity나 Fragment의 onPause / onResume 에서 Banner의 onPause / onResume을 호출해 줘야 합니다. (In the onPause / onResume of the activity or fragment exposing the banner ad, you must call the banner's onPause / onResume.)

onPause/onResume을 정상적으로 처리해 주지 않을 경우 third-party mediation을 사용할 때, 리포트 수치가 누락되는 경우가 있으므로 하기와 같이 구현해 주시는 것이 좋습니다. (Failing to properly handle onPause/onResume can lead to missing reports when using third-party mediation, so it is recommended to implement as follows:)

OAMBanner   banner;
 
public void onPause(){
    super.onPause();
 
    if( banner != null )
        banner.onPause();
}
 
public void onResume(){
    super.onResume();
 
    if( banner != null )
        banner.onResume();
}

배너 미디에이션 (Banner Mediation)

배너 광고는 일부 미디에이션에 대한 사용을 지원합니다. 배너의 load() api 호출 이전에 setting 되야 하며, 다음을 참고하세요. (Banner ads support the use of some mediations. This Settings must be done before calling the banner's load() API. Refer to the following codes:)

HashMap map = new HashMap<>();
map.put( OAMBanner.MediationExtra.CAULY_USE_DYNAMIC_RELOAD, false );
map.put( OAMBanner.MediationExtra.CAULY_RELOAD_INTERVAL, 20 );
map.put( OAMBanner.MediationExtra.CAULY_THREAD_PRIORITY, 5 );
 
banner.setMediationExtras( map );
banner.load();

지원하는 미디에이션의 설정값은 다음과 같습니다. (The set value for supported mediations is as follows:)

CAULY_ENABLE_LOCK               : 잠금 화면에서 노출 가능 여부. default false.
CAULY_ENABLE_DYNAMIC_RELOAD_INTERVAL: 카울리 다이나믹 배너 갱신 사용 여부. default true.
CAULY_RELOAD_INTERVAL           : 카울리 배너 갱신 주기. range: 10~120. default 20s. CAULY_ENABLE_DYNAMIC_RELOAD_INTERVAL를 false로 설정후에 사용가능.
CAULY_THREAD_PRIORITY           : 카울리 스레드 우선 순위 지정. range: 1~10. default 5.
 
MEZZO_AGE_LEVEL                 : 유저 나이 정보, default -1. 알수 없음 = -1, 어린이(13세 미만) = 0, 청소년 및 성인(만 13세 이상) = 1
MEZZO_ENABLE_BACKGROUND_CHECK   : 백그라운드 갱신 사용 여부.
MEZZO_STORE_URL                 : 앱 스토어 URL

배너 샘플 코드(Banner Sample Code)

배너 사용에 관련된 sample code 입니다. 다음을 참고하세요. (Refer to the following sample code related to the use of banner ads.)

private OAMBanner banner;
 
@Override
protected void onCreate( Bundle savedInstanceState ){
    super.onCreate( savedInstanceState );
    ...
     
    // ONEAdMax 로그 활성화. apk release시에는 삭제해야 합니다.
    ONEAdMax.setLogEnable( true );
 
    //ONEAdMax SDK 초기화
    if( ONEAdMax.isInit( MyActivity.this ) == false ){
        ONEAdMax.init( MyActivity.this, new IOAMInitListener() {
            @Override
            public void onInitialized() {
                Log.d( Tag, "ONEAdMax SDK Initialized.");
                initBanner( yourBannerPlacementID,  youtBannerSize  );
            }
        });
    }
 
    ...
}
 
 
public void initBanner( String placementId, OAMBanner.Size bannerSize ){
    // xml 없이 코드로 Banner 를 생성합니다.
    banner = new OAMBanner( MyActivity.this, Gravity.TOP|Gravity.CENTER );
 
    // placementID와 size setting은 필수입니다.  
    banner.setPlacementId( yourBannerPlacementID );
    banner.setSize( bannerSize );
 
    // optional    
    banner.setAnimType( OAMBanner.AnimType.FADE_IN );
    banner.setAutoBgColor( true );    
    banner.setNetworkScheduleTimeout( 10 );
    banner.setRefreshTime( 15 );
   
    HashMap map = new HashMap<>();
    map.put( OAMBanner.MediationExtra.CAULY_USE_DYNAMIC_RELOAD, false );
    map.put( OAMBanner.MediationExtra.CAULY_RELOAD_INTERVAL, 20 );
    map.put( OAMBanner.MediationExtra.CAULY_THREAD_PRIORITY, 5 );
    banner.setMediationExtras( map ); 
 
 
    // listener를 등록하지 않으면 이벤트를 받을 수 없습니다.
    banner.setEventListener( new IOAMBannerEventListener(){
        @Override
        public void onLoaded(){
            Log.d( Tag, "banner load success" );
        }
 
        @Override
        public void onLoadFailed( OAMError error ){
            Log.d( Tag, "banner load failed: " + error.toString() );
        }
 
        @Override
        public void onClicked(){
            Log.d( Tag, "banner clicked." );
        }
    } );    
 
    banner.load();
}
 
@Override
public void onPause(){
    super.onPause();
 
    if( banner != null )
        banner.onPause();
}
 
@Override
public void onResume(){
    super.onResume();
 
    if( banner != null )
         banner.onResume();
}
 
@Override
protected void onDestroy(){
    super.onDestroy();  
     
    if( banner != null )
        banner.stop();
 
    ONEAdMax.unInit();
}