מתחילים


המדריך הזה מיועד לבעלי אפליקציות שרוצים לייצר הכנסות מאפליקציית C++ באמצעות AdMob, באמצעות Firebase. אם אתם מתכננים לכלול את Firebase באפליקציה שלכם, או אם אתם שוקלים לעשות זאת, כדאי לעיין במקום זאת בגרסה של המדריך הזה לשימוש ב-AdMob עם Firebase.

שילוב של C++ SDK של מודעות Google לנייד באפליקציה הוא הצעד הראשון לקראת הצגת מודעות וייצור הכנסות. אחרי השילוב של ה-SDK, אפשר בוחרים פורמט מודעה, כמו מעברון או מודעה מתגמלת, ופועלים לפי השלבים להטמיע אותו.

‏Google Mobile Ads C++ SDK עוטף את ערכות ה-SDK של Google Mobile Ads ל-iOS ול-Android, והוא זמין רק בפלטפורמות האלה. ערכת ה-SDK של מודעות Google לנייד (C++ SDK) מאפשרת שימוש ב-Builds של Firebase C++ כדי לתמוך בפעולות אסינכרוניות, במרחב השמות firebase::gma.

אם זו הפעם הראשונה שאתם קוראים את המדריך הזה, אנחנו ממליצים להוריד ולעקוב אחריו באמצעות בדיקת C++ של מודעות Google לנייד app.

דרישות מוקדמות

Android

  • שימוש ב-Android Studio בגרסה 3.2 ואילך
  • יש לוודא שקובץ ה-build של האפליקציה משתמש בערכים הבאים:
    • minSdkVersion מתוך 16 ומעלה
    • compileSdkVersion של 28 ומעלה

iOS

  • צריך להשתמש ב-Xcode מגרסה 13 ואילך
  • טירגוט ל-iOS מגרסה 10.0 ואילך

הגדרת האפליקציה בחשבון AdMob

כדי לרשום את האפליקציה כאפליקציית AdMob:

  1. כניסה לחשבון או הרשמה בחשבון AdMob.

  2. רושמים את האפליקציה ב-AdMob. השלב הזה יוצר AdMob אפליקציה עם מזהה אפליקציה ייחודי ב-AdMob ותשתמשו בה בהמשך המדריך הזה.

התקנת Google Mobile Ads C++ SDK

מאחר ש-C++ SDK של מודעות Google לנייד נמצא במרחב השמות firebase::gma, מורידים את Firebase C++ SDK, ולאחר מכן מחלצים אותו בספרייה לבחירתכם.

ה-SDK של Firebase עבור C++‎ הוא לא ספציפי לפלטפורמה, אבל נדרש להגדרת ספרייה ספציפית לפלטפורמה.

Android

מומלץ להשתמש ב-CMake, אבל אפשר למצוא הוראות ליצירה של ndk-build כללי תחילת העבודה עם SDK + Firebase ב-Firebase מדריך לקשר את 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 – שכולל את יחסי התלות בספרייה של 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. מסנכרנים את האפליקציה כדי לוודא שלכל הרכיבים התלויים יש את הגרסאות הנדרשות.

iOS

השלבים שבקטע הזה הם דוגמה להוספת Google Mobile Ads SDK ל-C++ לפרויקט iOS.

  1. כדי לקבל את CocoaPods בגרסה 1 ואילך, מריצים את הפקודה:

    sudo gem install cocoapods --pre

  2. מוסיפים את רצף המודעות של Google לנייד מה-SDK לאחר חילוץ.

    1. צריך ליצור Podfile אם אין עדיין:

      cd APP_DIRECTORY
pod init

    2. ל-Podfile, מוסיפים את רצפי המודעות של Google Mobile Ads C++ SDK, Google User Messaging Platform SDK וה-SDK המינימלי של Firebase (נדרש על ידי GMA C++ SDK):

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

    3. מתקינים את רצפי ה-Pod ופותחים את הקובץ .xcworkspace ב-Xcode.

      pod install
open APP.xcworkspace

    4. מוסיפים לפרויקט את ה-frameworks הבאות מ-Firebase C++ SDK:

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

סיימת! האפליקציה ב-C++ מוגדרת להשתמש ב-Google Mobile Ads C++ SDK בלי שירותי Firebase אחרים.

הגדרת מזהה האפליקציה ב-AdMob

Android

פועלים לפי שלב 3 בקטע הגדרת האפליקציה כפי שמתואר במדריך ל-Mobile Ads SDK ל-Android, ואז חוזרים לדף הזה.

iOS

פועלים לפי השלב עדכון קובץ Info.plist כפי שמתואר במדריך ל-Mobile Ads SDK ל-iOS, ואז חוזרים לדף הזה.

איך מפעילים את Google Mobile Ads SDK

לפני טעינת המודעות, צריך להפעיל את Google Mobile Ads C++ SDK באפליקציה באמצעות קריאה ל-firebase::gma::Initialize(). הפונקציה הזו מפעילה את ה-SDK ומבצעת firebase::Future בסיום ההפעלה (או אחרי זמן קצוב של 30 שניות). צריך לעשות זאת רק פעם אחת, רצוי בזמן ההשקה של האפליקציה.

ייתכן שהמודעות ייטענו מראש על ידי ערכות ה-SDK של Google Mobile Ads C++ או ערכות ה-SDK של שותף בתהליך בחירת הרשת כשקוראים אל Initialize(). אם אתם צריכים לקבל הסכמה ממשתמשים באזור הכלכלי האירופי (EEA), להגדיר דגלים ספציפיים לבקשה (כמו tag_for_child_directed_treatment או tag_for_under_age_of_consent) או לבצע פעולה אחרת לפני טעינת המודעות, עליכם להפעיל את firebase::gma::SetRequestConfiguration() לפני שמפעילים את Google Mobile Ads C++ SDK. מידע נוסף זמין במדריך לטירגוט.

כך אפשר להתקשר אל 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, אז הפעולה הסתיימה בהצלחה.

אפשר גם לרשום קריאה חוזרת (callback) להפעלה לאחר השלמת Future. במקרים מסוימים, פונקציית ה-callback תפעל בשרשור אחר, לכן חשוב לוודא שהקוד שלכם בטוח לשרשור. קטע הקוד הזה משתמש ב-function pointer ל-callback:

// 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 Mobile Ads ב-C++ יובא, ותוכלו להטמיע מודעה. ב-AdMob יש כמה פורמטים שונים של מודעות, כך שתוכלו לבחור את הפורמט שמתאים ביותר לחוויית המשתמש באפליקציה.

מודעות מלבניות שמופיעות בחלק העליון או התחתון של מסך המכשיר. מודעות באנר מוצגות במסך בזמן שהמשתמשים יוצרים אינטראקציה עם האפליקציה, יתבצע רענון אוטומטי לאחר פרק זמן מסוים. אם זו הפעם הראשונה שאתם משתמשים בנייד פרסום – זה מקום מצוין להתחיל בו.

הטמעת מודעות באנר

מעברון

מודעות במסך מלא שמכסות את ממשק האפליקציה עד שהמשתמש סוגר אותן. מומלץ להציג אותן בהפסקות טבעיות בזרימה של האפליקציה, למשל בין שלבים במשחק או מיד אחרי השלמת משימה.

הטמעת מודעות מעברון

ההטבה הופעלה

מודעות שמציעות למשתמשים תגמולים בתמורה לצפייה בסרטונים קצרים ולאינטראקציה עם הילדים מודעות וסקרים. משמש למונטיזציה מאפליקציות חינמיות.

הטמעת מודעות מתגמלות