ابدأ استخدام AdMob في مشروعك باستخدام لغة C++‎

دليل البدء السريع هذا مخصص للناشرين والمطورين الذين يرغبون في استخدام AdMob لتحقيق الدخل من أحد التطبيقات التي تم إنشاؤها باستخدام Firebase. إذا كنت لا تخطط لتضمين Firebase في تطبيقك، فتفضل بزيارة دليل AdMob المستقل بدلاً من ذلك.

إذا لم تكن قد فعلت ذلك بعد، فتعرف على جميع فوائد استخدام AdMob وFirebase وGoogle Analytics معًا.

إذا كانت هذه هي المرة الأولى التي تستعرض فيها هذا الدليل، فنوصيك بتنزيل التطبيق التجريبي Google Mobile Ads C++ SDK ومتابعته.

قبل ان تبدأ

  • إذا لم يكن لديك بالفعل مشروع Firebase وتطبيق Firebase، فاتبع دليل بدء Firebase: أضف Firebase إلى مشروع C++ الخاص بك .

  • تأكد من تمكين Google Analytics في مشروع Firebase الخاص بك:

    • إذا كنت تقوم بإنشاء مشروع Firebase جديد، فقم بتمكين Google Analytics أثناء سير عمل إنشاء المشروع.

    • إذا كان لديك مشروع Firebase حالي لم يتم تمكين Google Analytics فيه، فيمكنك تمكين Google Analytics من علامة التبويب عمليات التكامل في جهازك > إعدادات المشروع .

الخطوة 1: قم بإعداد تطبيقك في حسابك في AdMob

  1. قم بتسجيل كل نسخة مختلفة من النظام الأساسي لتطبيقك كتطبيق AdMob.

    1. قم بتسجيل الدخول أو الاشتراك في حساب AdMob.

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

    سيُطلب منك إضافة SDK لإعلانات الجوال إلى تطبيقك. يمكنك العثور على تعليمات مفصلة لهذه المهمة لاحقًا في هذا الدليل.

  2. اربط كل تطبيق من تطبيقات AdMob بتطبيق Firebase المطابق.

    هذه الخطوة اختيارية ولكن يوصى بها بشدة. تعرّف على المزيد عن فوائد تمكين مقاييس المستخدم وربط تطبيقات AdMob بـ Firebase.

    بالنسبة لكل متغير من الأنظمة الأساسية، أكمل الخطوتين التاليتين في لوحة تحكم التطبيقات بحسابك في AdMob:

    1. قم بتمكين مقاييس المستخدم للسماح لـ AdMob بمعالجة وعرض بيانات التحليلات المنظمة في حسابك في AdMob. وهو أيضًا إعداد مطلوب بالنسبة لك لربط تطبيق AdMob بـ Firebase.

    2. اربط تطبيق AdMob بمشروع Firebase الحالي وتطبيق Firebase المقابل.

      تأكد من إدخال نفس اسم الحزمة (Android) أو معرف الحزمة (iOS) الذي أدخلته في تطبيق Firebase. ابحث عن اسم حزمة تطبيق Firebase أو معرف الحزمة في بطاقة التطبيقات الخاصة بك > إعدادات المشروع .

الخطوة 2: أضف معرف تطبيق AdMob إلى تطبيقك

ذكري المظهر

أضف معرف تطبيق AdMob إلى ملف AndroidManifest.xml لتطبيقك عن طريق إضافة العلامة <meta-data> كما هو موضح أدناه.

<manifest>
    <application>
        <!-- Sample AdMob App ID: ca-app-pub-3940256099942544~3347511713 -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ADMOB_APP_ID"/>
    </application>
</manifest>

دائرة الرقابة الداخلية

في ملف Info.plist لتطبيقك، أضف مفتاح GADApplicationIdentifier مع قيمة سلسلة لمعرف تطبيق AdMob .

يمكنك إجراء هذا التغيير برمجياً:

<!-- Sample AdMob App ID: ca-app-pub-3940256099942544~1458002511 -->
<key>GADApplicationIdentifier</key>
<string>ADMOB_APP_ID</string>

أو قم بتحريره في محرر قائمة الخصائص:

محرر قائمة الممتلكات

الخطوة 3: أضف SDK لإعلانات Google على الجوال

نظرًا لأن Google Mobile Ads C++ SDK موجودة في مساحة الاسم firebase::gma ، قم بتنزيل Firebase C++ SDK ، ثم قم بفك ضغطها إلى دليل من اختيارك.

إن Firebase C++ SDK ليس خاصًا بالنظام الأساسي، ولكنه يتطلب تكوينات مكتبة خاصة بالنظام الأساسي.

