광고 네트워크 미디에이션 어댑터 개발

참고: 미디에이션 서비스와 관련하여 Google 모바일 광고 SDK를 사용하는 경우 미디에이션 서비스 약관이 적용됩니다.

이 가이드는 미디에이션 어댑터를 제작하려는 광고 네트워크를 대상으로 합니다. 게시자는 게시자 미디에이션 지침을 참고하세요.

광고 네트워크 어댑터는 광고 네트워크와 Google 모바일 광고 미디에이션 간의 통신 계층입니다.

어댑터는 배너 광고를 지원하는 MediationBannerAdapter 및 전면 광고를 지원하는 MediationInterstitialAdapter를 구현해야 합니다. 또한 적절한 시점에 MediationBannerListener 및 MediationInterstitialListener 콜백을 호출하여 Google 모바일 광고 미디에이션에 이러한 이벤트를 알려야 하며, 개발자에게 이벤트를 전달할 수도 있습니다.

샘플 광고 네트워크

이 가이드에서는 샘플 광고 네트워크용 어댑터를 만드는 방법을 보여줍니다. 샘플 광고 네트워크에는 대부분의 광고 네트워크가 제공하는 클래스를 대표하는 다음 클래스가 포함되어 있습니다.

class SampleAdView {
    public SampleAdView(Context context);
    public void setSize(SampleAdSize size);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void destroy();
}

class SampleAdSize {
    public SampleAdSize(int width, int height);
    public int getWidth();
    public int getHeight();
}

class SampleAdRequest {
    public SampleAdRequest();
    public void setKeywords(Set<String> keywords);
    public void setTestMode(boolean useTesting);
}

class SampleAdListener {
    public void onAdFetchSucceeded();
    public void onAdFetchFailed(SampleErrorCode code);
    public void onAdFullScreen();
    public void onAdClosed();
}

enum SampleErrorCode {
    UNKNOWN,
    BAD_REQUEST,
    NETWORK_ERROR,
    NO_INVENTORY
}

class SampleInterstitial {
    public SampleInterstitial(Context context);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void show();
    public void destroy();
}

클래스의 자세한 내용은 전체 SDK 구현을 참조하세요.

배너 어댑터 구현하기

배너 광고를 지원하는 어댑터를 구현하려면 MediationBannerAdapter를 구현하는 클래스를 만듭니다.

