این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

توسعه آداپتور میانجی شبکه تبلیغاتی

این راهنما برای شبکه های تبلیغاتی در نظر گرفته شده است که به دنبال ساخت یک آداپتور میانجی هستند. اگر ناشر هستید، دستورالعمل‌های میانجی‌گری ناشر را ببینید.

آداپتور شبکه تبلیغاتی لایه ارتباطی بین شبکه تبلیغاتی شما و واسطه گری تبلیغات موبایل گوگل است.

آداپتور مسئول اجرای 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 بپردازیم، اجازه دهید در مورد پارامترهای سرور، موارد اضافی میانجی‌گری و نحوه ارسال این مقادیر به آداپتور بحث کنیم.

پارامترهای سرور

شبکه تبلیغاتی شما احتمالاً برای شناسایی ناشر به شناسه(های) نیاز دارد. برای مثال، شبکه تبلیغاتی نمونه فقط به یک واحد تبلیغاتی نیاز دارد. این پارامترهای مورد نیاز در بسته serverParameters در داخل requestBannerAd() در اختیار شما قرار می گیرد. در طول توسعه، می توانید فرض کنید که بسته از قبل با کلیدهای مورد نیاز شما پر شده است:

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 استفاده خواهد کرد. تصویر زیر نشان می‌دهد که APID برای Millennial Media و App ID برای InMobi لازم است.

AdMob از این اطلاعات برای پر کردن بسته serverParameters هنگام نمونه سازی آداپتور شما استفاده می کند.

برای اطلاعات بیشتر در مورد نحوه پیکربندی ناشران شبکه های تبلیغاتی میانجی به این مقاله مراجعه کنید.

پارامترهای هدف گیری اضافی

MediationAdRequest حاوی برخی از اطلاعات هدف‌گیری رایج است که می‌توانید از آنها برای هدف‌یابی تبلیغات استفاده کنید، مانند:

موارد اضافی میانجیگری

اگر شبکه تبلیغاتی شما از اطلاعات هدفمندی پشتیبانی می‌کند که 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();

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 Mobile Ads Mediation ممکن است زمینه برنامه را به آداپتور شما ارسال کند. اگر آداپتور شما نمی تواند زمینه برنامه را مدیریت کند، توصیه می شود که onAdFailedToLoad() را با کد خطا AdRequest.ERROR_CODE_INVALID_REQUEST فراخوانی کنید.

MediationBannerListener به تماس ها پاسخ می دهد

باید MediationBannerListener را که در requestBannerAd() ارائه شده است ذخیره کنید تا بتوانید رویدادهای تبلیغاتی را به Google Mobile Ads Mediation بازگردانید. هر تماس برگشتی باید در زمان مناسب در چرخه عمر تبلیغ فراخوانی شود:

روش	چه زمانی تماس بگیرید
`onAdLoaded()`	درخواست بنر با موفقیت انجام شد.
`onAdFailedToLoad()`	درخواست بنر انجام نشد.
`onAdClicked()`	روی بنر کلیک شد.
`onAdOpened()`	بنر در حال نمایش تمام صفحه است.
`onAdClosed()`	کاربر پس از کلیک بر روی یک بنر به برنامه باز می گردد.
`onAdLeftApplication()`	بنر باعث می شود کاربر از برنامه خارج شود.

آداپتور شبکه Sample ad کلاسی به نام 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 Mobile Ads مطابقت نداشته باشد، این مسئولیت آداپتور است که نقشه‌ای معقول ارائه دهد.

getBannerView

هنگامی که MediationBannerListener.onAdLoaded() را فراخوانی کردید، واسطه گری getBannerView() را فراخوانی می کند تا نمای بنر شبکه تبلیغاتی شما روی صفحه نمایش داده شود. به سادگی نمای بنری را که در requestBannerAd() ایجاد کردید برگردانید:

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

رویدادهای چرخه حیات فعالیت

در صورتی که توسعه‌دهنده برنامه میانجی‌گری رویدادها را اطلاع دهد، واسطه‌سازی به آداپتور رویدادهای فعالیت onPause() و onResume() اطلاع می‌دهد. هرگونه مکث و از سرگیری بنر خود را انجام دهید:

@Override
public void onPause() {
}

@Override
public void onResume() {
}

