איך מתחילים להשתמש בהעברת הודעות בענן ב-Firebase באפליקציות Unity

בחירת פלטפורמה: iOS+‎ Android אינטרנט Flutter Unity C++‎


במדריך הזה מוסבר איך להתחיל להשתמש ב-Firebase Cloud Messaging באפליקציות הלקוח של Unity כדי לשלוח הודעות באופן מהימן.

כדי לכתוב אפליקציית לקוח של Firebase Cloud Messaging בפלטפורמות שונות באמצעות Unity, צריך להשתמש ב-API של Firebase Cloud Messaging. ערכת Unity SDK פועלת גם ב-Android וגם ב-Apple, אבל צריך לבצע הגדרות נוספות בכל פלטפורמה.

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

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

  • מתקינים את Unity 2021 LTS ואילך. יכול להיות שגם גרסאות קודמות יהיו תואמות, אבל לא תהיה להן תמיכה פעילה.

  • (פלטפורמות של אפל בלבד) מתקינים את הרכיבים הבאים:

    • ‫Xcode מגרסה 26.2 ואילך
    • ‫CocoaPods מגרסה 1.12.0 ואילך

  • חשוב לוודא שהפרויקט ב-Unity עומד בדרישות הבאות:

    • ב-iOS – מטרגט את iOS מגרסה 15 ואילך
    • ב-tvOS – מטרגט את tvOS 15 ואילך
    • ב-Android – מטרגטת לרמת ה-API המיועדת 24 (Nougat) ומעלה

  • מגדירים מכשיר או משתמשים באמולטור כדי להריץ את פרויקט Unity.

    • ב-iOS או ב-tvOS – מגדירים מכשיר פיזי להפעלת האפליקציה, ומבצעים את המשימות הבאות:

      • משיגים מפתח אימות של שירות ההתראות של אפל (APNs) לחשבון הפיתוח של אפל.
      • מפעילים התראות ב-XCode בקטע App (אפליקציה) > Capabilities (יכולות).

    • ב-Android – באמולטורים צריך להשתמש בתמונת אמולטור עם Google Play.

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

שלב 1: יוצרים פרויקט ב-Firebase

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

שלב 2: רישום האפליקציה ב-Firebase

אתם יכולים לרשום אפליקציה אחת או יותר, או משחק אחד או יותר, כדי לקשר אותם לפרויקט Firebase.

  1. נכנסים למסוף Firebase.

  2. במרכז דף הסקירה הכללית של הפרויקט, לוחצים על הסמל של Unity () כדי להפעיל את תהליך ההגדרה.

    אם כבר הוספתם אפליקציה לפרויקט ב-Firebase, לוחצים על Add app כדי להציג את אפשרויות הפלטפורמה.

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

  4. מזינים את המזהים הספציפיים לפלטפורמה של הפרויקט ב-Unity.

    • ב-iOS – בשדה iOS bundle ID, מזינים את מזהה ה-iOS של הפרויקט ב-Unity.

    • ב-Android – מזינים את מזהה ה-Android של הפרויקט ב-Unity בשדה שם החבילה ל-Android.
      המונחים שם החבילה ומזהה האפליקציה משמשים לעיתים קרובות לסירוגין.

  5. (אופציונלי) מזינים את הכינויים הספציפיים לפלטפורמה של הפרויקט ב-Unity.
    הכינויים האלה הם מזהים פנימיים לנוחות, ורק אתם יכולים לראות אותם במסוף Firebase.

  6. לוחצים על Register app.

שלב 3: מוסיפים קובצי תצורה של Firebase

  1. מורידים את קובצי התצורה של Firebase הספציפיים לפלטפורמה בתהליך העבודה להגדרה במסוף Firebase.

    • ב-iOS – לוחצים על Download GoogleService-Info.plist.

    • ב-Android – לוחצים על Download google-services.json.

  2. פותחים את החלון Project(פרויקט) של הפרויקט ב-Unity ומעבירים את קובצי התצורה לתיקייה Assets.

  3. חוזרים למסוף Firebase, ובמסך תהליך ההגדרה לוחצים על הבא.

