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

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

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