פיתוח מתאם בידינג

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

מתאם בידינג הוא החלק בצד הלקוח של השילוב. המתאם מאפשר ל-SDK של רשת המודעות לתקשר עם Google Mobile Ads SDK כדי לטעון מודעות שהוצגו על ידי מגיש הצעות המחיר.

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

תהליך עבודה של מתאם בידינג

אתחול

כאן מוצגת זרימה מפורטת של כל מחזור החיים של מתאם בין עיבוד בקשה-תגובה:

המתאם אחראי לחלקים הבאים בתהליך העבודה:

  • שלבים 4-7: מפעילים את המתאם וקוראים שוב ל-Google Mobile Ads SDK בסיום האתחול.

  • שלבים 10-13: איסוף אותות מה-SDK של רשת המודעות שיישלחו למגיש הצעות המחיר כדי שישתתף בבקשת RTB, והעברה שלהם אל Google Mobile Ads SDK.

  • שלבים 18-21: אם מגיש הצעות המחיר יחזיר את הצעת המחיר הזוכה, צריך לטעון את המודעה בהתאם לתגובת מגיש הצעות המחיר. לאחר הטעינה, דווחו ל-Google Mobile Ads SDK שהמודעה נטענה.

  • שלב 23 ואילך: בזמן שהמודעה מוצגת, עדכנו את ה-SDK של מודעות Google לנייד לגבי אירועי חשיפות וקליקים, וכן לגבי אירועים אחרים של מודעות שמתרחשים במחזור החיים של המודעה.

הטמעה של מתאם הבידינג

כדי ליצור מתאם בידינג ל-Google Mobile Ads SDK, צריך להרחיב את מחלקת המופשט RtbAdapter. הקטעים הבאים מסבירים כל שיטה מופשטת ב-RtbAdapter.

getSDKVersionInfo()

כאן עליך להחזיר את גרסת ה-SDK שלך. הגרסה הזו מועברת למגיש הצעות המחיר כחלק מבקשת OpenRTB.

בשיטה הזו עליך להחזיר VersionInfo. בדוגמה הבאה אפשר לראות איך ממירים את גרסת המחרוזת של ה-SDK ל-VersionInfo.

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

כאן עליך להחזיר את גרסת המתאם. הגרסה הזו מועברת למגיש הצעות המחיר כחלק מבקשת OpenRTB.

המתאמים לגרסאות של הקוד הפתוח של Google משתמשים בסכמת גרסאות מתאמים של 4 ספרות, אבל ב-VersionInfo אפשר להזין רק 3 ספרות. כדי לעקוף את הבעיה, מומלץ לשלב את שתי הספרות האחרונות בגרסת התיקון, כפי שמוצג בהמשך.

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

initialize()

הזמן הקצוב לתפוגה: 30 שניות

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

אחרי שה-SDK מופעל ומוכן לקבלת בקשות להצגת מודעות, צריך להפעיל את השיטה onInitializationSucceeded() של InitializationCompleteCallback. הקריאה החוזרת (callback) תועבר לבעלי האפליקציות כדי שהם ידעו שהם יכולים להתחיל לטעון מודעות.

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

זמן קצוב לתפוגה: שנייה אחת

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

בוצעה קריאה ל-collectSignals() בשרשור ברקע. ה-Google Mobile Ads SDK מבקש אותות מכל המתאמים שמשתתפים בבידינג. חשוב להתנהג בכבוד ולהגביל את הקריאות ל-thread של ממשק המשתמש במהלך התקופה הזו. כל העבודה הקשה שהמתאם או ה-SDK צריכים לבצע כדי לאסוף אותות צריך להתבצע בשיטה initialize() ולשמור אותה במטמון.

כשהאותות מוכנים, מפעילים את הקריאה החוזרת (callback) של onSuccess() באמצעות האותות המקודדים.

דוגמה להטמעה:

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

אם המתאם לא מצליח לאסוף אותות, מפעילים את signalCallbacks.onFailure() בצירוף מחרוזת שמסבירה את השגיאה שאירעה.

הטמעה של שיטות לטעינת מודעות

