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

SearchAdOptions

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

View

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

SearchAdRequest

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

AdListener

• כדי לרשום קריאות חוזרות (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.