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

כדאי להשתמש בערכות ה-SDK ל-iOS ול-Android מ-AdMob.

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

   2. מקשרים את AdMobאפליקציית Firebase לפרויקט הקיים ב-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 ולפרוק אותו לספרייה לבחירתכם.

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

Android

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

סיימת! האפליקציה ב-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. מוסיפים ל-Podfile את ה-Pod של Google Mobile Ads C++ SDK:

      pod 'Google-Mobile-Ads-SDK'

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

      pod install
      open YOUR_APP.xcworkspace

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

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

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

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

באנר

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

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

מודעת מעברון

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

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

מתגמל

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

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

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

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

אפשר לבדוק דרכים נוספות למדידת מדדים ולשלב תכונות של Firebase עם AdMob.

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

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

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

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

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

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

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

• הוספה של Firebase SDK ל-Google Analytics ושימוש בו

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

  • להגדיר בקמפיינים מותאמים אישית מה נחשב להמרה.

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

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

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

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

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

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