פיתוח מתאם מנגנון בחירת הרשת למודעות

הערה: השימוש שלך ב-Google Mobile Ads SDK בהקשר של שירותי הגישור כפוף לתנאים ולהגבלות של תהליך בחירת הרשת.

המדריך הזה מיועד לרשתות מודעות שמעוניינות לבנות מתאם לתהליך בחירת הרשת (Mediation). אם אתם בעלי תוכן דיגיטלי, קראו את ההוראות לתהליך בחירת הרשת לבעלי אפליקציות.

מתאם לרשת מודעות הוא שכבת התקשורת בין רשת המודעות שלך לבין 'גישור Google לנייד'.

המתאם אחראי להטמיע את MediationBannerAdapter כדי לתמוך במודעות באנר ואת MediationInterstitialAdapter כדי לתמוך במודעות מעברון. בנוסף, הוא צריך להפעיל את הקריאות החוזרות (callback) ב-MediationBannerListener וב-MediationInterstitialListener במועדים המתאימים כדי להודיע לתהליך בחירת הרשת (Mediation) במודעות 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, ומזהה האפליקציה נדרש ל-InMobi.

המידע הזה ישמש את AdMob כדי לאכלס את החבילה serverParameters כשיוצרים את המתאם.

קראו מאמר זה כדי לקבל מידע נוסף על האופן שבו בעלי אתרים יגדירו רשתות מודעות של גישור.

פרמטרים נוספים של טירגוט

התג MediationAdRequest מכיל מידע נפוץ על טירגוט שאפשר להשתמש בו לטירגוט מודעות, למשל:

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

תוספות לגישור

אם רשת המודעות שלכם תומכת בפרטי טירגוט שלא סופקו ב-MediationAdRequest, מפתחי האפליקציות יכולים להעביר חבילה של mediationExtras ספציפית לרשת שלכם. תהליך בחירת הרשת מספק דוגמה לאופן שבו מעבירים תוספות לתהליך בחירת הרשת.

כדי להקל על המפתחים להעביר את המידע הזה באופן אופציונלי, תוכלו לציין במתאם את סוג הכלי ליצירת חבילות. נניח שהרשת שלכם תומכת בהעברת ערך הכנסה. במתאם אפשר להוסיף מחלקה של builder שמגדירה את ההכנסה:

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 Mobile Ads עשוי להעביר הקשר של יישום למתאם שלך. אם המתאם לא יכול לטפל בהקשר של אפליקציה, מומלץ להפעיל את onAdFailedToLoad() עם קוד השגיאה AdRequest.ERROR_CODE_INVALID_REQUEST.

קריאות חוזרות (callback) של MediationBannerBannerListener

כדאי לשמור את התג MediationBannerListener שסופק לכם ב-requestBannerAd() כדי שתוכלו להעביר אירועי מודעות חזרה אל תהליך בחירת הרשת (Mediation) ב-Google Mobile Ads. יש להפעיל כל קריאה חוזרת בזמן המתאים במחזור החיים של המודעה:

שיטה	מתי להתקשר
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 באותה קריאה חוזרת. על אף שהקריאות החוזרות (callback) ברשת שלך לא תואמות בדיוק לקריאות החוזרות שנדרשות על ידי Google Mobile Ads, באחריות המתאם לספק מיפוי סביר.

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 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 כששולחים בקשה להצגת מודעה.

הערה: אל תשתמשו ב-adSize.getWidth() או ב-adSize.getHeight() כדי לקבל את גודל המודעה. מודעות באנר חכמות מיוצגות על ידי גודל פנימי קבוע, ולכן adSize.getWidth() ו-adSize.getHeight() מחזירים ערכים שליליים.

זהו! עכשיו יש לך מתאם פעיל לתהליך בחירת הרשת (Mediation) במודעות באנר. כאן אפשר למצוא יישום מלא של 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);
    }
}

אל תניחו שפרמטר ההקשר הוא מסוג Activity! מנגנון בחירת הרשת של Google Mobile Ads מעביר את ההקשר שהועבר על ידי מפתח האפליקציה, ויכול להיות שהוא מועבר. אם המתאם לא יכול לטפל בהקשר של אפליקציה, מומלץ להפעיל את onAdFailedToLoad עם קוד השגיאה AdRequest.ERROR_CODE_INVALID_REQUEST.

קריאות חוזרות (callback) של MediationInterstitialListener

כדאי לשמור את ה-MediationInterstitialListener שסופק לכם ב-requestInterstitialAd כדי שתוכלו להעביר אירועי מודעות חזרה אל 'תהליך בחירת הרשת (Mediation) של Google Mobile Ads'. יש להפעיל כל קריאה חוזרת בזמן המתאים במחזור החיים של המודעה:

שיטה	מתי להתקשר
onAdLoaded	בקשת המעברון הצליחה.
onAdFailedToLoad	בקשת המעברון נכשלה.
onAdOpened	מודעת המעברון מוצגת.
onAdClosed	מודעת המעברון נסגרה.
onAdLeftApplication	מודעת המעברון גורמת למשתמשים לצאת מהאפליקציה.

showInterstitial

אחרי שמתקשרים אל MediationInterstitialListener.onAdLoaded(), צריך להמתין עם הצגת מודעת המעברון עד שתתבצע קריאה ל-showInterstitial(). מפתח האפליקציה מחליט מתי להציג את מודעת המעברון, דבר שיכול להימשך כמה דקות אחרי שליחת הבקשה.

ההטמעה של showInterstitial() פשוטה למדי. פשוט מציגים את אובייקט המעברון:

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

אירועים במחזור החיים של הפעילות (מודעות מעברון)

מידע נוסף מופיע בקטע אירועים במחזור החיים של פעילות הבאנר.

לאחר הטמעת אירועי מחזור החיים של פעילות, מתאם תהליך בחירת הרשת מוכן לטיפול במודעות מעברון! כאן אפשר למצוא יישום מלא של SampleAdapter.

שאלות נפוצות

מה אפשר לעשות אם המתאם שלי תומך רק במודעות באנר או במודעות מעברון, אבל לא בשתיהן?

אם המתאם תומך רק במודעות באנר, צריך להטמיע רק את הממשק של MediationBannerAdapter. אם המתאם תומך רק במודעות מעברון, צריך רק להטמיע את הממשק MediationInterstitialAdapter.