إعداد حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" (الإصدار القديم)

اختيار النظام الأساسي: Android iOS Unity Flutter Android (الإصدار القديم)

يُعدّ دمج Google Mobile Ads SDK (Legacy) في تطبيق الخطوة الأولى نحو عرض الإعلانات وتحقيق الإيرادات. بعد دمج حزمة SDK، يمكنك اختيار شكل إعلان (مثل الإعلان المدمج مع المحتوى أو الفيديو مقابل مكافأة) واتّباع الخطوات لتنفيذه.

قبل البدء

لإعداد تطبيقك، أكمِل الخطوات الواردة في الأقسام التالية.

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

• تأكَّد من أنّ ملف إنشاء تطبيقك يستخدم القيم التالية:

  • الإصدار 24 من حزمة تطوير البرامج (SDK) أو إصدار أحدث
  • إصدار حزمة تطوير البرامج (SDK) الذي تم تجميعه 35 أو إصدار أحدث

إعداد تطبيقك في حسابك على AdMob

سجِّل تطبيقك كتطبيق يستخدم AdMob من خلال إكمال الخطوات التالية:

1. سجِّل الدخول أو اشترِك في حساب على AdMob.

2. تسجيل تطبيقك في AdMob تؤدي هذه الخطوة إلى إنشاء تطبيق يستخدم AdMob باستخدام معرّف تطبيق AdMob فريد، وهو مطلوب لاحقًا في هذا الدليل.

إعداد تطبيقك

1. في ملف إعدادات Gradle، أدرِج مستودع Maven من Google ومستودع Maven المركزي:

   Kotlin

   pluginManagement {
     repositories {
       google()
       mavenCentral()
       gradlePluginPortal()
     }
   }
   
   dependencyResolutionManagement {
     repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
     repositories {
       google()
       mavenCentral()
     }
   }
   
   rootProject.name = "My Application"
   include(":app")

   Groovy

   pluginManagement {
     repositories {
       google()
       mavenCentral()
       gradlePluginPortal()
     }
   }
   
   dependencyResolutionManagement {
     repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
     repositories {
       google()
       mavenCentral()
     }
   }
   
   rootProject.name = "My Application"
   include ':app'

2. أضِف التبعيات الخاصة بـ Google Mobile Ads SDK (Legacy) إلى ملف الإصدار على مستوى التطبيق:

   Kotlin

   dependencies {
     implementation("com.google.android.gms:play-services-ads:25.5.0")
   }

   Groovy

   dependencies {
     implementation 'com.google.android.gms:play-services-ads:25.5.0'
   }

3. انقر على المزامنة الآن. لمزيد من التفاصيل حول المزامنة، يُرجى الاطّلاع على مزامنة المشاريع مع ملفات Gradle.

4. أضِف رقم تعريف تطبيقك على AdMob، كما هو محدّد في واجهة مستخدم AdMob على الويب، إلى ملف AndroidManifest.xml الخاص بتطبيقك. لإجراء ذلك، أضِف علامة <meta-data> مع android:name="com.google.android.gms.ads.APPLICATION_ID". يمكنك العثور على رقم تعريف تطبيقك في واجهة الويب الخاصة بخدمة AdMob. استبدِل android:value بمعرّف تطبيقك على AdMob، مع وضع المعرّف بين علامتَي اقتباس.

   <manifest>
     <application>
       <!-- Sample AdMob app ID: ca-app-pub-3940256099942544~3347511713 -->
       <meta-data
           android:name="com.google.android.gms.ads.APPLICATION_ID"
           android:value="SAMPLE_APP_ID"/>
     </application>
   </manifest>
   

   استبدِل SAMPLE_APP_ID برقم تعريف تطبيقك على AdMob. أثناء الاختبار، استخدِم معرّف نموذج التطبيق الموضّح في المثال السابق.

   يُرجى أيضًا العِلم أنّ عدم إضافة العلامة <meta-data> كما هو موضّح تمامًا سيؤدي إلى حدوث عطل مع ظهور الرسالة التالية:

   Missing application ID.
   

   (اختياري) عليك تعريف إذن AD_ID للإصدارات السابقة لكي تعمل مع نظام التشغيل Android 13.

   إذا كان تطبيقك يستخدم الإصدار Google Mobile Ads SDK (Legacy)20.4.0 أو إصدارًا أحدث، يمكنك تخطّي هذه الخطوة لأنّ حزمة تطوير البرامج (SDK) تطلب الإذن com.google.android.gms.permission.AD_ID تلقائيًا ويمكنها الوصول إلى المعرّف الإعلاني متى كان متاحًا.

   بالنسبة إلى التطبيقات التي تستخدم الإصدار 20.3.0 أو إصدارًا أقدم من Google Mobile Ads SDK (Legacy) وتستهدف الإصدار 13 من نظام التشغيل Android، عليك إضافة إذن com.google.android.gms.permission.AD_ID في ملف AndroidManifest.xml لكي تتمكّن Google Mobile Ads SDK (Legacy) من الوصول إلى المعرّف الإعلاني:

   <manifest>
    <application>
      <meta-data
          android:name="com.google.android.gms.ads.APPLICATION_ID"
          android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
   
      <!-- For apps targeting Android 13 or higher & GMA SDK version 20.3.0 or lower -->
      <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
   
    </application>
   </manifest>

   لمزيد من المعلومات عن بيان الإذن com.google.android.gms.permission.AD_ID، بما في ذلك كيفية إيقافه، يمكنك الرجوع إلى مقالة Play Console هذه.

