تنفيذ "AdSense للبحث في التطبيقات المتوافقة مع الأجهزة الجوّالة" لنظام التشغيل Android

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

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

• بروتوكول تنفيذ إعلانات البحث المخصّص (CSA) في AdSense للبحث
• تطوير تطبيقات Android
• ربط حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة لنظام التشغيل Android (الآن جزء من خدمات Google Play) بمشروع "استوديو Android". يجب توفُّر الإصدار 9.0.0 من "خدمات Google Play".

صفوف

لعرض إعلانات AFSMA (المعروفة أيضًا باسم إعلانات الارتفاع الديناميكي على شبكة البحث) في تطبيقك، نفِّذ الفئات التالية:

SearchAdView

• يتم اكتساب هذه الفئة من فئة ViewGroup لنظام التشغيل Android وتعرض إعلانات AdSense للبحث. تعمل السمة SearchAdView على تقديم طلب للإعلان الذي يتضمّن السمة DynamicHeightSearchAdRequest، ثم عرض الإعلانات المعروضة. يجب إضافة SearchAdView إلى أيّ من مجموعات الملفات الشخصية الحالية في التطبيق.
• يجب إنشاء مثيل SearchAdView مع السياق الذي يتم فيه تشغيل SearchAdView، ويكون عادةً Activity.
• بعد إنشاء مثيل SearchAdView، يجب استدعاء الطريقة setAdSize() باستخدام AdSize.SEARCH لطلب إعلانات AFSMA. ستطلب قيم تعداد أخرى إعلانات غير متوافقة مع "AdSense للبحث" في التطبيقات المتوافقة مع الأجهزة الجوّالة.
• استدعِ الطريقة setAdUnitId() في هذا الكائن باستخدام رمز الملكية.

DynamicHeightSearchAdRequest.Builder

• تضم هذه الفئة معلمات طلبات الإعلان. ويشبه هذا الإعداد المَعلمات في كائنات طلبات الإعلانات المستندة إلى JavaScript (خيارات الصفحة وخيارات الوحدة) في ما يخصّ "AdSense للبحث" على أجهزة الكمبيوتر المكتبي والويب على الأجهزة الجوّالة.
• اضبط المعلَمات باستخدام عوامل الضبط المناسبة (بعبارة أخرى، استدعِ setQuery() لضبط مَعلمة طلب البحث).

مثال على عملية التنفيذ

يوضح المثال أدناه استخدام Activity لإنشاء SearchAdView كعرض فرعي لـ ViewGroup. لطلب إعلانات AFSMA بشكل صحيح، يجب أن يستدعي الكائن SearchAdView الطريقة setAdSize() باستخدام AdSize.SEARCH.

//  MainActivity.java implementation
//  (MainActivity is a subclass of Activity)

// Create the SearchAdView
final SearchAdView searchAdView = new SearchAdView(this);

// Set parameter to request for dynamic height search ads
searchAdView.setAdSize(AdSize.SEARCH); // Important!

// Replace with your pub ID (e.g. ms-app-pub-9616389000213823)
searchAdView.setAdUnitId("ms-app-pub-################");

// Add searchAdView to parent view group
...

ضمن السمة Activity نفسها، أنشئ عنصر DynamicHeightSearchAdRequest.Builder يحدّد معلَمات الإعلان الذي سيتم عرضه في SearchAdView. يتم ضبط إعلانات AFSMA بالطريقة نفسها التي يتم بها إعداد إعلانات البحث المخصص في AdSense للبحث. يُرجى الاطّلاع على مرجع إعلانات البحث المخصص في AdSense للبحث للحصول على التفاصيل.

// Create the ad request
DynamicHeightSearchAdRequest.Builder builder =
        new DynamicHeightSearchAdRequest.Builder();
builder.setQuery("flowers");
builder.setNumber(2);

// Replace with the ID of a style from your custom search styles
builder.setAdvancedOptionValue("csa_styleId", "0000000001");

// Customization options (set using setters on
// DynamicHeightSearchAdRequest.Builder)
builder.setAdTest(true);

ويمكن الاستفادة من خيارات تخصيص أخرى من خلال ضبط سمات إضافية على العنصر DynamicHeightSearchAdRequest.Builder.

لتقديم طلب إعلان، يمكنك استدعاء الإجراء loadAd() باستخدام الكائن DynamicHeightSearchAdRequest.Builder من الكائن SearchAdView:

searchAdView.loadAd(builder.build());

الخيارات المتقدمة

يمكن ضبط معظم مَعلمات طلبات الإعلان باستخدام طرق setter على كائن DynamicHeightSearchAdRequest.Builder. يمكن ضبط أي معلَمات لا تتضمّن طريقة setter في DynamicHeightSearchAdRequest.Builder باستخدام أزواج المفتاح/القيمة باستخدام الطريقة setAdvancedOptionValue(). اطّلِع على مرجع إعلانات البحث المخصّص في "AdSense للبحث" للحصول على قائمة كاملة بالإعدادات التي يمكن ضبطها باستخدام طريقة setAdvancedOptionValue().

