תחילת עבודה


המדריך הזה מיועד לבעלי אפליקציות שרוצים לייצר הכנסות מאפליקציית 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. מוסיפים לפרויקט את ה-frameworks הבאים מ-Firebase C++ SDK:

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

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

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

Android

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

iOS

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

הפעלה של Google Mobile Ads SDK

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

יכול להיות שהמודעות ייטענו מראש על ידי Google Mobile Ads C++ SDK או על ידי ערכות SDK של שותפים בתהליך בחירת הרשת (Mediation) כשמתבצעת קריאה ל-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 כדי לעקוב אחרי סטטוס ההשלמה של הפעלת method

‫Future מאפשר לכם לקבוע את סטטוס ההשלמה של הפעלות ה-method האסינכרוניות.

לדוגמה, כשהאפליקציה קוראת ל-firebase::gma::Initialize(), נוצר ומוחזר firebase::Future חדש. לאחר מכן, האפליקציה יכולה לבדוק את ה-status() של ה-Future כדי לקבוע מתי תהליך האיניציאליזציה הסתיים. בסיום התהליך, האפליקציה יכולה להפעיל את result() כדי לקבל את ה-AdapterInitializationStatus שנוצר.

ל-methods שמחזירות Future יש method תואם של "תוצאה אחרונה", שאפליקציות יכולות להשתמש בו כדי לאחזר את ה-Future העדכני ביותר לפעולה נתונה. לדוגמה, ל-firebase::gma::Initialize() יש שיטה תואמת שנקראת firebase::gma::InitializeLastResult(), שמחזירה Future שהאפליקציה יכולה להשתמש בו כדי לבדוק את הסטטוס של הפעלת ה-method האחרונה ל-firebase::gma::Initialize().

אם הסטטוס של Future הוא complete וקוד השגיאה הוא firebase::gma::kAdErrorCodeNone, הפעולה הושלמה בהצלחה.

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

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

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

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

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

מעברון

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

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

ההטבה הופעלה

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

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