public class SampleAdapter implements MediationBannerAdapter {
    @Override
    public void requestBannerAd(
            Context context,
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View getBannerView() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

MediationBannerAdapter의 구현을 자세히 알아보기 전에 서버 매개변수, 미디에이션 추가 항목 및 이러한 값이 어댑터에 전달되는 방법을 살펴보겠습니다.

서버 매개변수

게시자를 식별하려면 광고 네트워크에 식별자가 필요할 수 있습니다. 예를 들어 샘플 광고 네트워크에는 광고 단위만 있으면 됩니다. 이러한 필수 매개변수는 requestBannerAd() 내의 serverParameters 번들에서 제공됩니다. 개발 중에는 번들에 필요한 키가 이미 채워져 있다고 가정할 수 있습니다.

private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

@Override
public void requestBannerAd(
        Context context,
        MediationBannerListener listener,
        Bundle serverParameters,
        AdSize adSize,
        MediationAdRequest mediationAdRequest,
        Bundle mediationExtras) {
    String adUnit = serverParameters.getString(SAMPLE_AD_UNIT_KEY);
    ...
}

AdMob에서 광고를 요청하고 게재하기 위해 게시자에게 필요한 서버 매개변수를 묻는 설문지를 보냅니다. AdMob은 이 입력을 사용하여 AdMob UI에 네트워크를 구성합니다. 아래 스크린샷에서는 Millennial Media에 APID가 필요하고 InMobi에는 App ID가 필요합니다.

AdMob에서 어댑터를 인스턴스화할 때 이 정보를 사용하여 serverParameters 번들을 채웁니다.

게시자의 미디에이션 광고 네트워크 구성 방법에 대한 자세한 내용은 도움말을 참조하세요.

추가 타겟팅 매개변수

MediationAdRequest에는 다음과 같이 광고 타겟팅에 사용할 수 있는 일반적인 타겟팅 정보가 포함되어 있습니다.

• getKeywords()
• isTesting()
• taggedForChildDirectedTreatment()

미디에이션 추가

MediationAdRequest에서 제공하지 않는 타겟팅 정보를 광고 네트워크에서 지원하는 경우 앱 개발자가 mediationExtras 번들을 내 네트워크에 전달할 수 있습니다. 미디에이션에서는 미디에이션 추가를 전달하는 예시를 제공합니다.

개발자가 선택적으로 이 정보를 전달할 수 있도록 어댑터에 번들 빌더 클래스를 제공할 수 있습니다. 네트워크에서 수입 값의 전달을 지원한다고 가정해 보겠습니다 어댑터에 수입을 설정하는 빌더 클래스를 추가할 수 있습니다.

public static final class BundleBuilder {
    private int income;

    public BundleBuilder setIncome(int income) {
        this.income = income;
        return this;
    }

    public Bundle build() {
        Bundle bundle = new Bundle();
        bundle.putInt("income", income);
        return bundle;
    }
}

이 클래스는 개발자가 사용자 네트워크의 번들을 생성할 수 있는 깔끔한 API를 제공합니다.

Bundle sampleAdapterBundle =
        new SampleAdapter.BundleBuilder().setIncome(100000).build();

참고: 개발자가 네트워크에 대한 추가 정보를 제공하지 않으면 mediationExtras는 null이 됩니다.

requestBannerAd()

서버 매개변수 및 미디에이션 추가에 대해 알았으니 이번에는 이를 사용해 MediationBannerAdapter를 만들어 보겠습니다.

requestBannerAd() 메서드는 어댑터가 인스턴스화된 직후 호출됩니다. 여기에서 광고 보기를 만들고 배너 광고를 요청해야 합니다.

샘플 광고 네트워크의 requestBannerAd() 구현은 다음과 같습니다.

public class SampleAdMobAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";
    private SampleAdView sampleAdView;

    @Override
    public void requestBannerAd(
            Context context, // May be an application context.
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleAdView = new SampleAdView(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleAdView.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleAdView.setSize(
                new SampleAdSize(adSize.getWidth(),adSize.getHeight()));

        sampleAdView.setAdListener(
                new SampleBannerEventForwarder(listener, this));

        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleAdView.fetchAd(request);
    }
}

컨텍스트 매개변수를 Activity 유형이라고 가정해서는 안 됩니다. 게시자 구현에 따라 Google 모바일 광고 미디에이션은 어댑터에 애플리케이션 컨텍스트를 전달할 수도 있습니다. 어댑터에서 애플리케이션 컨텍스트를 처리할 수 없다면 오류 코드 AdRequest.ERROR_CODE_INVALID_REQUEST로 onAdFailedToLoad()를 호출하는 것이 좋습니다.

MediationBannerListener 콜백

광고 이벤트를 Google 모바일 광고 미디에이션에 다시 전달할 수 있도록 requestBannerAd()에 제공된 MediationBannerListener를 저장해야 합니다. 각 콜백은 광고 수명 주기 중 적절한 시점에 호출되어야 합니다.

메서드	호출 시점
onAdLoaded()	배너 요청에 성공했을 때
onAdFailedToLoad()	배너 요청에 실패했습니다.
onAdClicked()	배너를 클릭했을 때
onAdOpened()	배너가 전체 화면 보기를 렌더링하는 경우
onAdClosed()	사용자가 배너를 클릭한 후 앱으로 돌아가는 경우
onAdLeftApplication()	배너로 인해 사용자가 앱에서 나간 경우

샘플 광고 네트워크 어댑터에서는 SampleBannerEventForwarder라는 클래스를 만들어 이벤트 전달을 처리합니다.

public class SampleBannerEventForwarder extends SampleAdListener {
    private MediationBannerListener mediationListener;
    private SampleAdapter adapter;

    public SampleBannerEventForwarder(
            MediationBannerListener listener, SampleAdapter adapter) {
        this.mediationListener = listener;
        this.adapter = adapter;
    }

    @Override
    public void onAdFetchSucceeded() {
        mediationListener.onAdLoaded(adapter);
    }

    @Override
    public void onAdFetchFailed(SampleErrorCode errorCode) {
        switch(errorCode) {
            case UNKNOWN:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_INTERNAL_ERROR);
                break;
            case BAD_REQUEST:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_INVALID_REQUEST);
                break;
            case NETWORK_ERROR:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_NETWORK_ERROR);
                break;
            case NO_INVENTORY:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_NO_FILL);
                break;
        }
    }

    @Override
    public void onAdFullScreen() {
        mediationListener.onAdClicked(adapter);
        mediationListener.onAdOpened(adapter);
        mediationListener.onAdLeftApplication(adapter);
    }

    @Override
    public void onAdClosed() {
        mediationListener.onAdClosed(adapter);
    }
}

