تتوافق حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" أيضًا مع أنماط البحث المخصّصة. إذا كان تطبيقك يستخدم حاليًا "SDK لإعلانات Google على الأجهزة الجوّالة"، نقترح استخدام إصدار AFSMA SDK بدلاً من ذلك.
في حال الترقية إلى الإصدار 19.0.0 أو إصدار أحدث من 18.1.0 أو إصدار أقدم، يُرجى الاطّلاع على دليل نقل البيانات.
المتطلبات الأساسية
يفترض دليل التنفيذ هذا أنك على دراية بما يلي:
- إعلانات البحث المخصّص في AdSense مع أنماط البحث المخصّصة
- تطوير تطبيق Android
استيراد "حزمة تطوير البرامج (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
، واحدة لكل حالة. - يجب أن تقدّم الدالة الإنشائية رمز موقعك الإلكتروني (معرّف الناشر) ورقم تعريف النمط لتطبيقه على الإعلانات
المعروضة و
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
إلى محو جميع الإعلانات المخزَّنة مؤقتًا ومفاتيح الإعلان المرتبطة بها).
- مرِّر هذا الكائن إلى الدالة الإنشائية
SearchAdController
لتخصيص طريقة طلب الإعلانات وعرضها. استدعِbuild()
علىSearchAdOptions.Builder
لإنشاء كائنSearchAdOptions
.
View
- أنشِئ عنصر
View
لتعليق الإعلانات من خلال طلبcreateAdView()
علىSearchAdController
. تعرض إعلانًا واحدًا على الأكثر في كل مرة، ولكن يمكن إعادة تدوير إعلانView
نفسه لعرض إعلانات مختلفة بمرور الوقت.
- يمكنك استدعاء الإجراء
loadAds
فيSearchAdController
باستخدامSearchAdRequest
لبدء طلب إعلان غير متزامن. استدعِ "build()
" علىSearchAdRequest.Builder
لإنشاء كائنSearchAdRequest
.
- نفِّذ هذه الواجهة ومرِّرها إلى الدالة الإنشائية
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.