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

בחירת פלטפורמה: ‫iOS+‎ Android Web 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‏ 23 (Marshmallow) ומעלה

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

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

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

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

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

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

  6. לוחצים על Register app (רישום האפליקציה).

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

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

    • ב-iOS – לוחצים על Download GoogleService-Info.plist (הורדה של GoogleService-Info.plist).

    • ב-Android — לוחצים על הורדה של google-services.json.

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

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

שלב 4: מוסיפים את Firebase Unity SDKs

  1. במסוף Firebase, לוחצים על הורדה של Firebase Unity SDK, ואז מבטלים את הדחיסה של ה-SDK במיקום נוח.

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

    • ‫Firebase Unity SDK לא ספציפי לפלטפורמה.

  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. בחלון ייבוא חבילת Unity, לוחצים על ייבוא.

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

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

חלק מהמוצרים ב-Firebase Unity SDK ל-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. מחפשים את המיקום שבו שמרתם את המפתח, בוחרים אותו ולוחצים על פתיחה. מוסיפים את מזהה המפתח (שזמין ב-Apple Developer Member Center) ולוחצים על העלאה.

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

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

אתחול Firebase Cloud Messaging

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

כדי להפעיל את הרישום של מופע האפליקציה ב-Firebase Cloud Messaging באמצעות מזהה ההתקנה (FID) של Firebase, קודם צריך להפעיל את מזהי ההתקנה בהגדרות של האפליקציה בפלטפורמות 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 תאותחל כשמוסיפים פונקציות לטיפול באירועים 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, שמטמיעה את כל השיטות הנדרשות.

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

/**
 * 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

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

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

בקצרה:

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

‫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 for Unity: