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