זמן קצוב לתפוגה: 10 שניות

אם מגיש הצעות המחיר מחזיר את הצעת המחיר שזכתה, מערכת Google Mobile Ads SDK קוראת למתאם כדי לטעון את המודעה הזוכה, ומעבירה לכם את כל הנתונים שמגיש הצעות המחיר החזיר ל-SDK שלכם כדי לטעון את המודעה.

שיטת הטעינה המדויקת שמופעלת תלויה בפורמט המודעה שעבורו מיועדת הבקשה:

פורמט מודעה שיטת טעינה
כרזה loadBannerAd()
פרסומת מרווח ביניים loadInterstitialAd()
ההטבה הופעלה loadRewardedAd()

יישם את השיטות האלה בפורמטים של מודעות שנתמכים במתאם שלך.

שיטת הטעינה מופעלת ב-thread של ממשק המשתמש, באותה מכונה של המתאם שממנו סיפקתם את האותות. השיטה הזו מספקת את הפרמטרים הבאים:

  • MediationAdConfiguration, שכולל פרמטרים שה-SDK צריך לטעון בו את המודעה עבור הצעת המחיר הזוכה. למשל, התגובה להצעת המחיר וכל פרטי הכניסה שבעל האפליקציה הגדיר בממשק המשתמש של AdMob.

  • אובייקט MediationAdLoadCallback המשמש לקבלת התראה ל-Google Mobile Ads SDK כשהטעינה מצליחה או נכשלת.

לאחר שה-SDK יטען את המודעה, יש להתקשר אל mediationAdLoadCallback.onSuccess(). כשטעינת המודעה באירוע נכשלה, צריך לבצע קריאה ל-mediationAdLoadCallback.onFailure() עם מחרוזת שמסבירה את השגיאה שהתרחשה.

השיטה mediationAdLoadCallback.onSuccess() דורשת העברה באובייקט שמאשר לאחד מממשקי ה'מודעה' שהוגדרו על ידי Google Mobile Ads SDK. ממשקי המודעות האלה מבקשים מכם לספק מידע מסוים לגבי המודעה.

ב-MediationAdConfiguration יש גם את השיטה getWatermark() כדי להחזיר מחרוזת בקידוד base64 שמייצגת תמונה בפורמט PNG. את התמונה הזו צריך להציג כשכבת-על שקופה במודעות. כדי לקבל הנחיות נוספות לרינדור של סימן המים, אפשר לפנות ל-Google. הוא מכיל מטא-נתונים לגבי המודעה המוצגת לשימוש על ידי בעלי אתרים, כדי לקבוע את המקור של המודעות שיוצגו.

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

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

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to the Google Mobile Ads SDK.
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

אירועים במחזור החיים של הצגת המודעות באמצעות שרת ממסר

האחריות הסופית של המתאם היא להודיע ל-Google Mobile Ads SDK על כל אירוע במחזור החיים של המצגת, כדי שניתן יהיה להעביר אותם לבעל האתר. בעל האתר מצפה להתקשרות חזרה בזמנים מסוימים, ללא קשר לרשת המודעות שמציגה את המודעה, ולכן חשוב להפעיל כמה שיותר מהקריאות החוזרות האלה, בזמן הנכון, כדי ש-Google Mobile Ads SDK יוכל להעביר אותן לבעל האתר.

המתאמים צריכים להפעיל את האירועים הבאים במקרים הרלוונטיים:

משותף לכל הפורמטים
שיטה מתי להתקשר
reportAdClicked() בוצעה לחיצה על המודעה.
reportAdImpression() המודעה עיבדה חשיפה.
onAdOpened() המודעה הוצגה במסך מלא.
onAdClosed() תצוגת המסך המלא של המודעה נסגרה.
onAdLeftApplication() המודעה גרמה למשתמש לעזוב את האפליקציה.
מודעות מתגמלות
onRewarded() המשתמש מקבל תגמול.
התקשרות חזרה בווידאו (מודעות מתגמלות ומודעות מותאמות)
onVideoStarted() הסרטון של המודעה התחיל.
onVideoCompleted() הסרטון של המודעה הושלם.

המתאם מקבל אובייקט MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> בקריאה ל-mediationAdLoadCallback.onSuccess(). המתאמים צפויים להיאחז באובייקט הזה ולהשתמש בו כדי להפעיל אירועי מצגת שמתרחשים במודעה שלכם.

בדרך כלל, רוב האירועים האלה שייכים ל-SDK של רשת המודעות. תפקיד המתאם הוא למפות את הקריאות החוזרות מ-SDK של רשת המודעות אל Google Mobile Ads SDK.

הדוגמה הבאה ממחישה איך מעבירים קריאות חוזרות (callback) מ-SDK של ה-SDK ל-Google Mobile Ads SDK:

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

הנכסים הנדרשים למעקב אחר חשיפות של מודעות מותאמות

Google Mobile Ads SDK מתעדת חשיפה של מודעה מותאמת כאשר פיקסל אחד של המודעה מופיע. אם ל-SDK של רשת המודעות נדרש הצגה של נכסים ספציפיים כדי ליצור חשיפה חוקית, מגיש הצעות המחיר יכול לציין בתגובה את הצעת המחיר לנכסים מותאמים נדרשים. לאחר מכן, ה-SDK של מודעות Google לנייד מאמת שהנכסים המותאמים שנדרשים מוצגים לפני התיעוד של חשיפה.

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

הצגת שגיאות במודעות

כשמשתמשים בפורמטים של מסך מלא, כמו מודעות מעברון ומודעות מתגמלות, בטעינת הקריאה החוזרת יש הטמעה של MediationInterstitialAd או MediationRewardedAd כדי לאפשר ל-Google Mobile Ads SDK לבקש מהמתאם להציג את המודעה.

ה-Google Mobile Ads SDK מצפה שאם מתאם טען מודעה בהצלחה, המודעה תהיה מוכנה להצגה כשבעל האתר יבקש להציג אותה. כלומר, כל קריאה לתוכנית צריכה להוביל לחשיפה.

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

בטבלה הבאה אפשר לראות איך הקריאות החוזרות למצגת משפיעות על תיעוד החשיפות בפורמטים של מודעות במסך מלא:

התקשרות חזרה תוצאה
onAdOpened() Impression recorded
onAdFAILEDToShow() Impression failure1
אף אחת מהאפשרויות האלה במשך כמה שניות Impression recorded

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

הדוגמה הבאה ממחישה את מחזור החיים של טעינה/תוכנית, שבו קריאה להצגת מודעות עשויה לגרום לתקלה.

final class SampleRtbAdapter extends RtbAdapter implements MediationRewardedAd {

 private MediationRewardedAdCallback callback;
 private RewardedAd rewardedAd;

 ...

  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration adConfiguration,
      final MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> loadCallback) {

    // Load an ad. This mock example uses Google's SDK, but in practice
    // your adapter will load the ad using your ad network's SDK.
    RewardedAd.load(adConfiguration.getContext(),
        "ca-app-pub-3940256099942544/5224354917",
        new AdRequest.Builder().build(),
        new RewardedAdLoadCallback() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // When the ad loads, invoke the load success callback.
            callback = loadCallback.onSuccess(SampleRtbAdapter.this);
          }
        });
  }

  @Override
  public void showAd(Context context) {
    // In this mock example, your ad network requires an activity context, but
    // didn't receive one, making you unable to show the ad.
    if (!(context instanceof Activity)) {
      AdError error = new AdError(1, "Context must be an activity",
          "com.google.ads.mediation.sample");
      callback.onAdFailedToShow(error);
    }

    // This example shows Google SDK's callbacks, but it's likely your SDK
    // has similar presentation callbacks.
    rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Your ad network SDK successfully showed the ad. Call onAdOpened().
        callback.onAdOpened();
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Your ad network SDK failed to show the ad, invoke onAdFailedToShow.
        // In practice, you will map your SDK's error to an AdError.
        AdError error = new AdError(adError.getCode(), adError.getMessage(),
            adError.getDomain());
        callback.onAdFailedToShow(adError);
      }
    });


    rewardedAd.show((Activity) context, ...);
  }
}