تطوير مهايئ وساطة شبكة الإعلانات

ملاحظة: إنّ استخدامك لحزمة SDK الخاصة بإعلانات Google على الأجهزة الجوّالة في ما يتعلق بخدمات التوسّط يخضع لبنود خدمة التوسّط.

هذا الدليل مخصّص لشبكات المواقع الإعلانية التي تتطلّع إلى إنشاء محوّل توسّط. إذا كنت ناشرًا، اطّلِع على تعليمات توسّط الناشرِين.

محوّل شبكة الإعلانات هو طبقة الاتصال بين شبكة الإعلانات وتوسّط إعلانات 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، دعنا نناقش معلمات الخادم، وإضافات التوسط، وكيفية تمرير هذه القيم إلى المحوّل.

مَعلمات الخادم

من المحتمل أن تحتاج شبكة الإعلانات إلى بعض المعرّفات من أجل تحديد هوية الناشر. على سبيل المثال، يتطلب نموذج شبكة الإعلانات وحدة إعلانية فقط. يتم توفير هذه المعلَمات المطلوبة لك في حزمة 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 على بعض معلومات الاستهداف الشائعة التي يمكنك استخدامها لاستهداف الإعلانات، مثل:

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

توفّر هذه الفئة واجهة برمجة تطبيقات واضحة للمطوِّر لإنشاء حزمة لشبكتك:

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

ملاحظة: لن يتم توفير قيم التوسّطExtras إذا لم يقدِّم مطوِّر البرامج أي ميزات إضافية لشبكتك.

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 على الأجهزة الجوّالة توجيه سياق التطبيق إلى المحوّل. إذا لم يتمكّن المحوّل من معالجة سياق التطبيق، ننصحك باستدعاء onAdFailedToLoad() مع عرض رمز الخطأ AdRequest.ERROR_CODE_INVALID_REQUEST.

استدعاءات MediationBannerListener

عليك حفظ MediationBannerListener المقدّمة لك في requestBannerAd() بحيث يمكنك إعادة توجيه أحداث الإعلانات إلى "توسّط إعلانات Google على الأجهزة الجوّالة" مرة أخرى. يجب استدعاء كل معاودة اتصال في الوقت المناسب خلال دورة حياة الإعلان:

الطريقة	وقت الاتصال
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();
    }
}

إعلانات البانر الذكية

تتوافق حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" مع حجم إعلان بانر ذكي بعرض كامل وارتفاع متغيّر حسب حجم الجهاز.

للحصول على حجم إعلان البانر الذكي بدقة، يجب أن يستخدم المحوِّل 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 كحجم عند تقديم طلب إعلان.

ملاحظة: لا تستخدم adSize.getWidth() أو adSize.getHeight() للحصول على حجم الإعلان. يتم تمثيل إعلانات البانر الذكية بحجم ثابت داخلي، لذلك تعرِض adSize.getWidth() وadSize.getHeight() قيمتَين سالبتَين.

أكملت هذه الخطوة. لديك الآن محوّل توسّط يعمل بشكل صحيح لإعلانات البانر. كمرجع، يمكنك الاطّلاع هنا على عملية تنفيذ كاملة لـ Sample Adapter.

تنفيذ محوّل بيني

يتشابه تنفيذ المحوّل للإعلانات البينية مع إعلانات البانر. لتنفيذ محوّل يتيح عرض الإعلانات البينية، عليك إنشاء فئة تنفّذ 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 للجوّال توجيه السياق الذي تجاوزه مطوّر التطبيق، ومن الممكن أن يتم تمرير سياق التطبيق. إذا لم يتمكّن المحوّل من معالجة سياق التطبيق، ننصحك باستدعاء onAdFailedToLoad مع عرض رمز الخطأ AdRequest.ERROR_CODE_INVALID_REQUEST.

استدعاءات MediationInterstitialListener

عليك حفظ MediationInterstitialListener المقدّمة لك في requestInterstitialAd حتى تتمكن من إعادة توجيه أحداث الإعلانات إلى توسّط إعلانات Google على الأجهزة الجوّالة مرة أخرى. يجب استدعاء كل معاودة اتصال في الوقت المناسب خلال دورة حياة الإعلان:

الطريقة	وقت الاتصال
onAdLoaded	تم إرسال الطلب البيني بنجاح.
onAdFailedToLoad	تعذّر طلب الإعلان البيني.
onAdOpened	يتم عرض الإعلان البيني.
onAdClosed	الإعلان البيني مغلق.
onAdLeftApplication	تؤدي الصفحة البينية إلى مغادرة المستخدم التطبيق.

showInterstitial

بعد طلب الإعلان MediationInterstitialListener.onAdLoaded()، عليك الانتظار لعرض الإعلان البيني إلى أن يتم طلب showInterstitial(). يقرر مطوِّر التطبيق وقت عرض الإعلان البيني، وقد يستغرق ذلك مدة تصل إلى عدة دقائق بعد طلب الإعلان.

إنّ عملية تنفيذ showInterstitial() واضحة جدًا. ما عليك سوى عرض الكائن البيني:

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

أحداث مراحل نشاط النشاط (الإعلانات البينية)

يُرجى الاطّلاع على قسم أحداث مراحل نشاط نشاط البانر.

بعد تنفيذ أحداث مراحل نشاط النشاط، يصبح محوّل التوسّط جاهزًا للتعامل مع الإعلانات البينية. كمرجع لك، يمكن العثور على عملية تنفيذ كاملة لـ sampleAdapter هنا.

الأسئلة الشائعة

ماذا أفعل إذا كان المحوّل يتيح استخدام إعلانات البانر أو الإعلانات البينية فقط، وليس كليهما؟

إذا كان المحوِّل لا يتوافق إلا مع إعلانات البانر، ستحتاج فقط إلى تنفيذ واجهة MediationBannerAdapter. وإذا كان المحوّل لا يتيح سوى الإعلانات البينية، لن تحتاج سوى إلى تنفيذ واجهة MediationInterstitialAdapter.