샘플 광고 네트워크 어댑터에서 어떻게 동일한 콜백으로 onAdClicked, onAdOpened, onAdLeftApplication를 전송했는지 확인하세요. 네트워크의 콜백이 Google 모바일 광고에서 요구하는 콜백과 정확히 일치하지 않을 수도 있지만 적절한 매핑을 제공하는 것은 어댑터의 책임입니다.

getBannerView

MediationBannerListener.onAdLoaded()를 호출하면 미디에이션에서 getBannerView()를 호출하여 광고 네트워크의 배너 보기를 화면에 표시합니다. requestBannerAd()에서 만든 배너 보기를 반환하기만 하면 됩니다.

@Override
public View getBannerView() {
    return sampleAdView;
}

활동 수명 주기 이벤트

앱 개발자가 미디에이션에 onPause() 및 onResume() 활동 이벤트를 알리면 미디에이션에서 어댑터에 이를 알립니다. 필요에 따라 배너 일시중지 및 재개를 수행합니다.

@Override
public void onPause() {
}

@Override
public void onResume() {
}

샘플 광고 네트워크에는 호출 일시중지 또는 재개가 포함되어 있지 않으므로 빈 구현을 제공합니다.

어댑터가 폐기되려고 할 때 미디에이션에서는 onDestroy() 호출을 시도합니다. 여기에서 필요한 정리를 실행합니다.

@Override
public void onDestroy() {
    if (sampleAdView != null) {
        sampleAdView.destroy();
    }
}

스마트 배너

Google 모바일 광고 SDK는 전체 너비와 기기 크기에 따라 다양한 높이를 사용하는 스마트 배너 광고 크기를 지원합니다.

스마트 배너의 광고 크기를 정확하게 확인하려면 어댑터에서 adSize.getWidthInPixels(context)을 사용하여 너비를 가져오고 adSize.getHeight() 대신 adSize.getHeightInPixels(context)을 사용하여 높이를 구해야 합니다. 그런 다음 이 값을 기기 밀도로 나눠야 합니다.

int widthInPixels = adSize.getWidthInPixels(context);
int heightInPixels = adSize.getHeightInPixels(context);
DisplayMetrics displayMetrics = Resources.getSystem().getDisplayMetrics();
int widthInDp = Math.round(widthInPixels / displayMetrics.density);
int heightInDp = Math.round(heightInPixels / displayMetrics.density);

그런 다음 광고를 요청할 때 widthInDp 및 heightInDp를 크기로 사용하면 됩니다.

참고: 광고 크기를 가져오는 데 adSize.getWidth() 또는 adSize.getHeight()를 사용하지 마세요. 스마트 배너는 내부적으로 특별한 크기 상수로 표시되므로 adSize.getWidth() 및 adSize.getHeight()는 음수 값을 반환합니다.

작업이 끝났습니다. 이제 배너용 미디에이션 어댑터가 정상적으로 작동하게 됩니다. 참고로 SampleAdapter의 완전한 구현은 여기에서 확인할 수 있습니다.

전면 광고 어댑터 구현하기