שלב 4: מוסיפים את ערכות ה-SDK של Firebase Unity

  1. במסוף Firebase, לוחצים על Download Firebase Unity SDK ומחלצים את קובצי ה-SDK למיקום נוח.

    • תמיד אפשר להוריד שוב את Firebase Unity SDK.

    • ערכת ה-SDK של Firebase Unity לא ספציפית לפלטפורמה.

  2. בפרויקט Unity הפתוח, עוברים אל Assets (נכסים) > Import Package (ייבוא חבילה) > Custom Package (חבילה בהתאמה אישית).

  3. מתוך ה-SDK שחילצתם, בוחרים את מוצרי Firebase הנתמכים שבהם רוצים להשתמש באפליקציה.

    כדי ליהנות מחוויית השימוש הכי טובה ב-Firebase Cloud Messaging, מומלץ להפעיל את Google Analytics בפרויקט. בנוסף, כחלק מההגדרה של Analytics, צריך להוסיף לאפליקציה את חבילת Firebase של Analytics.

    ‫Analytics מופעל

    • ‫מוסיפים את חבילת Firebase עבור Google Analytics: FirebaseAnalytics.unitypackage
    • מוסיפים את החבילה של Firebase Cloud Messaging: FirebaseMessaging.unitypackage

    ‫Analytics לא מופעל

    מוסיפים את החבילה של Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. בחלון Import Unity Package, לוחצים על Import.

  5. חוזרים למסוף Firebase, ובמסך תהליך ההגדרה לוחצים על הבא.

שלב 5: מוודאים שגרסת Google Play Services עומדת בדרישות

חלק מהמוצרים ב-SDK של Firebase Unity ל-Android דורשים את Google Play services. אילו מוצרים תלויים בזה כדי להשתמש במוצרים האלה, צריך לעדכן את Google Play services.

מוסיפים את ההצהרה הבאה של using ואת קוד האתחול בתחילת האפליקציה. אתם יכולים לבדוק אם יש עדכון ל-Google Play services ולעדכן לגרסה הנדרשת לפני שאתם קוראים לשיטות אחרות ב-SDK.

using Firebase.Extensions;

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(task => {
  var dependencyStatus = task.Result;
  if (dependencyStatus == Firebase.DependencyStatus.Available) {
    // Create and hold a reference to your FirebaseApp,
    // where app is a Firebase.FirebaseApp property of your application class.
       app = Firebase.FirebaseApp.DefaultInstance;

    // Set a flag here to indicate whether Firebase is ready to use by your app.
  } else {
    UnityEngine.Debug.LogError(System.String.Format(
      "Could not resolve all Firebase dependencies: {0}", dependencyStatus));
    // Firebase Unity SDK is not safe to use here.
  }
});

הפרויקט ב-Unity רשום ומוגדר לשימוש ב-Firebase.

הגדרה בפלטפורמות של אפל

כך מגדירים את FCM בפלטפורמות של Unity ו-Apple.

העלאת מפתח האימות של APNs

מעלים את מפתח האימות של APNs ל-Firebase. אם עדיין אין לכם מפתח אימות של APNs, הקפידו ליצור מפתח כזה ב-Apple Developer Member Center.

  1. במסוף Firebase, נכנסים אל הגדרות > כללי. לוחצים על הכרטיסייה העברת הודעות בענן.
  2. ‫בקטע APNs authentication key (מפתח אימות של APNs) שמופיע בקטע iOS app configuration (הגדרת אפליקציה ל-iOS), לוחצים על Upload (העלאה) כדי להעלות את מפתח האימות של סביבת הפיתוח, את מפתח האימות של סביבת הייצור או את שניהם. צריך להוסיף לפחות אחד.
  3. עוברים למיקום שבו שמרתם את המפתח, בוחרים אותו ולוחצים על Open. מוסיפים את מזהה המפתח (זמין ב-Apple Developer Member Center) ולוחצים על Upload.

הפעלת התראות בפלטפורמות של אפל

  1. לוחצים על הפרויקט ב-Xcode, ואז בוחרים בכרטיסייה General (כללי) ב-Editor area (אזור העריכה).
  2. גוללים אל Linked Frameworks and Libraries (ספריות וסביבות עבודה מקושרות) ולוחצים על הכפתור + כדי להוסיף סביבת עבודה.
  3. בחלון שמופיע, גוללים אל UserNotifications.framework, לוחצים על הרשומה הזו ואז על Add.
  4. לוחצים על הפרויקט ב-Xcode, ואז בוחרים בכרטיסייה Capabilities (יכולות) ב-Editor area (אזור העריכה).
  5. מעבירים את המתג התראות למצב מופעל.
  6. גוללים אל מצבי רקע ומעבירים את המתג למצב מופעל.
  7. מסמנים את התיבה Remote notifications (התראות מרחוק) בקטע Background Modes (מצבי רקע).

