הגדרת אפליקציית לקוח של העברת הודעות בענן ב-Firebase באמצעות 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.

  1. במסוף Firebase, לוחצים על הוספת פרויקט.

    • כדי להוסיף משאבי Firebase לפרויקט קיים Google Cloud צריך להזין את שם הפרויקט או לבחור אותו מהתפריט הנפתח.

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

  2. אם תופיע בקשה, תצטרכו לקרוא את התנאים של Firebase ולאשר אותם.

  3. לוחצים על המשך.

  4. (אופציונלי) מגדירים את Google Analytics לפרויקט, כדי ליהנות מחוויה אופטימלית באמצעות המוצרים הבאים של Firebase:‏ Firebase A/B Testing,‏ Cloud Messaging,‏ Crashlytics,‏ In-App Messaging ו-Remote Config (כולל התאמה אישית).

    בוחרים חשבון Google Analytics קיים או יוצרים חשבון חדש. אם יוצרים חשבון חדש, בוחרים את Analytics מיקום הדיווח, ואז מאשרים את הגדרות שיתוף הנתונים ואת Google Analytics התנאים של הפרויקט.

  5. לוחצים על יצירת פרויקט (או על הוספת Firebase, אם מוסיפים את Firebase לפרויקט קיים של Google Cloud).

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

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

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

  1. עוברים אל מסוף Firebase.

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

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

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

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

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

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

    פותחים את הפרויקט ב-Unity IDE ועוברים לקטע ההגדרות של כל פלטפורמה:

    • ב-iOS — עוברים אל Build Settings > iOS (הגדרות בנייה > iOS).

    • ב-Android — עוברים אל Android > Player Settings > Other Settings.

    מזהה פרויקט Unity הוא הערך של מזהה החבילה (לדוגמה: com.yourcompany.yourproject).

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

  6. לוחצים על רישום האפליקציה.

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

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

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

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

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

    • תמיד אפשר להוריד שוב את קובץ התצורה של Firebase.

    • מוודאים שלא נוספו תווים לשם של קובץ ההגדרות, כמו (2).

  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 לאפליקציה.

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

    מוסיפים את החבילה ל-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.

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

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

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

  2. בקטע הגדרת אפליקציה ל-iOS, בשדה מפתח אימות של APNs, לוחצים על לחצן העלאה.

  3. מדפדפים למיקום שבו שמרתם את המפתח, בוחרים אותו ולוחצים על פתיחה. מוסיפים את מזהה המפתח (שזמין ב- Apple Developer Member Center) ולוחצים על העלאה.

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

שלב 1: מוסיפים מסגרת של הודעות למשתמש

  1. לוחצים על הפרויקט ב-Xcode ואז בוחרים בכרטיסייה General (כללי) מתוך אזור העריכה.

  2. גוללים למטה אל Linked Frameworks and Libraries (מסגרות וספריות מקושרות) ולוחצים על הלחצן + כדי להוסיף מסגרת.

  3. בחלון שמופיע, גוללים אל UserNotifications.framework, לוחצים על הרשומה הזו ואז על Add (הוספה).

שלב 2: הפעלת התראות

  1. לוחצים על הפרויקט ב-Xcode, ואז בוחרים בכרטיסייה Capabilities (יכולות) מתוך אזור העריכה.

  2. מעבירים את המתג שליד התראות למצב מופעל.

  3. גוללים למטה אל מצבי רקע ומעבירים את המתג למצב מופעל.

  4. בקטע Background Modes (מצבי רקע), מסמנים את תיבת הסימון Remote notifications (התראות מרחוק).

אתחול Firebase Cloud Messaging

ספריית ההודעות בענן ב-Firebase תאותחל כשמוסיפים פונקציות לטיפול באירועים 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

ב-Android, ‏ Firebase Cloud Messaging מגיע עם פעילות של נקודת כניסה בהתאמה אישית שמחליפה את UnityPlayerActivity שמוגדר כברירת מחדל. אם אתם לא משתמשים בנקודת כניסה מותאמת אישית, ההחלפה הזו מתבצעת באופן אוטומטי ולא תצטרכו לבצע פעולות נוספות. אפליקציות שלא משתמשות בנקודת הכניסה Activity שמוגדרת כברירת מחדל, או שמספקות Assets/Plugins/AndroidManifest.xml משלהן, יצטרכו הגדרה נוספת.

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, אתם יכולים להרחיב במקום זאת את 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 older 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 ensures 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

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

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

בקצרה:

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

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

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

AndroidSwift
<?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>
FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

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>

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

השלבים הבאים

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

כדי להוסיף לאפליקציה התנהגויות אחרות ומתקדמות יותר, אפשר לעיין במדריכים לשליחת הודעות משרת אפליקציה:

חשוב לזכור: כדי להשתמש בתכונות האלה, צריך להטמיע הטמעה בצד השרת.