يجب أن تبدأ المعلمة الرئيسية بـ "csa_" لكي يتم ضبط الموقع بشكل صحيح.

// Advanced customization options (set using key-value pair)

// Set a parameter (parameter_name) and its value (parameter_value)
// builder.setAdvancedOptionValue("csa_parameter_name", "parameter_value");

// Example: Show visible URL below description
// (domainLinkAboveDescription: false)
builder.setAdvancedOptionValue("csa_domainLinkAboveDescription", "false");

إذا استخدمت طريقة setter لمَعلمة وعيَّنتها باستخدام setAdvancedOptionValue، سيلغي الاستدعاء الثاني القيمة من الاستدعاء الأول.

التحقيق في الأخطاء

تحتوي SearchAdView (searchAdView هنا) على طريقة setAdListener() لمساعدتك في التحقيق في الأخطاء. ضمن نطاق Activity نفسه:

searchAdView.setAdListener(new AdListener() {
    @Override
    public void onAdLoaded() {
        // Called when an ad is loaded
        super.onAdLoaded();
        Toast.makeText(MainActivity.this, "Ad Loaded",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
    }

    @Override
    public void onAdOpened() {
        // Called when an ad opens an overlay that covers the screen
        super.onAdOpened();
        Toast.makeText(MainActivity.this, "Ad Opened",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Opened");
    }

    @Override
    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example)
        super.onAdLeftApplication();
        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
        super.onAdFailedToLoad(errorCode);
        Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
                Toast.LENGTH_SHORT).show();
        Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
                errorCode);
    }
});

يتم وصف الثوابت المستخدمة في طريقة معاودة الاتصال onAdFailedToLoad() في مرجع واجهة برمجة التطبيقات.

الاستعداد لمتطلبات الإفصاح عن البيانات على Google Play

في أيار (مايو) 2021، أعلن فريق Google Play عن قسم جديد باسم "أمان البيانات"، وهو بيان إفصاح مقدَّم من مطوّري البرامج بشأن الممارسات المتّبعة لجمع بيانات التطبيقات ومشاركتها والحفاظ على أمانها.

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

نهدف إلى الالتزام بالشفافية قدر الإمكان في مساندتك، إلا أنّك بصفتك مطوِّر التطبيق تكون وحدك المسؤول عن تحديد كيفية الردّ على نموذج قسم "أمان البيانات" في Google Play بشأن ممارسات جمع بيانات المستخدمين النهائيين ومشاركتها وأمانها في تطبيقك.

كيفية استخدام المعلومات في هذه الصفحة

تعرِض هذه الصفحة بيانات المستخدمين النهائيين التي يتم جمعها من خلال أحدث إصدار من حزمة تطوير البرامج (SDK) فقط.

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

بيانات حزمة تطوير البرامج (SDK) لنوع البيانات التي يتم الوصول إليها وجمعها

الحِزم:

com.google.android.gms:play-services-afs-native

com.google.ads.afsn

البيانات المجمّعة تلقائيًا

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

البيانات	يتم جمع هذه البيانات للأغراض التالية...
عنوان IP	الملخّص: منع الاحتيال، والأمان، والامتثال الإعلان أو التسويق استنتاج الموقع الجغرافي التقريبي التفاصيل: يُستخدم عنوان IP في رصد عمليات الاحتيال وإساءة الاستخدام، كما يُستخدم للحصول على الموقع الجغرافي التقريبي للمستخدم. ويتم بعد ذلك استخدام الموقع الجغرافي التقريبي لضمان توافق الإعلانات المعروضة مع اللوائح التنظيمية المحلية، ولتقديم إعلانات ذات صلة بالموقع الجغرافي التقريبي للمستخدم.
النشاط على التطبيقات عدد مشاهدات الصفحات على الويب وعدد النقرات داخل التطبيق سجلّ البحث داخل التطبيق	الملخّص: الإحصاءات منع الاحتيال، والأمان، والامتثال الإعلان أو التسويق التخصيص التفاصيل: يزوّدنا تطبيقك بطلب البحث الذي أدخله المستخدم لنتمكّن من عرض إعلانات على شبكة البحث ذات صلة بالكلمة الرئيسية. نقيس عدد مرّات المشاهدة والتفاعل (النقرات) مع الإعلانات التي يتم عرضها.
بيانات التشخيص	الملخّص: الإحصاءات التفاصيل: تقيس حزمة تطوير البرامج (SDK) وقت استجابة العرض للإعلانات من أجل تنفيذ تحسينات المنتج وقياسه. نرسل أيضًا تقارير الأعطال/الأخطاء، ونضيف أحيانًا أدوات أخرى حسب الحاجة للتعرّف على كيفية استخدام الناشرين للوظائف.
الجهاز أو المعرّفات الأخرى	الملخّص: منع الاحتيال، والأمان، والامتثال الإعلان أو التسويق التفاصيل: يُستخدَم رقم تعريف الجهاز للمساعدة في رصد عمليات الاحتيال وإساءة الاستخدام، بالإضافة إلى قياس أداء الإعلانات.