שנתחיל?

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

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

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

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

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

Android

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

iOS

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

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

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

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

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

איך מתקינים את C++ SDK של מודעות Google לנייד

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

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

Android

אנחנו ממליצים להשתמש ב-CMake, אבל אפשר למצוא הוראות ל-ndk-build במדריך הכללי שלנו לתחילת העבודה ב-Firebase C++ SDK כדי לקשר את libfirebase_app.a ואת libfirebase_gma.a לאפליקציה שלך.

  1. ציינו את המיקום של ה-SDK שפרוס בקובץ gradle.properties:

    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

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

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

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

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

      cd APP_DIRECTORY
      pod init
      
    2. לקובץ ה-Podfile, מוסיפים את קטעי ה-pod של Google Mobile Ads C++ SDK, את Google User Messaging Platform SDK ואת ה-SDK המינימלי של Firebase Core SDK (הנדרש על ידי GMA C++ SDK):

      pod 'Firebase/CoreOnly'
      pod 'Google-Mobile-Ads-SDK'
      pod 'GoogleUserMessagingPlatform'
      
    3. מתקינים את רכיבי ה-pod ואז פותחים את הקובץ .xcworkspace ב-Xcode.

      pod install
      open APP.xcworkspace
      
    4. מוסיפים לפרויקט את המסגרות הבאות מ-SDK של Firebase C++:

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

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

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

Android

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

iOS

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

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

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

יכול להיות שהמודעות ייטענו מראש על ידי ערכות ה-SDK של 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 הושלם וקוד השגיאה שלו הוא firebase::gma::kAdErrorCodeNone, הפעולה הושלמה בהצלחה.

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

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

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

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

פרסומת מרווח ביניים

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

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

ההטבה הופעלה

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

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