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

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

View

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

SearchAdRequest

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

AdListener

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