البدء


هذا الدليل مخصّص للناشرين الذين يريدون تحقيق الربح من تطبيق 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 أو إصدار أحدث
  • استهداف نظام التشغيل iOS 10.0 أو إصدار أحدث

إعداد تطبيقك في حسابك على 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، وحزمة User Messaging Platform SDK، وحزمة 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 لتطبيقك

Android

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

iOS

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

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

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

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

إعلان بيني

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

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

تمت المكافأة

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

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