הטמעה של מתאם למודעות מתגמלות

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

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

מדריך זה מיועד לרשתות מודעות שמעוניינות לבנות מתאם גישור למודעות מתגמלות לצורך גישור של מודעות Google לנייד. בקטעי הקוד שבהמשך נעשה שימוש ב-SDK לדוגמה למטרות הדגמה. אפשר למצוא הטמעה מלאה של מתאם שנוצרה עבור ה-SDK לדוגמה הזה בפרויקט Android תהליך בחירת הרשת. במדריך הזה מוסבר איך לבנות את המתאם.

הגדרת שם המחלקה של המתאם והפרמטרים של השרת

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

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

הטמעה של מחלקת מתאם

השלב הראשון הוא להטמיע את מחלקת המתאם:

...
import com.google.android.gms.ads.mediation.Adapter;
...

public class SampleAdapter extends Adapter {
 ...
}

השינוי הזה מבטיח שבכיתה שלך יוטמעו כמה שיטות שמפורטות בהמשך.

מספרי הגרסאות של הדוח

המתאם חייב לדווח ל-Google Mobile Ads SDK גם על גרסת המתאם עצמו וגם על גרסת ה-SDK של הצד השלישי. הגרסאות מדווחות באמצעות VersionInfo.

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

...
import com.google.android.gms.ads.VersionInfo;
...

public class SampleAdapter extends Adapter implements SampleRewardedAdListener {
  ...
  @Override
  public VersionInfo getVersionInfo() {
    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);
    }

    return new VersionInfo(0, 0, 0);
  }

  @Override
  public VersionInfo getSDKVersionInfo() {
    String versionString = SampleAdRequest.getSDKVersion();
    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);
    }

    return new VersionInfo(0, 0, 0);
  }
  ...
}

לאתחל את המתאם

כאשר אפליקציה מאתחלת את Google Mobile Ads SDK, initialize() מופעל בכל המתאמים שהוגדרו לאפליקציה בממשק המשתמש של AdMob.

הארגומנט List<MediationConfiguration> מספק מידע על כל המיקומים שהוגדרו לרשת המודעות שלכם בממשק המשתמש של AdMob. השתמשו במידע הזה כדי להפעיל את ה-SDK של רשת המודעות. לאחר האתחול של ה-SDK של רשת המודעות, דווחו על אתחול מוצלח או נכשל ל-Google Mobile Ads SDK על ידי הפעלת השיטה onInitializationSucceeded() או onInitializationFailed() בארגומנט InitializationCompleteCallback שסופק בקריאה ל-initialize().

...
import com.google.android.gms.ads.mediation.InitializationCompleteCallback;
import com.google.android.gms.ads.mediation.MediationConfiguration;
...

public class SampleAdapter extends Adapter {
  ...
  @Override
  public void initialize(
      Context context,
      InitializationCompleteCallback initializationCompleteCallback,
      List<MediationConfiguration> mediationConfigurations) {
    if (context == null) {
      initializationCompleteCallback.onInitializationFailed(
          "Initialization Failed: Context is null.");
      return;
    }

    // The Sample SDK doesn't have an initialization method, so this example
    // immediately reports a success callback.
    initializationCompleteCallback.onInitializationSucceeded();
  }
  ...
}

בקשה למודעה מתגמלת

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

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

