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

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

في حال الترقية إلى الإصدار 19.0.0 أو إصدار أحدث من 18.1.0 أو إصدار أقدم، يُرجى الاطّلاع على دليل نقل البيانات.

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

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

استيراد "حزمة تطوير البرامج (SDK) الأصلية" لخدمة "AdSense للبحث"

إضافة حزمة تطوير البرامج (SDK)

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

افتح ملف build.gradle داخل دليل وحدة التطبيق. أضِف قاعدة إصدار جديدة بموجب dependencies لأحدث إصدار من حزمة تطوير البرامج (SDK):

dependencies {
  implementation 'com.google.android.gms:play-services-afs-native:19.0.3'
}

تأكَّد من أنّ قيمة build.gradle ذات المستوى الأعلى تحتوي على مرجع إلى مستودع google() أو إلى maven { url "https://maven.google.com" }.

اتّبِع هذه التعليمات لتضمين المكوّن الإضافي لواجهة Google Play Standalone Version Matcher في مشروعك. يتسبب تطبيق هذا المكوّن الإضافي في حدوث خطأ في إصدار Gradle عند استخدام حزمة تطوير البرامج (SDK) الأصلية لخدمة "AdSense للبحث" مع إصدار غير متوافق من "خدمات Google Play" بدلاً من السماح بإنشاء التطبيق مع احتمالية حدوث أعطال في وقت التشغيل. أو يمكنك تطبيق failOnVersionConflict() ResolutionStrategy على مشروعك للتسبّب في حدوث خطأ في الإصدار عند استخدام إصدارات غير متوافقة من "خدمات Google Play" في مشروعك. احفظ التغييرات وانقر على مزامنة المشروع مع ملفات Gradle في شريط الأدوات.

استخدام AndroidX بدلاً من Android Support Libraries

بدءًا من الإصدار 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.