إعداد حزمة "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.

   إذا كان تطبيقك يستخدم الإصدار 20.4.0 أو إصدارًا أحدث من Google Mobile Ads SDK (Legacy)، يمكنك تخطّي هذه الخطوة لأنّ حزمة تطوير البرامج (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 كيفية استخدام أشكال الإعلانات المختلفة التي توفّرها واجهة برمجة التطبيقات هذه.