התחל בעבודה


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

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

‫Google Mobile Ads C++ SDK הוא מעטפת של Google Mobile Ads iOS SDK ו-Google Mobile Ads Android SDK, והוא זמין רק בפלטפורמות האלה. ‫Google Mobile Ads C++ SDK משתמש במבני 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 ואז לחלץ אותו לספרייה שתבחרו.

‫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 – מוסיפים את התוכן הבא, שכולל את התלות בספרייה של 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 C++ SDK לפרויקט 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 כמו שמתואר במדריך ל-iOS Mobile Ads SDK, ואז חוזרים לדף הזה.

הפעלה של 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, סימן שהפעולה הושלמה בהצלחה.

אפשר גם לרשום קריאות חוזרות (callback) שיופעלו כשפעולת 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.
  }
}

בחירת פורמט מודעה

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

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

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

מעברון

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

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

ההטבה הופעלה

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

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