شبکه تبلیغاتی نمونه شامل مکث یا تماس مجدد نمی شود، بنابراین یک پیاده سازی خالی ارائه می دهد.

هنگامی که آداپتور در شرف نابودی است، Mediation بهترین تلاش خود را برای فراخوانی onDestroy() انجام می دهد. هر گونه پاکسازی لازم را در اینجا انجام دهید:

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

بنرهای هوشمند

Google Mobile Ads SDK از اندازه تبلیغات بنری هوشمند پشتیبانی می کند که بسته به اندازه دستگاه، عرض کامل و ارتفاع متغیر است.

برای دریافت دقیق اندازه تبلیغات یک بنر هوشمند، آداپتور شما باید از adSize.getWidthInPixels(context) برای بدست آوردن عرض و adSize.getHeightInPixels(context) به جای adSize.getHeight() برای بدست آوردن ارتفاع استفاده کند. سپس باید بر چگالی دستگاه تقسیم شود:

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 به عنوان اندازه هنگام درخواست تبلیغات استفاده کنید.

خودشه! اکنون یک آداپتور میانجی کار برای بنرها دارید! برای مرجع، پیاده‌سازی کامل 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 با پارامترهای سرور و موارد اضافی میانجی آشنا شوید.

درخواستInterstitialAd

متد requestInterstitialAd() بلافاصله پس از نمونه سازی آداپتور فراخوانی می شود. اینجاست که باید تبلیغ بینابینی خود را ایجاد کنید و درخواست بینابینی بدهید.

پیاده سازی requestInterstitialAd() برای شبکه تبلیغاتی Sample به شکل زیر است:

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);
    }
}

فرض نکنید که پارامتر زمینه از نوع Activity است! Google Mobile Ads Mediation متنی را که توسط توسعه‌دهنده برنامه ارسال شده است، ارسال می‌کند و ممکن است یک زمینه برنامه ارسال شود. اگر آداپتور شما نمی تواند زمینه برنامه را مدیریت کند، توصیه می شود onAdFailedToLoad با کد خطا AdRequest.ERROR_CODE_INVALID_REQUEST فراخوانی کنید.

MediationInterstitialListener به تماس پاسخ می دهد

باید MediationInterstitialListener را که در requestInterstitialAd به شما ارائه شده است ذخیره کنید تا بتوانید رویدادهای تبلیغاتی را به Google Mobile Ads Mediation بازگردانید. هر تماس برگشتی باید در زمان مناسب در چرخه عمر تبلیغ فراخوانی شود:

روش	چه زمانی تماس بگیرید
onAdLoaded	درخواست بینابینی با موفقیت انجام شد.
onAdFailedToLoad	درخواست بینابینی ناموفق بود.
onAdOpened	بینابینی در حال نمایش است.
روی AdClosed	بینابینی بسته است.
onAdLeftApplication	بینابینی باعث می شود کاربر برنامه را ترک کند.

نمایش بینابینی

هنگامی که MediationInterstitialListener.onAdLoaded() را فراخوانی کردید، باید منتظر بمانید تا interstitial نمایش داده شود تا زمانی که showInterstitial() فراخوانی شود. برنامه‌نویس برنامه تصمیم می‌گیرد که چه زمانی بینابینی را نشان دهد، که ممکن است تا چند دقیقه پس از درخواست آن باشد.

پیاده سازی برای showInterstitial() بسیار ساده است. فقط شی بینابینی خود را نشان دهید:

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

رویدادهای چرخه حیات فعالیت (بینابینی)

بخش رویدادهای چرخه حیات فعالیت بنر را ببینید.

پس از اجرای رویدادهای چرخه حیات فعالیت، آداپتور میانجی شما آماده رسیدگی به تبلیغات بینابینی است! برای مرجع، پیاده‌سازی کامل SampleAdapter را می‌توانید در اینجا بیابید.

سوالات متداول

اگر آداپتور من فقط از تبلیغات بنر یا بینابینی پشتیبانی می کند، اما از هر دو پشتیبانی نمی کند، چه کار کنم؟: اگر آداپتور شما فقط از بنرها پشتیبانی می کند، فقط باید رابط MediationBannerAdapter را پیاده سازی کنید. اگر آداپتور شما فقط از موارد بینابینی پشتیبانی می کند، فقط باید رابط MediationInterstitialAdapter را پیاده سازی کنید.