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

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


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

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

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

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

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

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

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

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

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

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

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

      • משיגים מפתח אימות של שירות ההתראות של אפל (APNs) לחשבון הפיתוח שלכם ב-Apple.
      • מפעילים התראות ב-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 של הפרויקט ב-Unity בשדה מזהה החבילה ב-iOS.

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

  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, נכנסים אל הגדרות > כללי. לאחר מכן לוחצים על הכרטיסייה Cloud Messaging.
  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 ושל אפל:

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="true" >
</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: