מתחילים

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

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

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

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

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

Android

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

iOS

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

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

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

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

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

התקנת Google Mobile Ads C++ SDK

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

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

Android

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

  1. בקובץ gradle.properties של הפרויקט, מציינים את המיקום של ה-SDK אחרי הורדת ה-ZIP:

    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 לנייד לפרויקט iOS.

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

    sudo gem install cocoapods --pre

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

    1. אם עדיין אין לכם קובץ Podfile, צריך ליצור אותו:

      cd APP_DIRECTORY
pod init

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

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

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

      pod install
open APP.xcworkspace

    4. מוסיפים לפרויקט את ה-frameworks הבאות מ-Firebase C++ SDK:

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

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

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

Android

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

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 SDK או ערכות ה-SDK של שותף בתהליך בחירת הרשת (Mediation) בקריאה ל-Initialize(). אם אתם צריכים לקבל הסכמה ממשתמשים באזור הכלכלי האירופי (EEA), להגדיר סימונים ספציפיים לבקשה (כמו tag_for_child_directed_treatment או tag_for_under_age_of_consent) או לבצע פעולה אחרת לפני טעינת מודעות, הקפידו לעשות זאת על ידי הפעלת firebase::gma::SetRequestConfiguration() לפני ההפעלה של Google Mobile Ads SDK עבור 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.

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

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

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

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

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

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

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

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

ההטבה הופעלה

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

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