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

המדריך הזה מיועד לרשתות מודעות שרוצות ליצור מתאם בידינג כדי להשתתף בבידינג בזמן אמת (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 ואילך: בזמן שהמודעה מוצגת, צריך להודיע ל-Google Mobile Ads SDK על אירועי חשיפה וקליקים, וגם על אירועים אחרים שקשורים למודעה שמתרחשים במהלך מחזור החיים של הצגת המודעה.

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

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

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

@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 שולחת בקשות לאותות מכל המתאמים שמשתתפים בבידינג בו-זמנית. במהלך הזמן הזה, חשוב לשמור על נימוס ולהגביל את השיחות ל-UI thread. כל פעולה כבדה שהמתאם או ה-SDK צריכים לבצע כדי לאסוף אותות צריכה להתבצע בשיטה initialize() ולהישמר במטמון.

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

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

@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()

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

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

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

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

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

השיטה mediationAdLoadCallback.onSuccess() מחייבת להעביר אליה אובייקט שתואם לאחד מממשקי Ad שמוגדרים על ידי 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 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() המשתמש מקבל תגמול.
קריאות חוזרות (callback) של וידאו (מודעות מתגמלות ומותאמות)
onVideoStarted() הסרטון של המודעה התחיל.
onVideoCompleted() הצפייה בסרטון של המודעה הסתיימה.

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

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

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

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

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

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

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

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