البدء

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

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

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

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

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

Android

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

iOS

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

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

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

  1. سجّل الدخول إلى حساب AdMob أو اشترِك فيه.

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

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

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

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

Android

ننصح باستخدام CMake، ولكن يمكنك العثور على تعليمات حول إنشاء ndk في دليل البدء العام لحزمة تطوير البرامج (SDK) لـ Firebase C++ لربط 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 - أضف المحتوى التالي، والذي يتضمن تبعية المكتبة لـ C++ SDK لإعلانات Google على الأجهزة الجوّالة.

    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

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

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

    sudo gem install cocoapods --pre

  2. أضِف مجموعة "إعلانات Google على الأجهزة الجوّالة" من حزمة تطوير البرامج (SDK) غير المضغوطة.

    1. أنشئ ملف Podfile إذا لم يكن لديك ملف بالفعل:

      cd APP_DIRECTORY
pod init

    2. إلى ملف Podfile، أضِف اللوحات الخاصة بحزمة SDK الخاصة بـ C++ لإعلانات Google على الأجهزة الجوّالة، وحزمة SDK لمنصة Google User Messaging Platform، وحزمة SDK الأساسية البسيطة من Firebase (مطلوبة من 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++ لاستخدام حزمة C++ SDK لإعلانات Google على الأجهزة الجوّالة بدون أي خدمات Firebase أخرى.

ضبط رقم تعريف تطبيق AdMob لتطبيقك

Android

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

iOS

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

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

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

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

إليك مثال على كيفية الاتصال بـ 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.
  }
}

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

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

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

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

إعلان بيني

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

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

تم منح المكافأة

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

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