ذكري المظهر

  1. في ملف gradle.properties الخاص بمشروعك، حدد موقع SDK الذي تم فك ضغطه:

    systemProp.firebase_cpp_sdk.dir=FULL/PATH/TO/SDK
  2. إلى ملف settings.gradle الخاص بمشروعك، أضف المحتوى التالي:

    def firebase_cpp_sdk_dir = System.getProperty('firebase_cpp_sdk.dir')
    
    gradle.ext.firebase_cpp_sdk_dir = "$firebase_cpp_sdk_dir"
    includeBuild "$firebase_cpp_sdk_dir"
  3. إلى ملف Gradle الخاص بوحدتك (على مستوى التطبيق) (عادةً app/build.gradle )، أضف المحتوى التالي، والذي يتضمن تبعية المكتبة لـ Google Mobile Ads C++ SDK.

    android.defaultConfig.externalNativeBuild.cmake {
      arguments "-DFIREBASE_CPP_SDK_DIR=$gradle.firebase_cpp_sdk_dir"
    }
    
    # Add the dependency for the Google Mobile Ads C++ SDK
    apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
    firebaseCpp.dependencies {
      gma
    }
  4. إلى ملف CMakeLists.txt الخاص بمشروعك، قم بإضافة المحتوى التالي.

    # Add Firebase libraries to the target using the function from the SDK.
    add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL)
    
    # Add the Google Mobile Ads C++ SDK.
    
    # The Firebase C++ library `firebase_app` is required,
    # and it must always be listed last.
    
    set(firebase_libs
      firebase_gma
      firebase_app
    )
    
    target_link_libraries(${target_name} "${firebase_libs}")
  5. قم بمزامنة تطبيقك للتأكد من أن جميع التبعيات لديها الإصدارات الضرورية.

أنت جاهز تمامًا! تم تكوين تطبيق C++ الخاص بك لاستخدام Google Mobile Ads C++ SDK.

دائرة الرقابة الداخلية

تعد الخطوات الواردة في هذا القسم مثالاً لكيفية إضافة Google Mobile Ads C++ SDK إلى مشروع iOS الخاص بك.

  1. احصل على CocoaPods الإصدار 1 أو الأحدث عن طريق تشغيل:

    sudo gem install cocoapods --pre
  2. أضف مجموعة إعلانات Google للجوال من حزمة SDK غير المضغوطة.

    1. قم بإنشاء ملف Podfile إذا لم يكن لديك واحد بالفعل:

      cd YOUR_APP_DIRECTORY
      pod init
    2. إلى ملف Podfile الخاص بك، أضف pod لـ Google Mobile Ads C++ SDK:

      pod 'Google-Mobile-Ads-SDK'
    3. قم بتثبيت البود، ثم افتح ملف .xcworkspace في Xcode.

      pod install
      open YOUR_APP.xcworkspace
    4. أضف الأطر التالية من Firebase C++ SDK إلى المشروع:

      • xcframeworks/firebase.xcframework
      • xcframeworks/firebase_gma.xcframework

أنت جاهز تمامًا! تم تكوين تطبيق C++ الخاص بك لاستخدام Google Mobile Ads C++ SDK.

الخطوة 4: تهيئة حزمة SDK لإعلانات Google على الجوال

قبل تحميل الإعلانات، قم بتهيئة SDK لإعلانات الجوال عن طريق استدعاء firebase::gma::Initialize() .

يُرجع هذا الاستدعاء firebase::Future الذي يكتمل بمجرد انتهاء التهيئة (أو بعد مهلة 30 ثانية). قم باستدعاء هذه الطريقة مرة واحدة فقط وفي أقرب وقت ممكن، ومن الأفضل عند تشغيل التطبيق.

فيما يلي مثال لكيفية استدعاء Initialize() :

ذكري المظهر

