الخطوات الأولى


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

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

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

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

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

Android

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

iOS

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

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

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

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

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

تثبيت حزمة تطوير البرامج لإعلانات Google على الأجهزة الجوّالة باستخدام لغة C++

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

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

Android

ننصح باستخدام CMake، ولكن يمكنك العثور على تعليمات حول ndk-build في عام بدء استخدام حزمة تطوير البرامج (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، المحتوى التالي الذي يتضمّن الاعتمادية على المكتبة لحزمة تطوير البرامج (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

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

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

    sudo gem install cocoapods --pre

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

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

      cd APP_DIRECTORY
pod init

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

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

    3. ثبِّت وحدات pod، ثم افتح ملف .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

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

iOS

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

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

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

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

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

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

إعلان بيني

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

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

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

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

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