ב-Google Mobile Ads SDK יש תמיכה גם בסגנונות מותאמים אישית של המודעות בחיפוש. אם באפליקציה שלכם כבר נעשה שימוש ב-Google Mobile Ads SDK, מומלץ להשתמש במקום זאת בגרסה של AFSMA SDK.
אם אתם משדרגים לגרסה 19.0.0 ואילך מ-18.1.0 ואילך, תוכלו לעיין במדריך להעברת נתונים (מיגרציה).
דרישות מוקדמות
מדריך ההטמעה הזה מבוסס על ההנחה שאתם מכירים את:
- מודעות לרשת החיפוש בהתאמה אישית של AdSense עם סגנונות מותאמים אישית של המודעות בחיפוש
- פיתוח אפליקציות ל-Android
מייבאים את ה-SDK המקורי של AFS
הוספת ה-SDK
כדי להוסיף לאפליקציה את ה-SDK המקורי של AFS:
פותחים את הקובץ build.gradle
בספרייה של מודול האפליקציה.
יש להוסיף כלל build חדש בקטע dependencies
לגרסה העדכנית של ה-SDK:
dependencies {
implementation 'com.google.android.gms:play-services-afs-native:19.1.0'
}
מוודאים שה-build.gradle
ברמה העליונה מכיל הפניה למאגר google()
או ל-maven { url "https://maven.google.com" }
.
צריך לפעול לפי ההוראות האלה כדי לכלול בפרויקט את פלאגין Google Play Standalone Version Matcher.
החלה של הפלאגין הזה גורמת לשגיאת build ברמת גרסה נמוכה יותר כשנעשה שימוש ב-SDK המקורי של AFS בשילוב עם גרסה לא תואמת של Google Play Services במקום לאפשר לאפליקציה לפתח את האפליקציה, אך באופן פוטנציאלי עלול לגרום לקריסות בזמן הריצה. לחלופין, אפשר להחיל את failOnVersionConflict()
ResolutionStrategy על הפרויקט כדי לגרום לשגיאת build כשנעשה שימוש בפרויקט בגרסאות לא תואמות של שירותי Google Play.
שומרים את השינויים ולוחצים על Sync Project with Gradle Files בסרגל הכלים.
שימוש ב-AndroidX במקום בספריות תמיכה של Android
החל מגרסה 17.0.0
של ה-SDK, באפליקציה צריך להשתמש בספריות Jetpack (AndroidX) במקום בספריות תמיכה של Android. דרישות תאימות:
- צריך להגדיר את
com.android.tools.build:gradle
לגרסה 3.2.1 ואילך. - צריך להגדיר את
compileSdkVersion
לערך 28 ואילך. - מעדכנים את האפליקציה כדי להשתמש ב-Jetpack (AndroidX). פועלים לפי ההוראות במאמר העברה ל-AndroidX.
מחלקות
כדי להציג באפליקציה מודעות מותאמות של AdSense לחיפוש (AFS), צריך להטמיע את הסוגים הבאים:
- הכיתה הזו אחראית לשליחת מודעות באופן אסינכרוני, לשמירה במטמון ולאחזור של מודעות ולרינדור של מודעות.
- לכל הקשר של מודעה צריך להוסיף
SearchAdController
נפרד. לדוגמה, אם יש לכם מסך שבו מוצגות מודעות לצד רשימה של תוצאות חיפוש ומסך נוסף שבו מוצגות מודעות לצד הפרטים על מוצר ספציפי, כדאי ליצור שני מופעים נפרדים שלSearchAdController
– אחד לכל מקרה. - ה-constructor צריך לספק את קוד נכס האינטרנט (מזהה בעל האתר), מזהה הסגנון כדי להחיל אותו על המודעות שמוחזרות, וגם את
SearchAdOptions
. הערךContext
שמצוינת ב-constructor חייב להיותActivity
שמכיל אתSearchAdController
, ושבו תציב את המודעהView
. - קוראים לפונקציה
loadAds
כדי לציין חיפוש חדש של משתמש ולשלוח בקשה אסינכרונית להצגת מודעה. מודעות שנטענות מקריאות קודמות ל-loadAds
נמחקות מהמטמון הפנימי של מודעות כשמתבצעת קריאה חדשה. - כדי להציג נכסי קריאייטיב של מודעות, צריך ליצור
View
עםcreateAdView
. - אחרי שהמודעות נטענות, צריך לקרוא לפונקציה
populateAdView
עםView
שנוצר בעבר באמצעותcreateAdView
כדי לעבד מודעה שנשמרה במטמוןView
. בנוסף ל-View
שאמור להופיע, צריך לספקadKey
, מחרוזת שרירותית כדי לזהות את המודעה באופן ייחודי. הפעולה הזו משייכת את הקריאייטיב הספציפי של המודעה שמוחזר מהמטמון אל אותוadKey
, כך שכשאותוadKey
מועבר לקריאה עתידית ל-populateAdView
, אותה מודעה תוחזר. לדוגמה, אם מתבצעת קריאה אלpopulateAdView
בפעם הראשונה באמצעותadKey="keyA"
ורינדור מודעה לנעלי הליכה, כל קריאה נוספת ל-populateAdView
עםadKey="keyA"
יאכלס את אותה מודעה עבור נעלי הליכה. (ביצוע קריאה חדשה ל-loadAds
מנקה את כל המודעות שנשמרו במטמון ואת מפתחות המודעות המשויכים).
- כדי להתאים אישית את האופן שבו מוצגות בקשות להצגת מודעות, מעבירים את האובייקט הזה ל-constructor של
SearchAdController
. קוראים לפונקציהbuild()
ב-SearchAdOptions.Builder
כדי ליצור אובייקטSearchAdOptions
.
View
- יוצרים אובייקט
View
כדי להחזיק מודעות על ידי קריאה ל-createAdView()
ב-SearchAdController
. מציגה לכל היותר מודעה אחת בכל פעם, אבל ניתן למחזר את אותוView
כדי להציג מודעות שונות לאורך זמן.
- קוראים ל-method
loadAds
ב-SearchAdController
עםSearchAdRequest
כדי לשלוח בקשה להצגת מודעה אסינכרונית. קוראים לפונקציהbuild()
ב-SearchAdRequest.Builder
כדי ליצור אובייקטSearchAdRequest
.
- כדי לרשום קריאות חוזרות (callback) במספר מצבים, צריך להטמיע את הממשק הזה ולהעביר אותו ל-constructor של
SearchAdController
. - הערה: לא תתבצע קריאה חוזרת (callback) של
AdListener
בבקשה שבוטלה (קריאה ל-loadAds
שבוצעה על ידי קריאה אחרת ל-loadAds
לפני שהקריאה הראשונה נפתרה).
הטמעה לדוגמה
הדוגמה הבאה ממחישה איך ליצור SearchAdController
בדוגמה Activity
.
// MainActivity.java implementation
// (MainActivity is a subclass of Activity)
SearchAdController adController;
// adContainer where we will place our ads in this example.
ViewGroup adContainer;
protected void onCreate(Bundle bundle){
super.onCreate(bundle);
adContainer = (ViewGroup) findViewById(...);
// Specify ad options (not required).
SearchAdOptions.Builder adOptionsBuilder = new SearchAdOptions.Builder();
adOptionsBuilder.setAdType(SearchAdOptions.AD_TYPE_TEXT);
adOptionsBuilder.setPrefetch(true);
adOptionsBuilder.setNumAdsRequested(3);
// Provide a callback to trigger when ads are loaded.
AdListener adListener = new AdListener() {
public void onAdLoaded() {
createAndShowAd();
}
};
// Instantiate the SearchAdController.
adController = new SearchAdController(this, "your-client-id", "your-style-id",
adOptionsBuilder.build(), adListener);
}
כשהמשתמש יוזם שאילתה, צריך ליצור SearchAdRequest
ולקרוא ל-loadAds
ב-SearchAdController
כדי להתחיל בקשה אסינכרונית להצגת מודעה.
// Create the request.
SearchAdRequest.Builder requestBuilder = new SearchAdRequest.Builder();
requestBuilder.setQuery("user query here");
// Load the ads.
adController.loadAds(requestBuilder.build());
יישום הקריאה החוזרת (callback) של onAdLoaded
כדי לאכלס מודעה שנטענה בצפייה במודעה.
private void createAndShowAd() {
// Create a new view that will contain the ad.
View adView = adController.createAdView();
// Attach the new view to the view hierarchy.
adContainer.addView(adView);
// Display the ad inside the adView. We need to provide an adKey to
// indicate which ad is to be displayed in the adView. In this example,
// since we only have one ad, we can provide any constant string. However,
// if you intend to display multiple ads, each ad you wish to display
// should be given a unique adKey of your choosing.
adController.populateAdView(adView, "demoAd");
}
מודעה שקשורה לשאילתה הנתונה תופיע עכשיו בadView
.
איך בודקים שגיאות
השימוש SearchAdController
מחייב אובייקט AdListener
עם השיטה onAdLoaded()
כדי להודיע לאפליקציה שהמודעות מוכנות להצגה. כדאי גם להטמיע את השיטה onAdFailedToLoad()
כדי לזהות ולתקן שגיאות.
לדוגמה, אפשר להשתמש בפקודות AdListener
הבאות כדי לנפות באגים בהטמעה:
AdListener adListener = new AdListener() {
public void onAdLoaded() {
// Called when an ad is loaded.
Toast.makeText(MainActivity.this, "Ad Loaded",
Toast.LENGTH_SHORT).show();
Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
}
public void onAdLeftApplication() {
// Called when an ad leaves the application
// (to go to the browser for example).
Toast.makeText(MainActivity.this, "Ad Left Application",
Toast.LENGTH_SHORT).show();
Log.d(MainActivity.class.getSimpleName(), "Ad Left Application");
}
@Override
public void onAdFailedToLoad(int errorCode) {
// Called when an ad request failed.
Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
Toast.LENGTH_SHORT).show();
Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
errorCode);
}
};
קבועים שבהם נעשה שימוש בשיטת הקריאה החוזרת של onAdFailedToLoad()
מוגדרים ב-AdListener.