איך מתחילים להשתמש בהעברת הודעות בענן ב-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. בחלון ייבוא חבילת Unity, לוחצים על ייבוא.

  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. בקטע Background Modes (מצבי הפעלה ברקע), מסמנים את תיבת הסימון Remote notifications (התראות מרחוק).

מפעילים את 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 תאותחל כשמוסיפים פונקציות לטיפול באירועים 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 for Unity: