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

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

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

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

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

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

  1. נכנסים למסוף Firebase.

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

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

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

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

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

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

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

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

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

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

    • ב-iOS – לוחצים על Download GoogleService-Info.plist.

    • ב-Android – לוחצים על Download google-services.json.

  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 של Firebase Unity ל-Android, צריך להתקין את Google Play services בגרסה עדכנית.

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

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.

  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.

בקצרה:

מצב האפליקציה התראה נתונים שניהם
חזית Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
רקע מגש המערכת Firebase.Messaging.FirebaseMessaging.MessageReceived התראה: מגש המערכת
נתונים: ב-extras של ה-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.TokenRegistrationOnInitEnabled = true;

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

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>

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

השלבים הבאים

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

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

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