התחל בעבודה


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

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

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

אם זו הפעם הראשונה שאתם קוראים את המדריך הזה, מומלץ להוריד את אפליקציית הבדיקה של Google Mobile Ads ב-C++‎ ולפעול לפי ההוראות.

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

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

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

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

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 – שכולל את יחסי התלות בספרייה של 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. מוסיפים את ה-pod של Google Mobile Ads מה-SDK ללא האפסון.

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

      cd APP_DIRECTORY
pod init

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

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

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

      pod install
open APP.xcworkspace

    4. מוסיפים לפרויקט את המסגרות הבאות מ-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 שניות). צריך לעשות זאת רק פעם אחת, רצוי בזמן ההשקה של האפליקציה.

ייתכן שהמודעות ייטענו מראש על ידי Google Mobile Ads C++ SDK או על ידי ערכות ה-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 הוא complete וקוד השגיאה שלו הוא firebase::gma::kAdErrorCodeNone, סימן שהפעולה הושלמה בהצלחה.

אפשר גם לרשום קריאות חוזרות (callbacks) שיופעלו כשהפעולה 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 יש כמה פורמטים שונים של מודעות, כך שתוכלו לבחור את הפורמט שמתאים ביותר לחוויית המשתמש של האפליקציה.

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

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

מעברון

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

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

ההטבה הופעלה

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

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