הגדר אפליקציית לקוח Firebase Cloud Messaging עם Unity

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

לפני שאתה מתחיל

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

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

  • (iOS בלבד) התקן את הדברים הבאים:

    • Xcode 13.3.1 ומעלה
    • CocoaPods 1.10.0 ומעלה

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

    • עבור iOS - מכוון ל-iOS 10 ומעלה

    • עבור אנדרואיד - מתמקד ברמת API 19 (KitKat) ומעלה

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

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

      • השג מפתח אימות של Apple Push Notification עבור חשבון ה-Apple Developer שלך.
      • אפשר הודעות דחיפה ב-XCode תחת אפליקציה > יכולות .

    • עבור אנדרואיד - אמולטורים חייבים להשתמש בתמונת אמולטור עם Google Play.

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

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

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

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

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

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

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

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

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

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

    • עבור iOS - הזן את מזהה iOS של פרוייקט Unity שלך בשדה מזהה החבילה של iOS.

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

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

  6. לחץ על הרשמה אפליקציה .

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

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

    • עבור iOS - לחץ על הורד GoogleService-Info.plist .

    • עבור אנדרואיד - לחץ על הורד google-services.json .

  2. פתח את חלון הפרויקט של פרויקט Unity שלך, ולאחר מכן העבר את קבצי התצורה שלך לתיקיית Assets .

  3. בחזרה במסוף Firebase, בזרימת העבודה של ההגדרה, לחץ על הבא .

שלב 4: הוסף ערכות SDK של Firebase Unity

  1. במסוף Firebase, לחץ על הורד Firebase Unity SDK ולאחר מכן פתח את ה-SDK במקום נוח.

    • אתה יכול להוריד שוב את Firebase Unity SDK בכל עת.

    • ה-SDK של Firebase Unity אינו ספציפי לפלטפורמה.

  2. בפרויקט Unity הפתוח שלך, נווט אל נכסים > ייבוא ​​חבילה > חבילה מותאמת אישית .

  3. מה-SDK הפתוח, בחר את מוצרי Firebase הנתמכים שבהם ברצונך להשתמש באפליקציה שלך.

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

    אנליטיקס מופעל

    • הוסף את חבילת Firebase עבור Google Analytics: FirebaseAnalytics.unitypackage
    • הוסף את החבילה עבור Firebase Cloud Messaging: FirebaseMessaging.unitypackage

    Analytics לא מופעל

    הוסף את החבילה עבור Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. בחלון ייבוא ​​חבילת אחדות , לחץ על ייבוא ​​.

  5. בחזרה במסוף Firebase, בזרימת העבודה של ההגדרה, לחץ על הבא .

שלב 5: אשר את דרישות גרסת שירותי Google Play

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

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

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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.

שלב 7: הוסף מסגרת להודעות משתמש

  1. לחץ על הפרויקט ב-Xcode, ולאחר מכן בחר בכרטיסייה כללי מאזור העורך .

  2. גלול מטה אל מסגרות וספריות מקושרות ולאחר מכן לחץ על הלחצן + כדי להוסיף מסגרת.

  3. בחלון שמופיע, גלול אל UserNotifications.framework , לחץ על הערך הזה ולאחר מכן לחץ על הוסף .

שלב 8: הפעל התראות דחיפה

  1. לחץ על הפרויקט ב-Xcode, ולאחר מכן בחר בכרטיסייה יכולות מאזור העורך .

  2. העבר את הודעות הדחיפה למצב מופעל .

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

  4. בחר בתיבת הסימון הודעות מרחוק תחת מצבי רקע .

אתחול 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);
}

הגדרת פעילות נקודת כניסה אנדרואיד

באנדרואיד, 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>

הערה לגבי מסירת הודעות באנדרואיד

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

דְמוּי אָדָם

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

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

זכור שתזדקק למימוש שרת כדי לעשות שימוש בתכונות אלה.