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

bookmark_border קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

כדי לכתוב את אפליקציית הלקוח 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.

• נכנסים ל-Firebase באמצעות חשבון Google.

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

שלב 1: יצירת פרויקט Firebase

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

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

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

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

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

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

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

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

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

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

   איפה אפשר למצוא את מזהה פרויקט Unity?

   פותחים את הפרויקט ב-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 לאפליקציה.

   Analytics הופעלו 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.

בקצרה:

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

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

FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

טיפול בהודעות עם קישורי עומק ב-Android

‫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. מידע נוסף זמין בדוגמה למתחילים שבה מוצגת הפונקציונליות הזו.

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

• שליחת הודעות בנושאים
• שליחה לקבוצות מכשירים

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