البدء


هذا الدليل مخصّص للناشرين الذين يريدون تحقيق الربح من تطبيق ++C باستخدام AdMob، بدون استخدام Firebase. إذا كنت تخطط لتضمين Firebase في تطبيقك أو كنت تفكّر في ذلك، يُرجى الاطّلاع بدلاً من ذلك على إصدار هذا الدليل الذي يتناول استخدام AdMob مع Firebase.

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

تغطي حزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C حزمتَي SDK لإعلانات Google على الأجهزة الجوّالة لنظامَي التشغيل iOS وAndroid، ولا تتوفّر إلا على هذين النظامَين. تستخدِم حزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C بُنى Firebase C++ لدعم العمليات غير المتزامنة، لذا فهي تقع في مساحة الاسم firebase::gma.

إذا كانت هذه هي المرة الأولى التي تستخدم فيها هذا الدليل، ننصحك بتنزيل تطبيق الاختبار لحزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C واتّباع الخطوات أثناء استخدامه.

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

Android

  • استخدام الإصدار 3.2 أو إصدار أحدث من "استوديو Android"
  • التأكّد من أنّ ملف إصدار تطبيقك يستخدم القيم التالية:
    • minSdkVersion بقيمة 16 أو أعلى
    • compileSdkVersion بقيمة 28 أو أعلى

iOS

  • استخدام الإصدار 13 أو إصدار أحدث من Xcode
  • استهداف الإصدار 10.0 من نظام التشغيل iOS أو إصدار أحدث

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

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

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

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

تثبيت حزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C

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

لا ترتبط حزمة Firebase C++ SDK بمنصة معيّنة، ولكنها تتطلّب إعدادات مكتبة خاصة بالمنصة.

Android

ننصحك باستخدام CMake، ولكن يمكنك العثور على تعليمات حول ndk-build في دليل البدء العام لحزمة Firebase C++ SDK لربط libfirebase_app.a و libfirebase_gma.a بتطبيقك.

  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، أضِف المحتوى التالي الذي يتضمّن مصدر الاعتمادية الخاص بمكتبة حزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C.

    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. عليك مزامنة تطبيقك للتأكّد من أنّ جميع مصادر الاعتمادية تتضمّن الإصدارات اللازمة.

iOS

الخطوات الواردة في هذا القسم هي مثال على كيفية إضافة حزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C إلى مشروعك على iOS.

  1. احصل على الإصدار 1 أو إصدار أحدث من CocoaPods من خلال تنفيذ الأمر التالي:

    sudo gem install cocoapods --pre

  2. أضِف وحدة Google Mobile Ads من حزمة SDK التي تم فك ضغطها.

    1. أنشِئ Podfile إذا لم يكن لديك واحد:

      cd APP_DIRECTORY
pod init

    2. في Podfile، أضِف وحدات حزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C، وحزمة SDK لمنصة Google User Messaging Platform، وحزمة Firebase core SDK الأساسية (التي تتطلبها حزمة GMA C++ SDK):

      pod 'Firebase/CoreOnly'
pod 'Google-Mobile-Ads-SDK'
pod 'GoogleUserMessagingPlatform'

    3. ثبِّت الوحدات، ثم افتح ملف .xcworkspace في Xcode.

      pod install
open APP.xcworkspace

    4. أضِف الأُطر التالية من حزمة Firebase C++ SDK إلى المشروع:

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

إذًا أنت على أتمّ استعداد. تم ضبط تطبيقك ++C لاستخدام حزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C بدون أي خدمات أخرى من Firebase.

ضبط معرّف تطبيق AdMob الخاص بتطبيقك

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

قبل تحميل الإعلانات، يجب أن يُعدّ تطبيقك حزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C من خلال استدعاء firebase::gma::Initialize() الذي يُعدّ حزمة SDK ويكمل firebase::Future بعد اكتمال الإعداد (أو بعد انتهاء مهلة مدتها 30 ثانية). يجب إجراء ذلك مرة واحدة فقط، ويُفضّل أن يكون ذلك عند تشغيل التطبيق.

قد يتم تحميل الإعلانات مسبقًا من خلال حزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C أو حزم SDK الخاصة بشركاء التوسّط عند استدعاء Initialize(). إذا كنت بحاجة إلى الحصول على موافقة من المستخدمين في "المنطقة الاقتصادية الأوروبية"، أو تقديم أي بلاغات خاصة بالطلبات (مثل tag_for_child_directed_treatment أو tag_for_under_age_of_consent)، أو اتخاذ أي إجراء آخر قبل تحميل الإعلانات، تأكَّد من إجراء ذلك من خلال استدعاء firebase::gma::SetRequestConfiguration() قبل إعداد حزمة SDK لإعلانات Google على الأجهزة الجوّالة الخاصة بتطبيقات ++C. لمزيد من المعلومات، يُرجى الاطّلاع على دليل الاستهداف.

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

Android

// 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.
}

iOS

// 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.
  }
}

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

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

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

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

إعلان بيني

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

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

تمت المكافأة

إعلانات تمنح مكافآت للمستخدمين مقابل مشاهدة فيديوهات قصيرة والتفاعل مع "إعلانات تشغيل إصدار بسيط من اللعبة" والاستطلاعات. تُستخدم لتحقيق الربح من التطبيقات المجانية.

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