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

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

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

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

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

استيراد حزمة تطوير البرامج (SDK) الأصلية لبرنامج AFS

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

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

افتح ملف 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، يجب أن يستخدم تطبيقك مكتبات 17.0.0 (AndroidX) بدلاً من مكتبات Android Support Libraries. متطلبات التوافق:

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

صفوف

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

SearchAdController

  • تتحمّل هذه الفئة مسؤولية طلب الإعلانات بشكل غير متزامن وتخزينها مؤقتًا و retrieving retrieving الإعلانات وعرضها.
  • يحتاج كل سياق إعلان إلى 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 constructor لتسجيل وظائف الاستدعاء لعدة حالات.
  • ملاحظة: لن يتمّ استدعاء وظائف الاستدعاء 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.