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

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

אם אתם משדרגים לגרסה 19.0.0 ואילך מ-18.1.0 או מגרסה קודמת, כדאי לעיין במאמר הבא: המדריך להעברת נתונים (מיגרציה).

דרישות מוקדמות

במדריך הזה אנחנו יוצאים מנקודת הנחה שאתם מכירים את הנושאים הבאים:

• מודעות לרשת החיפוש בהתאמה אישית של AdSense עם סגנונות חיפוש מותאמים אישית
• פיתוח אפליקציות ל-Android

ייבוא של AFS Native SDK

הוספת ה-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 לזיהוי גרסאות עצמאיות בפרויקט. החלת הפלאגין הזה גורמת לשגיאה ב-build של Gradle כשמשתמשים ב-AFS Native SDK עם גרסה לא תואמת של Google Play Services, במקום לאפשר את ה-build של האפליקציה אבל עלולה לגרום לקריסות בסביבת זמן הריצה. לחלופין, אפשר להחיל את failOnVersionConflict() ResolutionStrategy על הפרויקט כדי לגרום לשגיאת build כשמשתמשים בגרסת Google Play Services לא תואמת בפרויקט. שומרים את השינויים ולוחצים על Sync Project with Gradle Files (סנכרון הפרויקט עם קובצי Gradle) את סרגל הכלים.

שימוש ב-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 את קוד נכס האינטרנט (מזהה בעל האתר), style ID שעליו רוצים להחיל החזירו מודעות, ו-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

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

View

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

SearchAdRequest

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

AdListener

• מטמיעים את הממשק הזה ומעבירים אותו למבנה SearchAdController כדי לרשום פונקציות קריאה חוזרת לכמה מצבים.
• הערה: AdListener לא יתבצעו קריאות חוזרות (callback) אם הבקשה בוטלה (שיחה אל 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);
    }
};

קבועים שבהם נעשה שימוש בשיטת הקריאה החוזרת (callback) של onAdFailedToLoad() מוגדרים ב-AdListener.