تنفيذ "AdSense للبحث" الأصلي على نظام التشغيل Android

تتوافق حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" أيضًا مع أنماط البحث المخصّصة. إذا كان تطبيقك حزمة SDK لإعلانات Google على الأجهزة الجوّالة، نقترح استخدام إصدار حزمة تطوير البرامج (SDK) الخاصة بخدمة "AdSense لإعلانات Shopping" بدلاً من ذلك.

إذا كنت بصدد الترقية إلى الإصدار 19.0.0 أو إصدار أحدث من 18.1.0 أو إصدار سابق، يُرجى مراجعة دليل نقل البيانات

المتطلبات الأساسية

يفترض دليل التنفيذ هذا أنّك على دراية بما يلي:

استيراد حزمة تطوير البرامج (SDK) للإعلانات المدمجة مع المحتوى في "AdSense للبحث"

إضافة حزمة SDK

لإضافة حزمة تطوير البرامج (SDK) الأصلية لإعلانات Shopping إلى تطبيقك إلى تطبيقك، اتّبِع الخطوات التالية:

افتح ملف build.gradle داخل دليل وحدة التطبيق. أضِف قاعدة إصدار جديدة ضمن 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 Plugin إلى مشروعك. يؤدي تطبيق هذا المكوّن الإضافي إلى حدوث خطأ في إصدار Gradle عندما يتم تنفيذ يتم استخدامها مع إصدار غير متوافق من خدمات Google Play بدلاً من السماح إصدار التطبيق، ولكنه قد يتسبب في حدوث أعطال في وقت التشغيل. أو تطبيق failOnVersionConflict() ResolutionStrategy إلى مشروعك للتسبب في خطأ إصدار عند وجود إصدارات غير متوافقة من Google Play يتم استخدام الخدمات في مشروعك. احفظ التغييرات وانقر على مزامنة المشروع مع ملفات Gradle في شريط الأدوات.

استخدام AndroidX بدلاً من "مكتبات دعم Android"

بدءًا من الإصدار 17.0.0 من حزمة تطوير البرامج (SDK)، يجب أن يستخدم تطبيقك Jetpack (AndroidX). المكتبات بدلاً من "مكتبات دعم Android" متطلبات التوافق:

  • اضبط com.android.tools.build:gradle على الإصدار 3.2.1 أو إصدار أحدث.
  • اضبط السمة compileSdkVersion على 28 أو بعد ذلك.
  • تحديث تطبيقك لاستخدام Jetpack (AndroidX) اتبع التعليمات الواردة في نقل البيانات إلى AndroidX

صفوف

لعرض الإعلانات المدمجة مع المحتوى من خلال "AdSense للبحث" في تطبيقك، نفِّذ الفئات التالية:

SearchAdController

  • هذه الفئة مسؤولة عن الطلب غير المتزامن للإعلانات والتخزين المؤقت واسترداد الإعلانات وعرض الإعلانات
  • يحتاج كل سياق إعلان إلى SearchAdController منفصل. على سبيل المثال، إذا تحتوي على شاشة تعرض الإعلانات إلى جانب قائمة من نتائج البحث وقائمة أخرى التي تعرض الإعلانات إلى جانب تفاصيل منتج معيّن، أنشئ مثيلَين منفصلَين من SearchAdController، نسخة لكل حالة.
  • يجب توفير رمز موقع الويب (رقم تعريف الناشر) في الدالة الإنشائية. style ID المطلوب تطبيقه على و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

  • نفِّذ هذه الواجهة وتمريرها إلى الدالة الإنشائية SearchAdController لتسجيل عمليات معاودة الاتصال لعدة ولايات.
  • ملاحظة: لن يتم استدعاء 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());

نفِّذ دالة معاودة الاتصال "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.