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

שלב 4: מוסיפים ערכות SDK של Firebase Unity

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

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

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

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

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