...
import com.google.ads.mediation.sample.sdk.SampleAdRequest;
import com.google.ads.mediation.sample.sdk.SampleRewardedAd;
import com.google.ads.mediation.sample.sdk.SampleRewardedAdListener;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationRewardedAd;
import com.google.android.gms.ads.mediation.MediationRewardedAdCallback;
...

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...

  /**
   * A MediationAdLoadCallback that handles any callback when a Sample rewarded
   * ad finishes loading.
   */
  private MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> adLoadCallBack;

  /**
   * Represents a SampleRewardedAd.
   */
  private SampleRewardedAd sampleRewardedAd;

  /**
   * Used to forward rewarded video ad events to the Google Mobile Ads SDK..
   */
  private MediationRewardedAdCallback rewardedAdCallback;

  ...

  // Hold a reference to the MediationAdLoadCallback object to report ad load
  // events to the Google Mobile Ads SDK.
  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration mediationRewardedAdConfiguration,
      MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback>
          mediationAdLoadCallback) {
    adLoadCallBack = mediationAdLoadCallback;
    MediationRewardedAdConfiguration adConfiguration = mediationRewardedAdConfiguration;

    String adUnitId = adConfiguration.getServerParameters().getString(SAMPLE_AD_UNIT_KEY);

    sampleRewardedAd = new SampleRewardedAd(adUnitId);
    SampleAdRequest request = new SampleAdRequest();
    sampleRewardedAd.setListener(this);
    sampleRewardedAd.loadAd(request);
  }

  // Hold a reference to the MediationRewardedAdCallback object to report ad
  // lifecycle events to the Google Mobile Ads SDK.
  @Override
  public void onRewardedAdLoaded() {
    rewardedAdCallback = mediationAdLoadCallBack.onSuccess(this);
  }

  @Override
  public void onRewardedAdFailedToLoad(SampleErrorCode error) {
    mediationAdLoadCallBack.onFailure(error.toString());
  }
  ...
}

הצגת המודעה

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

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...
  @Override
  public void showAd(Context context) {
    if (!(context instanceof Activity)) {
      rewardedAdCallback.onAdFailedToShow(
          "An activity context is required to show Sample rewarded ad.");
      return;
    }
    Activity activity = (Activity) context;

    if (!sampleRewardedAd.isAdAvailable()) {
      rewardedAdCallback.onAdFailedToShow("No ads to show.");
      return;
    }
    sampleRewardedAd.showAd(activity);
  }
  ...
}

דיווח על אירועי מודעות ל-Mobile Ads SDK

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

בדרך כלל, השיחות החוזרות (callback) האלה מועברות משיטות של קריאה חוזרת (callback) שמופעלות על ידי ה-SDK של רשת המודעות. בדוגמה הזו מוטמעת Sample SDK את הקריאה החוזרת (callback) וממפות אותה לקריאות החוזרות (callback) שזמינות ב-MediationRewardedAdCallback.

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...
  @Override
  public void onAdRewarded(final String rewardType, final int amount) {
    RewardItem rewardItem =
        new RewardItem() {
          @Override
          public String getType() {
            return rewardType;
          }

          @Override
          public int getAmount() {
            return amount;
          }
        };
    rewardedAdCallback.onUserEarnedReward(rewardItem);
  }

  @Override
  public void onAdClicked() {
    rewardedAdCallback.reportAdClicked();
  }

  @Override
  public void onAdFullScreen() {
    rewardedAdCallback.onAdOpened();
    rewardedAdCallback.onVideoStart();
    rewardedAdCallback.reportAdImpression();
  }

  @Override
  public void onAdClosed() {
    rewardedAdCallback.onAdClosed();
  }

  @Override
  public void onAdCompleted() {
    rewardedAdCallback.onVideoComplete();
  }
  ...
}

בהמשך מופיעים אירועי המודעות שמדווחים ל-Google Mobile Ads SDK:

אירוע מודעה	התיאור
onAdOpened()	מודיע ל-Google Mobile Ads SDK שהמודעה תיפתח.
onVideoStart()	מודיע ל-Google Mobile Ads SDK שמודעה מתגמלת התחילה לפעול.
reportAdImpression()	מודיע ל-Google Mobile Ads SDK שהתקבלה חשיפה במודעה.
onVideoComplete()	מודיע ל-Google Mobile Ads SDK שהמודעה המתגמלת הפסיקה לפעול.
onUserEarnedReward()	תודיע ל-Google Mobile Ads SDK שהמשתמש הרוויח פרס.
reportAdClicked()	מודיע ל-Google Mobile Ads SDK שבוצע קליק על המודעה.
onAdClosed()	מודיע ל-Google Mobile Ads SDK שהמודעה נסגרה.
onAdFailedToShow()	מודיע ל-Google Mobile Ads SDK שהמודעה לא הוצגה.