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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   • ב-Android – עוברים אל Android > הגדרות הנגן > הגדרות אחרות.

   המזהה של פרויקט 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, בתהליך ההגדרה לוחצים על Next.

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

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, בתהליך ההגדרה לוחצים על Next.

שלב 5: מוודאים שגרסת Google Play Services עומדת בדרישות

ה-SDK של Unity Firebase ל-Android מחייב את ה-Google Play services, שחייב להיות עדכני כדי שאפשר יהיה להשתמש ב-SDK.

מוסיפים את ההצהרה הבאה של using ואת קוד האתחול בתחילת האפליקציה. אפשר לבדוק את Google Play services ולעדכן את הגרסה הנדרשת על ידי Firebase Unity ה-SDK לפני קריאה לשיטות אחרות ב-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.

העלאת מפתח האימות של נקודות ה-APN לתמיכה של Apple

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

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

2. בקטע APNs authentication key בקטע iOS app configuration, לוחצים על הלחצן Upload.

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

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

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

1. לוחצים על הפרויקט ב-Xcode ובוחרים בכרטיסייה General מEditor area.

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

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

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

1. לוחצים על הפרויקט ב-Xcode ובוחרים בכרטיסייה Capabilities מEditor area.

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

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

4. מסמנים את התיבה התראות מרחוק בקטע מצבי רקע.

אתחול של Firebase Cloud Messaging

ספריית Firebase Cloud Message תאופס כשתוסיפו מנהלים לאירועים 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 ב-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="false" >
</service>

הערה לגבי שליחת הודעות ב-Android

כשהאפליקציה לא פועלת בכלל והמשתמש מקייש על התראה, ההודעה לא מנותבת כברירת מחדל דרך פונקציות ה-callbacks המובנות של 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 מאפשר לשלוח הודעות שמכילות קישור עומק לאפליקציה. כדי לקבל הודעות שמכילות קישור עומק, צריך להוסיף פילטר חדש של כוונת השימוש לפעילות שמטפלת בקישורי עומק באפליקציה. פילטר כוונת השימוש אמור לזהות קישורי עומק של הדומיין שלכם. אם ההודעות לא מכילות קישור עומק, ההגדרה הזו לא נחוצה. בקובץ 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>

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

השלבים הבאים

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

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

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

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