// Initialize the Google Mobile Ads library
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(jni_env, j_activity, &result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

// Monitor the status of the future.
// See "Use a Future to monitor the completion status of a method call" below.
if (future.status() == firebase::kFutureStatusComplete &&
    future.error() == firebase::gma::kAdErrorCodeNone) {
  // Initialization completed.
} else {
  // Initialization on-going, or an error has occurred.
}

دائرة الرقابة الداخلية

// Initialize the Google Mobile Ads library.
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(&result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

// Monitor the status of the future.
// See "Use a Future to monitor the completion status of a method call" below.
if (future.status() == firebase::kFutureStatusComplete &&
    future.error() == firebase::gma::kAdErrorCodeNone) {
  // Initialization completed.
} else {
  // Initialization on-going, or an error has occurred.
}

استخدم Future لمراقبة حالة اكتمال استدعاء الأسلوب

يوفر لك Future طريقة لتحديد حالة اكتمال استدعاءات الطريقة غير المتزامنة.

على سبيل المثال، عندما يستدعي تطبيقك firebase::gma::Initialize() ، يتم إنشاء firebase::Future جديدة وإعادتها. يمكن لتطبيقك بعد ذلك استطلاع status() Future لتحديد وقت اكتمال التهيئة. بمجرد اكتماله، يمكن لتطبيقك استدعاء result() للحصول على ملف AdapterInitializationStatus الناتج.

الأساليب التي تُرجع Future لها طريقة "النتيجة الأخيرة" المقابلة التي يمكن للتطبيقات استخدامها لاسترداد أحدث Future لإجراء معين. على سبيل المثال، يحتوي firebase::gma::Initialize() على طريقة مقابلة تسمى firebase::gma::InitializeLastResult() ، والتي تُرجع Future يمكن لتطبيقك استخدامه للتحقق من حالة آخر استدعاء لـ firebase::gma::Initialize() .

إذا كانت حالة Future مكتملة وكان رمز الخطأ الخاص بها هو firebase::gma::kAdErrorCodeNone ، فقد اكتملت العملية بنجاح.

يمكنك أيضًا تسجيل عمليات الاسترجاعات ليتم استدعاؤها عند اكتمال Future . في بعض الحالات، سيتم تشغيل رد الاتصال في سلسلة محادثات مختلفة، لذا تأكد من أن الكود الخاص بك آمن لسلسلة المحادثات. يستخدم مقتطف التعليمات البرمجية هذا مؤشر وظيفة لرد الاتصال:

// Registers the OnCompletion callback. user_data is a pointer that is passed verbatim
// to the callback as a void*. This allows you to pass any custom data to the callback
// handler. In this case, the app has no data, so you must pass nullptr.
firebase::gma::InitializeLastResult().OnCompletion(OnCompletionCallback,
  /*user_data=*/nullptr);

// The OnCompletion callback function.
static void OnCompletionCallback(
  const firebase::Future<AdapterInitializationStatus>& future, void* user_data) {
  // Called when the Future is completed for the last call to firebase::gma::Initialize().
  // If the error code is firebase::gma::kAdErrorCodeNone,
  // then the SDK has been successfully initialized.
  if (future.error() == firebase::gma::kAdErrorCodeNone) {
    // success!
  } else {
    // failure.
  }
}

الخطوة 5: اختر شكل إعلان لتنفيذه في تطبيقك

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

الإعلانات المستطيلة التي تظهر أعلى أو أسفل شاشة الجهاز

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

تنفيذ إعلانات البانر

إعلان خلالي

إعلانات بملء الشاشة تغطي واجهة التطبيق حتى يغلقها المستخدم

من الأفضل استخدام الإعلانات البينية عند فترات الإيقاف المؤقت الطبيعية في تدفق تنفيذ التطبيق، مثل بين مستويات اللعبة أو بعد اكتمال المهمة مباشرةً.

تنفيذ الإعلانات البينية

مكافأة

الإعلانات التي تكافئ المستخدمين على مشاهدة مقاطع فيديو قصيرة والتفاعل مع الإعلانات والاستطلاعات القابلة للتشغيل

يمكن أن تساعد الإعلانات بمكافأة (أو "القائمة على المكافأة") في تحقيق الدخل من مستخدمي اللعب المجاني.

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

مواضيع أخرى ذات أهمية

عرض مقاييس المستخدم وبيانات التحليلات

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

لاحظ أنه لتمثيل مقاييس ARPU و ARPPU بشكل أفضل، قد ترغب في تضمين بيانات من حدث تحليلي مخصص يسمى ecommerce_purchase في حساب الإيرادات لهذه المقاييس ( تعرف على كيفية القيام بذلك ).

(اختياري) استخدم المزيد من ميزات Google Analytics وFirebase

استفد من المزيد من الفرص والميزات لتحسين تحقيق الدخل من التطبيق وتفاعل المستخدمين:

  • قم بإضافة واستخدام Firebase SDK لـ Google Analytics

    لمعرفة المزيد، تفضل بزيارة دليل استخدام Google Analytics وFirebase مع تطبيقات AdMob .

  • استخدم منتجات Firebase الأخرى في تطبيقك

    بعد إضافة Firebase SDK لبرنامج Google Analytics، استخدم منتجات Firebase الأخرى لتحسين الإعلانات في تطبيقك.

    • يمكّنك Remote Config من تغيير سلوك تطبيقك ومظهره دون نشر تحديث التطبيق، دون أي تكلفة، لعدد غير محدود من المستخدمين النشطين يوميًا.

    • يمنحك اختبار A/B القدرة على اختبار التغييرات التي تطرأ على واجهة مستخدم تطبيقك أو ميزاته أو حملات المشاركة لمعرفة ما إذا كانت تؤثر على مقاييسك الرئيسية (مثل الإيرادات والاحتفاظ) قبل نشر التغييرات على نطاق واسع.