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

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

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

قبل البدء

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

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

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

    • الإصدار 23 من حزمة SDK كحد أدنى أو إصدار أحدث
    • الإصدار 35 من حزمة SDK للتحويل البرمجي أو إصدار أحدث

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

يمكنك تسجيل تطبيقك كتطبيق على AdMob من خلال إكمال الخطوات التالية:

  1. سجِّل الدخول إلى حساب على AdMob أو أنشئ حسابًا على AdMob.

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

إعداد تطبيقك

  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.4.0")
}

    Groovy

    dependencies {
  implementation 'com.google.android.gms:play-services-ads:25.4.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 وتتمكّن من الوصول إلى المعرّف الإعلاني متى ما كان متاحًا.

    بالنسبة إلى التطبيقات التي تستخدم Google Mobile Ads SDK (Legacy) الإصدار 20.3.0 أو إصدارًا أقدم وتستهدف Android 13، يجب إضافة الإذن 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، عليك الانتظار إلى أن يتم استدعاء أداة معالجة الإكمال قبل تحميل الإعلانات. يضمن ذلك تهيئة جميع محوّلات التوسّط.

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

Kotlin

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

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

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

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

عرض "إعلانات بانر"

إعلان بيني

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

عرض الإعلانات البينية

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

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

عرض "إعلانات مدمجة مع المحتوى"

تمت المكافأة

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

عرض "الإعلانات مقابل مكافأة"

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

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

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

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

عرض "الإعلانات البينية مقابل مكافأة"

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

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

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

مراجع إضافية

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