המדריך הזה מיועד לרשתות מודעות שמעוניינות לבנות מתאם לבידינג כדי להשתתף בבידינג בזמן אמת (RTB) בתהליך בחירת הרשת (Mediation) של Google. אם הם בעלי אתרים, ראו תהליך בחירת הרשת (Mediation) של בעלי תוכן דיגיטלי. הוראות להתאמה אישית.
מתאם בידינג הוא החלק בצד הלקוח של השילוב. המתאם שמאפשר ל-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 שניות
ה-method initialize() היא ה-method הראשונה שנקראת במתאם. זה כן
את קריאה אחת בלבד בכל סשן. שיטה זו מספקת רשימה של
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 מבקש בו-זמנית אותות מכל המתאמים
שמשתתפים בבידינג. יש להתנהל בצורה מכבדת ולהגביל קריאות לשרשורים ב-UI
בפרק הזמן הזה. כל העבודה הקשה שהמתאם או ה-SDK צריכים לבצע כדי לאסוף
צריך לבצע את האותות בשיטה initialize() ולשמור אותם במטמון.
אחרי שהאותות יהיו מוכנים, צריך להתקשר למוקד של 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 של אירועים במחזור החיים של המצגת, כך שניתן יהיה להעביר אותם מו"ל. בעל התוכן הדיגיטלי מצפה לקריאות החוזרות האלה בשעות מסוימות, ללא קשר איזו רשת מודעות מציגה את המודעה, לכן חשוב שכמה שיותר כמה שיותר קריאות חוזרות (callback) ובזמן הנכון, כדי ש-Google ערכת ה-SDK של Mobile Ads SDK יכולה להעביר אותן לבעל האפליקציה.
המתאמים צריכים להפעיל את האירועים הבאים, כשזה רלוונטי:
| משותף לכל הפורמטים | |
|---|---|
| שיטה | מתי להתקשר |
reportAdClicked()
|
בוצע קליק על המודעה. |
reportAdImpression()
|
המודעה קיבלה חשיפה. |
onAdOpened()
|
במודעה הוצגה תצוגת מסך מלא. |
onAdClosed()
|
תצוגת המודעה במסך מלא נסגרה. |
onAdLeftApplication()
|
המודעה גרמה למשתמש לצאת מהאפליקציה. |
| מודעות מתגמלות | |
onRewarded()
|
המשתמש קיבל פרס. |
| התקשרות חזרה בווידאו (מודעות מתגמלות ומודעות מותאמות) | |
onVideoStarted()
|
הסרטון של המודעה התחיל. |
onVideoCompleted()
|
הסרטון של המודעה הושלם. |
המתאם מקבל MediationAdLoadCallback<MediationAdT, MediationAdCallbackT>
את האובייקט בחזרה אחרי הקריאה ל-mediationAdLoadCallback.onSuccess(). המתאמים הם
צפויה להחזיק את האובייקט הזה ולהשתמש בו כדי להפעיל אירועי מצגת
שקורים במודעה.
בדרך כלל, רוב האירועים האלה נובעים מ-SDK של רשת המודעות. תפקיד המתאם הוא פשוט למפות את הקריאות החוזרות מה-SDK של רשת המודעות Google Mobile Ads 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 של רשת המודעות דורש הצגה של נכסים ספציפיים כדי לקבל חשיפה תקינה, מגיש הצעות המחיר יכול לציין נכסים מותאמים בתגובה להצעת המחיר. לאחר מכן Google Mobile Ads SDK מבצע אימות שהנכסים המותאמים הנדרשים מוצגים לפני תיעוד חשיפה.
לעיון בנכסים המותאמים הנדרשים תיעוד עבור מידע נוסף על ציון נכסים נדרשים נוספים בהצעת המחיר תשובה.
הצגת שגיאות במודעות
כשמדובר בפורמטים של מסך מלא, כמו מודעות מעברון ומודעות מתגמלות
של הקריאה החוזרת (callback) של האפליקציה,
MediationInterstitialAd
או MediationRewardedAd
כדי ש-Google Mobile Ads SDK יוכל לבקש מהמתאם שלכם להציג את המודעה.
Google Mobile Ads SDK מצפה שאם המתאם יטען מודעה בהצלחה, המודעה מוכנה להצגה כשבעל האתר מבקש להציג אותה. המשמעות היא כל קריאה לתוכנית אמורה להוביל לחשיפה.
עם זאת, ייתכן שיהיו מקרים בפינות שבהם לא תוכלו להציג מודעה. אם
לא יכול להציג את המודעה,
onAdFailedToShow()
קריאה חוזרת (callback) כדי לבטל את החשיפה.
בטבלה הבאה אפשר לראות איך קריאות חוזרות (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, ...);
}
}