מפעילים את Firebase Cloud Messaging

הפעלת הרישום באמצעות מזהה ההתקנה של Firebase

כדי לרשום את מופע האפליקציה ב-Firebase Cloud Messaging באמצעות מזהה ההתקנה של Firebase‏ (FID), צריך קודם להפעיל את מזהי ה-FID בהגדרות של האפליקציה גם בפלטפורמות של Android וגם בפלטפורמות של Apple:

Android

מוסיפים את הרכיב <meta-data> הבא בתוך הרכיב <application> של AndroidManifest.xml:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

Swift

מוסיפים את המפתח FirebaseMessagingInstallationIdEnabled ל-Info.plist ומגדירים אותו ל-YES:

FirebaseMessagingInstallationIdEnabled = YES

הרשמה לאירועים של FCM

הספרייה Firebase Cloud Messaging תופעל כשמוסיפים פונקציות handler לאירועים RegistrationReceived או MessageReceived.

במהלך ההפעלה, Firebase Cloud Messaging רושם את המופע של אפליקציית הלקוח כדי לקבל הודעות באמצעות מזהה ההתקנה של Firebase‏ (FID). האפליקציה מקבלת את ה-FID עם האירוע RegistrationReceived, שצריך לשמור במטמון בשרת כדי לטרגט את המכשיר הספציפי הזה להודעות.

בנוסף, צריך להירשם לאירוע OnMessageReceived כדי לקבל הודעות נכנסות.

ההגדרה תיראה כך:

public void Start() {
  Firebase.Messaging.FirebaseMessaging.RegistrationReceived +=
      OnRegistrationReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived +=
      OnMessageReceived;
}

public void OnRegistrationReceived(
    object sender,
    Firebase.Messaging.RegistrationReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received Firebase Installation ID: " +
                        e.InstallationId);
  // TODO: Send the Firebase Installation ID (FID) to your app server to target
  // this device for messages.
}

public void OnMessageReceived(
    object sender,
    Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

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

רישום ידני כשההפעלה האוטומטית מושבתת

אפשר גם להפעיל את הרישום באופן ידני באמצעות FCM בזמן הריצה, באמצעות RegisterAsync():

// Manually register with FCM
Firebase.Messaging.FirebaseMessaging.RegisterAsync().ContinueWith(task => {
  if (task.IsCompleted) {
    // Note: The registered Installation ID is delivered to the
    // RegistrationReceived event handler.
    UnityEngine.Debug.Log("Registered with FCM");
  }
});

גישה לטוקן הרישום של FCM (הוצא משימוש)

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

// Deprecated: Use RegistrationReceived instead
public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}

public void OnTokenReceived(
    object sender,
    Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

הגדרה בפלטפורמות של Android

כך מגדירים את FCM בפלטפורמות Unity ו-Android.

הגדרת פעילות של נקודת כניסה ב-Android

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

הפלאגין של Firebase Cloud Messaging ל-Unity ב-Android כולל שני קבצים נוספים:

  • ‫Assets/Plugins/Android/libmessaging_unity_player_activity.jar מכיל פעילות שנקראת MessagingUnityPlayerActivity שמחליפה את UnityPlayerActivity הרגיל.
  • הפקודה Assets/Plugins/Android/AndroidManifest.xml מורה לאפליקציה להשתמש ב-MessagingUnityPlayerActivity כנקודת הכניסה לאפליקציה.

הקבצים האלה מסופקים כי ברירת המחדל של UnityPlayerActivity לא מטפלת במעברים של מחזור החיים של הפעילות ב-onStop, onRestart או מטמיעה את onNewIntent שנדרש כדי ש-Firebase Cloud Messaging יטפל בצורה נכונה בהודעות נכנסות.

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

אם האפליקציה לא משתמשת ב-UnityPlayerActivity שמוגדר כברירת מחדל, צריך להסיר את ה-AndroidManifest.xml שסופק ולוודא שהפעילות בהתאמה אישית מטפלת כראוי בכל המעברים של מחזור החיים של הפעילות ב-Android (בהמשך מוצגת דוגמה לאופן שבו אפשר לעשות את זה). אם הפעילות המותאמת אישית שלכם מרחיבה את UnityPlayerActivity, אתם יכולים במקום זאת להרחיב את com.google.firebase.MessagingUnityPlayerActivity, שמיישמת את כל השיטות הנדרשות.

אם אתם משתמשים ב-Activity בהתאמה אישית ולא מרחיבים את com.google.firebase.MessagingUnityPlayerActivity, אתם צריכים לכלול את קטעי הקוד הבאים ב-Activity.

/**
 * Workaround for when a message is sent containing both a Data and Notification payload.
 *
 * When the app is in the background, if a message with both a data and notification payload is
 * received the data payload is stored on the Intent passed to onNewIntent. By default, that
 * intent does not get set as the Intent that started the app, so when the app comes back online
 * it doesn't see a new FCM message to respond to. As a workaround, we override onNewIntent so
 * that it sends the intent to the MessageForwardingService which forwards the message to the
 * FirebaseMessagingService which in turn sends the message to the application.
 */
@Override
protected void onNewIntent(Intent intent) {
  Intent message = new Intent(this, MessageForwardingService.class);
  message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT);
  message.putExtras(intent);
  message.setData(intent.getData());
  // For earlier versions of Firebase C++ SDK (< 7.1.0), use `startService`.
  // startService(message);
  MessageForwardingService.enqueueWork(this, message);
}

