הטמעה מותאמת של AdSense לחיפוש (AFS) ל-Android

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.0.3'
}

ודאו שה-build.gradle ברמה העליונה מכיל הפניה למאגר google() או ל-maven { url "https://maven.google.com" }.

יש לפעול לפי ההוראות האלה כדי לכלול בפרויקט את הפלאגין 'התאמת גרסאות עצמאיות' של Google Play. שימוש בפלאגין הזה גורם לשגיאת build הדרגתית כאשר משתמשים ב-AFS Native SDK עם גרסה לא תואמת של Google Play Services במקום לאפשר לאפליקציה לפתח את האפליקציה, אבל עלול לגרום לקריסות בזמן הריצה. לחלופין, אפשר להחיל על הפרויקט את השיטה failOnVersionConflict() ResolutionStrategy כדי לגרום לשגיאת build כשמשתמשים בגרסאות לא תואמות של שירותי Google Play בפרויקט. שומרים את השינויים ולוחצים על Sync Project with Gradle Files (סנכרון הפרויקט עם 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 נפרד. לדוגמה, אם יש מסך שמציג מודעות לצד רשימה של תוצאות חיפוש, ומסך נוסף שמציג מודעות לצד פרטים לגבי מוצר ספציפי, עליך ליצור שני מופעים נפרדים של SearchAdController, אחד לכל מקרה.
• עליכם לספק ל-builder את קוד נכס האינטרנט (מזהה בעל האתר), את מזהה הסגנון כדי להחיל על המודעות המוחזרות, ואת SearchAdOptions. הערך Context שצוין במבנה חייב להיות Activity שמכיל את SearchAdController והמקום שבו תציבו את המודעה View.
• התקשרו אל loadAds כדי לציין חיפוש של משתמש חדש וליזום בקשה אסינכרונית להצגת מודעה. כל המודעות שנטענו משיחות קודמות אל loadAds נמחקות מהמטמון הפנימי של המודעות כשמתבצעת שיחה חדשה.
• כדי להציג קריאייטיבים של מודעות, צריך ליצור View עם createAdView.
• אחרי טעינת המודעות, צריך להפעיל את populateAdView עם View שנוצר בעבר באמצעות createAdView, כדי לעבד מודעה שנשמרה במטמון אל View. בנוסף ל-View שצריך לאכלס, צריך לספק adKey, מחרוזת שרירותית, שתאפשר לזהות את המודעה באופן ייחודי. הפעולה משייכת את הקריאייטיב של המודעה הספציפית שמוחזר מהמטמון לאותו adKey, ולכן כשאותו adKey מועבר לקריאה עתידית אל populateAdView, אותה מודעה תוחזר. לדוגמה, אם populateAdView מופעל בפעם הראשונה באמצעות adKey="keyA" ויוצרת מודעה שמפרסמת נעלי הליכה, כל קריאה נוספת ל-populateAdView עם adKey="keyA" תאכלס את אותה מודעה לנעלי הליכה. (ביצוע קריאה חדשה אל loadAds מנקה את כל המודעות שנשמרו במטמון ואת המפתחות המשויכים למודעות).

SearchAdOptions

• מעבירים את האובייקט הזה לבנאי SearchAdController כדי להתאים אישית את אופן הבקשה וההצגה של מודעות. קוראים לפונקציה build() ב-SearchAdOptions.Builder כדי ליצור אובייקט SearchAdOptions.

View

• כדי ליצור אובייקט View להשהיית מודעות, קוראים ל-createAdView() ב-SearchAdController. מציגה רק מודעה אחת בכל פעם, אבל אפשר למחזר את אותו View כדי להציג מודעות שונות לאורך זמן.

SearchAdRequest

• צריך להפעיל את השיטה loadAds ב-SearchAdController עם SearchAdRequest כדי ליזום בקשה אסינכרונית להצגת מודעה. קוראים לפונקציה build() ב-SearchAdRequest.Builder כדי ליצור אובייקט SearchAdRequest.

AdListener

• מטמיעים את הממשק ומעבירים אותו ל-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.