תחילת העבודה עם AdMob בפרויקט C++‎

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

אם עדיין לא עשיתם זאת, תוכלו לקרוא על כל היתרונות של השימוש ב-AdMob, ב-Firebase וב-Google Analytics ביחד.

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

לפני שמתחילים

• אם עדיין אין לכם פרויקט ב-Firebase ואפליקציה ב-Firebase, תצטרכו לפעול לפי השלבים במדריך לתחילת העבודה עם Firebase: הוספת Firebase לפרויקט C++‎.

• אתם צריכים לוודא ש-Google Analytics מופעל בפרויקט שלכם ב-Firebase:

  • אם אתם יוצרים פרויקט חדש ב-Firebase, צריך להפעיל את Google Analytics במהלך תהליך יצירת הפרויקט.

  • אם יש לכם פרויקט קיים ב-Firebase שלא הפעלתם בו את Google Analytics, תוכלו להפעיל את Google Analytics דרך הכרטיסייה Integrations בקטע settings > Project settings.

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

1. צריך לרשום כל וריאנט של האפליקציה בפלטפורמה כאפליקציית AdMob.

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

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

   תתבקשו להוסיף את ה-SDK של Mobile Ads לאפליקציה. בהמשך המדריך מפורטות הוראות לביצוע המשימה הזו.

2. מקשרים כל אחת מ-AdMob האפליקציות אל אפליקציית Firebase המתאימה.

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

   לכל גרסה של הפלטפורמה, מבצעים את שני השלבים הבאים בלוח הבקרה Apps בחשבון AdMob:

   1. מפעילים את מדדי המשתמשים כדי לאפשר ל-AdMob לעבד ולהציג נתונים שנאספו מ-Analytics בחשבון AdMob שלכם. זו גם הגדרה נדרשת כדי לקשר את אפליקציית AdMob ל-Firebase.

   2. מקשרים את אפליקציית AdMob לפרויקט Firebase הקיים ולאפליקציית Firebase התואמת.

      חשוב להזין את אותו שם חבילה (Android) או מזהה חבילה (iOS) שהזנתם לאפליקציית Firebase. שם החבילה או מזהה החבילה של אפליקציית Firebase מופיעים בכרטיס האפליקציות שלך בדף settings > הגדרות הפרויקט.

שלב 2: מוסיפים את מזהה האפליקציה AdMob לאפליקציה

Android

מוסיפים את מזהה האפליקציה AdMob לקובץ AndroidManifest.xml של האפליקציה באמצעות תג <meta-data>, כפי שמתואר בהמשך.

<manifest>
    <application>
        <!-- Sample AdMob App ID: ca-app-pub-3940256099942544~3347511713 -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ADMOB_APP_ID"/>
    </application>
</manifest>

iOS

בקובץ Info.plist של האפליקציה, מוסיפים מפתח GADApplicationIdentifier עם ערך מחרוזת של מזהה האפליקציה AdMob.

אפשר לבצע את השינוי הזה באופן פרוגרמטי:

<!-- Sample AdMob App ID: ca-app-pub-3940256099942544~1458002511 -->
<key>GADApplicationIdentifier</key>
<string>ADMOB_APP_ID</string>

לחלופין, אפשר לערוך אותו בעורך רשימת המלונות:

שלב 3: מוסיפים את Google Mobile Ads SDK

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

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

Android

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. מסנכרנים את האפליקציה כדי לוודא שלכל הרכיבים התלויים יש את הגרסאות הנדרשות.

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

iOS

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

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

   sudo gem install cocoapods --pre

2. מוסיפים את ה-pod Google Mobile Ads מ-SDK ללא האפסון.

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

      cd YOUR_APP_DIRECTORY
      pod init

   2. מוסיפים את ה-pod של Google Mobile Ads C++ SDK ל-Podfile:

      pod 'Google-Mobile-Ads-SDK'

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

      pod install
      open YOUR_APP.xcworkspace

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

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

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

שלב 4: מפעילים את Google Mobile Ads SDK

לפני טעינת המודעות, צריך להפעיל את ה-SDK של Mobile Ads על ידי קריאה ל-firebase::gma::Initialize().

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

דוגמה לקריאה ל-Initialize():

// 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.
}

// 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 אפשר לקבוע את סטטוס ההשלמה של הקריאות ל-method האסינכרוני.

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

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

שלב 5: בוחרים פורמט מודעה להטמעה באפליקציה

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

באנר

מודעות מלבניות שמופיעות בחלק העליון או התחתון של מסך המכשיר

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

מודעת מעברון

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

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

מתגמל

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

מודעות מתגמלות (או 'מבוססות-תגמול') יכולות לעזור לכם לייצר הכנסות ממשתמשים שאינם משלמים על השימוש באפליקציה.

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

נושאים מעניינים אחרים

הצגת מדדי משתמשים ונתוני ניתוח

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

• בכרטיס מדדי משתמשים בחשבון AdMob (בלוח הבקרה דף הבית או אפליקציות), אפשר לראות מדדי משתמשים שנבחרו מתוך נתוני ניתוח הנתונים שנאספו, כמו משך הסשן הממוצע, הכנסה ממוצעת לכל משתמש (ARPU) ושיעורי שימור.

• במרכז הבקרה של Analytics במסוף Firebase אפשר לראות נתונים סטטיסטיים מצטברים וסיכומים של מדדים מרכזיים. אם מוסיפים את Firebase SDK ל-Google Analytics, אפשר גם לסמן המרות בקמפיינים פרסומיים וליצור קהלים מותאמים אישית במסוף Firebase.

לתשומת ליבכם: כדי לייצג בצורה טובה יותר את המדדים הכנסה ממוצעת למשתמש (ARPU) והכנסה ממוצעת לכל משתמש משלם (ARPPU), מומלץ לכלול בנוסחת החישוב של ההכנסות של המדדים האלה נתונים מאירוע מותאם אישית של Analytics שנקרא ecommerce_purchase (כך עושים זאת).

(אופציונלי) שימוש בתכונות נוספות של Google Analytics ו-Firebase

נהנים מיותר הזדמנויות ותכונות כדי לשפר את המונטיזציה באפליקציה ואת העניין של המשתמשים בה:

• מוסיפים את Firebase SDK for Google Analytics ומשתמשים בו

  • מטמיעים באפליקציה רישום ביומן של אירועים מותאמים אישית.

  • סימון המרות בקמפיינים פרסומיים בהתאמה אישית.

  • הוספה של נתוני אירועים מסוג ecommerce_purchase לחישוב ההכנסות של המדדים הכנסה ממוצעת למשתמש (ARPU) והכנסה ממוצעת לכל משתמש משלם (ARPPU).

  מידע נוסף זמין במדריך בנושא שימוש ב-Google Analytics וב-Firebase עם אפליקציות AdMob.

• שימוש במוצרי Firebase אחרים באפליקציה

  אחרי שמוסיפים את Firebase SDK ל-Google Analytics, אפשר להשתמש במוצרים אחרים של Firebase כדי לבצע אופטימיזציה של המודעות באפליקציה.

  • Remote Config מאפשרת לשנות את ההתנהגות והמראה של האפליקציה ללא פרסום עדכון לאפליקציה, ללא עלות וללא הגבלת מספר המשתמשים הפעילים ביום.

  • A/B Testing מאפשר לבדוק שינויים בממשק המשתמש, בתכונות או בקמפיינים לעידוד השימוש באפליקציה, כדי לגלות אם הם משפיעים על המדדים העיקריים שלכם (כמו הכנסה ושימור), לפני שמחילים אותם בקנה מידה נרחב.