/**
 * Dispose of the mUnityPlayer when restarting the app.
 *
 * This makes sure that when the app starts up again it does not start with stale data.
 */
@Override
protected void onCreate(Bundle savedInstanceState) {
  if (mUnityPlayer != null) {
    mUnityPlayer.quit();
    mUnityPlayer = null;
  }
  super.onCreate(savedInstanceState);
}

גרסאות חדשות של Firebase C++ SDK (מגרסה 7.1.0 ואילך) משתמשות ב-JobIntentService, וצריך לבצע שינויים נוספים בקובץ AndroidManifest.xml.

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

מסירת הודעות ב-Android

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

הודעות שמתקבלות כשהאפליקציה פועלת ברקע משתמשות בתוכן של שדה ההתראה כדי לאכלס את ההתראה במגש המערכת, אבל תוכן ההתראה הזה לא יועבר אל FCM. כלומר, הערך של FirebaseMessage.Notification יהיה null.

בקצרה:

מצב האפליקציה התראה נתונים שניהם
חזית Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
רקע מגש המערכת Firebase.Messaging.FirebaseMessaging.MessageReceived התראה: מגש המערכת
נתונים: בתוספות של ה-intent.

‫FCM מאפשר לשלוח הודעות שמכילות קישור עומק לאפליקציה. כדי לקבל הודעות שמכילות קישור עומק, צריך להוסיף מסנן Intent חדש לפעילות שמטפלת בקישורי עומק באפליקציה. מסנן ה-Intent צריך לתפוס קישורי עומק של הדומיין. בקובץ AndroidManifest.xml:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/>
</intent-filter>

אפשר גם לציין תו כללי לחיפוש כדי להגמיש את מסנן ה-Intent. לדוגמה:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="*.example.com" android:scheme="http"/>
  <data android:host="*.example.com" android:scheme="https"/>
</intent-filter>

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

מניעת הפעלה אוטומטית

FCM יוצר טוקן רישום לטירגוט לפי מכשיר. כשנוצר אסימון, הספרייה מעלה את המזהה ואת נתוני ההגדרות ל-Firebase. אם אתם רוצים לקבל הסכמה מפורשת לפני השימוש בטוקן, אתם יכולים למנוע את היצירה שלו בזמן ההגדרה על ידי השבתת FCM (וב-Android, השבתת Analytics). אתם יכולים להוסיף ערך מטא-נתונים ל-Info.plist (לא ל-GoogleService-Info.plist) ב-Apple, או ל-AndroidManifest.xml ב-Android:

Android

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
  <meta-data android:name="firebase_analytics_collection_enabled"
             android:value="false" />
</application>

Swift

FirebaseMessagingAutoInitEnabled = NO

כדי להפעיל מחדש את FCM, אפשר לבצע קריאה בזמן ריצה:

Firebase.Messaging.FirebaseMessaging.RegistrationOnInitEnabled = true;

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

השלבים הבאים

אחרי שתסיימו את שלבי ההגדרה, תוכלו לבחור אחת מהאפשרויות הבאות כדי להמשיך להשתמש ב-FCM ל-Unity: