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

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

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

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

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

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

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

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

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

إعلان بيني

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

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

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

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

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

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

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

تمت المكافأة

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

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

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

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

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

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

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

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

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

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

مراجع إضافية

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