إعداد Google Mobile Ads SDK (Legacy)

قبل تحميل الإعلانات، عليك ضبط Google Mobile Ads SDK (Legacy) على القيمة الأولية من خلال استدعاء MobileAds.initialize().

تُعدّ هذه الطريقة حزمة تطوير البرامج (SDK) وتستدعي أداة معالجة الإكمال بعد اكتمال عملية إعداد كل من Google Mobile Ads SDK (Legacy) والمحوّل، أو بعد انتهاء المهلة البالغة 30 ثانية. يجب إجراء ذلك مرة واحدة فقط، ويُفضّل عند تشغيل التطبيق.

إذا كنت تستخدم "التوسّط" في AdMob، انتظِر إلى أن يتم استدعاء معالج الإكمال قبل تحميل الإعلانات. ويضمن ذلك تهيئة جميع محوّلات التوسّط.

قد يتم التحميل المُسبَق للإعلانات من خلال حِزم تطوير البرامج (SDK) الخاصة بـ Google Mobile Ads SDK (Legacy) أو شركاء التوسّط عند بدء التشغيل. إذا كنت بحاجة إلى الحصول على موافقة المستخدمين في المنطقة الاقتصادية الأوروبية أو المملكة المتحدة أو سويسرا، عليك ضبط أي علامات خاصة بالطلبات، مثل setTagForChildDirectedTreatment() أو setTagForUnderAgeOfConsent()، أو اتّخاذ إجراء آخر قبل تحميل الإعلانات، مع التأكّد من إجراء ذلك قبل بدء Google Mobile Ads SDK (Legacy).

في ما يلي مثال على كيفية استدعاء طريقة initialize() في سلسلة الخلفية ضمن نشاط:

جافا

new Thread(
        () -> {
          // Initialize the Google Mobile Ads SDK on a background thread.
          MobileAds.initialize(this, initializationStatus -> {});
        })
    .start();
MyActivity.java

Kotlin

CoroutineScope(Dispatchers.IO).launch {
  // Initialize the Google Mobile Ads SDK on a background thread.
  MobileAds.initialize(this@MainActivity) {}
}
MainActivity.kt

اختيار شكل الإعلان

تم الآن استيراد Google Mobile Ads SDK (Legacy) وأنت على استعداد لتنفيذ إعلان. توفّر AdMob عددًا من أشكال الإعلانات المختلفة، ما يتيح لك اختيار الشكل الأنسب لتجربة المستخدم في تطبيقك.

بانر

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

استخدام "إعلانات البانر"

إعلان بيني

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

استخدام الإعلانات البينية

مدمج مع المحتوى

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

تنفيذ "الإعلانات المدمجة مع المحتوى"

تمت المكافأة

تتيح وحدات "الإعلانات مقابل مكافأة" للمستخدمين تشغيل الألعاب أو المشاركة في استطلاعات أو مشاهدة فيديوهات للحصول على مكافآت داخل التطبيق، مثل الحصول على عملات معدنية أو محاولات إضافية أو نقاط. يمكنك تعيين مكافآت مختلفة لوحدات إعلانية مختلفة، وتحديد قيم المكافأة والعناصر التي حصل عليها المستخدم.

عرض الإعلانات مقابل مكافآت

إعلان بيني مقابل مكافأة

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

على عكس الإعلانات مقابل مكافأة، لا يُطلب من المستخدمين الموافقة على عرض إعلان بيني مقابل مكافأة.

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

استخدام "الإعلانات البينية مقابل مكافأة"

إعلان على شاشة فتح التطبيق

"الإعلانات على شاشة فتح التطبيق" هي شكل إعلان يظهر عندما يفتح المستخدمون تطبيقك أو يعودون إليه مرة أخرى. يظهر الإعلان على شاشة التحميل.

تنفيذ "الإعلانات على شاشة فتح التطبيق"

مراجع إضافية

يوضّح مستودع "إعلانات Google على الأجهزة الجوّالة" على GitHub كيفية استخدام أشكال الإعلانات المختلفة التي توفّرها واجهة برمجة التطبيقات هذه.