إعداد حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"

اختيار النظام الأساسي: Android جديد Android iOS Unity Flutter

إنّ دمج Google Mobile Ads SDK في أحد التطبيقات هو الخطوة الأولى نحو عرض الإعلانات وتحقيق الإيرادات. بعد دمج حزمة 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 إلى ملف إنشاء التطبيق على مستوى التطبيق:

    Kotlin

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

    Groovy

    dependencies {
  implementation 'com.google.android.gms:play-services-ads:25.2.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 الإصدار 20.4.0 أو إصدارًا أحدث، يمكنك تخطّي هذه الخطوة لأنّ حزمة SDK تُعلن تلقائيًا عن الإذن com.google.android.gms.permission.AD_ID وتتمكّن من الوصول إلى المعرّف الإعلاني متى ما كان متاحًا.

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

    <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

قبل تحميل الإعلانات، عليك تهيئة Google Mobile Ads SDK من خلال استدعاء MobileAds.initialize().

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

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

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

في ما يلي مثال على كيفية استدعاء الطريقة 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 تم الآن استيراد حزمة، وأنت مستعد لعرض إعلان. تقدّم AdMob عددًا من أشكال الإعلانات المختلفة، لذا يمكنك اختيار الشكل الذي يناسب تجربة المستخدم في تطبيقك على أفضل نحو.

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

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

إعلان بيني

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

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

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

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

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

تمت المكافأة

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

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

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

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

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

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

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

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

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

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

مراجع إضافية

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