תחילת עבודה


המדריך הזה מיועד לבעלי אפליקציות שרוצים להפעיל מונטיזציה באפליקציית 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 כמו שמתואר במדריך ל-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 כדי לעקוב אחרי סטטוס הסיום של הפעלת method

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

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

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

מעברון

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

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

ההטבה הופעלה

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

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