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

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

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

قبل البدء

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

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

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

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

إعداد تطبيقك

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

    Groovy

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

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

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

    <manifest>
  <application>
    <!-- Sample Ad Manager 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 برقم تعريف تطبيقك على "مدير إعلانات Google". أثناء الاختبار، استخدِم رقم تعريف نموذج التطبيق الموضّح في المثال السابق.

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

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

قد يتم تحميل الإعلانات مسبقًا من خلال 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();

Kotlin

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

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

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

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

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

إعلان بيني

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

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

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

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

يوفّر "مدير إعلانات Google" طريقتَين لعرض "الإعلانات المدمجة مع المحتوى": الأنماط المدمجة مع المحتوى و"الإعلانات المدمجة مع المحتوى" العادية من خلال العرض المخصّص.

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

عرض الأنماط المدمجة مع المحتوى عرض "الإعلانات المدمجة مع المحتوى" (العرض المخصّص)

تمت المكافأة

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

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

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

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

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

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

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

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

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

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

مراجع إضافية

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