전면 광고의 어댑터 구현은 배너 광고와 유사합니다. 전면 광고를 지원하는 어댑터를 구현하려면 MediationInterstitialAdapter를 구현하는 클래스를 만듭니다.

public class SampleAdapter implements MediationInterstitialAdapter {
    @Override
    public void requestInterstitialAd(
            Context context,
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View showInterstitial() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

어댑터가 배너도 지원하는 경우에는 동일한 어댑터 클래스를 사용해 두 인터페이스를 구현하면 됩니다.

MediationInterstitialAdapter 구현을 진행하기 전에 서버 매개변수 및 미디에이션 추가에 대해 알아보세요.

서버 매개변수 (전면 광고)

배너 서버 매개변수 섹션을 참조하세요.

추가 타겟팅 매개변수 (전면 광고)

배너 추가 타겟팅 매개변수 섹션을 참조하세요.

미디에이션 추가 (전면 광고)

배너 미디에이션 추가 섹션을 참조하세요.

requestInterstitialAd

requestInterstitialAd() 메서드는 어댑터가 인스턴스화된 직후 호출됩니다. 여기에서 전면 광고를 만들고 전면 광고를 요청해야 합니다.

샘플 광고 네트워크의 requestInterstitialAd() 구현은 다음과 같습니다.

public class SampleAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

    private SampleInterstitial sampleInterstitial;

    @Override
    public void requestInterstitialAd(
            Context context, // May be an application context.
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleInterstitial = new SampleInterstitial(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleInterstitial.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleInterstitial.setAdListener(
                new SampleInterstitialEventForwarder(listener, this));

        // Make an ad request.
        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleInterstitial.fetchAd(request);
    }
}

컨텍스트 매개변수가 활동 유형이라고 가정해서는 안 됩니다. Google 모바일 광고 미디에이션은 앱 개발자가 전달한 컨텍스트를 전달하는데, 애플리케이션 컨텍스트가 전달될 수도 있습니다. 어댑터에서 애플리케이션 컨텍스트를 처리할 수 없다면 오류 코드 AdRequest.ERROR_CODE_INVALID_REQUEST로 onAdFailedToLoad를 호출하는 것이 좋습니다.

MediationInterstitialListener 콜백

광고 이벤트를 Google 모바일 광고 미디에이션에 다시 전달할 수 있도록 requestInterstitialAd에 제공된 MediationInterstitialListener를 저장해야 합니다. 각 콜백은 광고 수명 주기 중 적절한 시점에 호출되어야 합니다.

메서드	호출 시점
onAdLoaded	전면 광고 요청에 성공한 경우
onAdFailedToLoad	전면 광고 요청에 실패했습니다.
onAdOpened	전면 광고가 표시되고 있습니다.
onAdClosed	전면 광고가 닫힌 경우
onAdLeftApplication	전면 광고로 인해 사용자가 앱에서 이탈하는 경우

showInterstitial

MediationInterstitialListener.onAdLoaded()를 호출한 후에는 showInterstitial()가 호출될 때까지 전면 광고가 게재되길 기다려야 합니다. 전면 광고를 언제 표시할지는 앱 개발자가 결정하며, 요청 후 표시되기까지 최대 몇 분이 걸릴 수 있습니다.

showInterstitial() 구현은 매우 간단합니다. 전면 광고 객체만 표시하면 됩니다.

@Override
public void showInterstitial() {
    sampleInterstitial.show();
}

활동 수명 주기 이벤트 (전면 광고)

배너 활동 수명 주기 이벤트 섹션을 참조하세요.

활동 수명 주기 이벤트를 구현하고 나면 미디에이션 어댑터에서 전면 광고를 처리할 준비가 된 것입니다. 참고로 SampleAdapter의 완전한 구현은 여기에서 확인할 수 있습니다.

FAQ

어댑터가 배너 또는 전면 광고 중 하나만 지원하는 경우에는 어떻게 해야 하나요?

배너만 지원하는 어댑터인 경우에는 MediationBannerAdapter 인터페이스만 구현해야 합니다. 전면 광고만 지원하는 어댑터인 경우에는 MediationInterstitialAdapter 인터페이스만 구현해야 합니다.