תחילת העבודה עם Firebase Cloud Messaging


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

הגדרת אפליקציית לקוח של Firebase Cloud Messaging באמצעות Unity

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

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

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

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

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

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

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

    • ל-iOS – מיועד ל-iOS 13 ומעלה
    • ב-tvOS – טירגוט ל-tvOS 13 ומעלה
    • ל-Android – טירגוט לרמת API‏ 21 (Lollipop) ומעלה

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

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

      • משיגים מפתח אימות של Apple Push Notification בשביל חשבון Apple Developer.
      • מפעילים את ההתראות בדחיפה ב-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. לוחצים על רישום האפליקציה.

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

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

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

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

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

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

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

  1. בFirebase Console, לוחצים על הורדה של 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 (ייבוא חבילת Unity), לוחצים על Import (ייבוא).

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

  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 (יכולות) מתוך Editor area (אזור העריכה).
  5. מעבירים את המתג שליד התראות למצב מופעל.
  6. גוללים אל מצבי רקע ומעבירים אותו למצב מופעל.
  7. בקטע Background Modes (מצבי רקע), מסמנים את תיבת הסימון Remote notifications (התראות מרחוק).

אתחול Firebase Cloud Messaging

ספריית ההודעות בענן ב-Firebase תאותחל כשמוסיפים handlers לאירועים TokenReceived או MessageReceived.

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

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

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

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

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

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

הגדרה באמצעות פלטפורמות Android

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

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

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

‫Firebase Cloud Messaging Unity Plugin ב-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, אתם יכולים להרחיב במקום זאת את 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-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>

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

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

‫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.TokenRegistrationOnInitEnabled = true;

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

השלבים הבאים

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