דלג לתוכן הראשי

קבלת אישורי Firebase (FCM) (Android)

Joryio שולחת התראות פוש למכשירי Android דרך Firebase Cloud Messaging (FCM), באמצעות FCM HTTP v1 API. לשם כך היא צריכה מפתח של חשבון שירות (service account) מפרויקט ה-Firebase שבו משתמשת אפליקציית ה-Android שלכם. עמוד זה מסביר שלב אחר שלב איך מגדירים את Firebase, איך יוצרים את המפתח ואיך מזינים אותו ב-Joryio.

לכל אפליקציה ב-Joryio יש אישורי פוש משלה, ולכן התהליך נעשה פעם אחת לכל אפליקציית Android. לפרויקט React Native או Unity יש אפליקציית Android נפרדת ב-Joryio - אישורי ה-FCM שלו מוזנים בה. ראו מעקב רב-פלטפורמי.

מה Joryio מבקשת​

שדה ב-Joryioמה זהחובה
Firebase service account (JSON)קובץ המפתח הפרטי של חשבון שירות בפרויקט ה-Firebase שלכם. Joryio שולחת איתו כל פוש ל-Android.כן
Sender IDמזהה מספרי של פרויקט ה-Firebase. Joryio שומרת אותו אבל לא משתמשת בו לשליחה.לא - אפשר להשאיר ריק

Joryio תומכת רק בקובץ ה-JSON של חשבון השירות (FCM HTTP v1). "מפתח השרת" (server key) הישן של FCM אינו נתמך - Google הוציאה משימוש את ממשקי ה-FCM הישנים, ושליחה מאפליקציית Android שיש לה רק מפתח שרת נכשלת.

מכשירי iOS לא מקבלים פוש דרך Firebase: Joryio שולחת ל-iOS ישירות דרך APNs. ראו קבלת אישורי APNs.

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

  • פרויקט Firebase. צרו פרויקט ב-Firebase console אם אין לכם.
  • הרשאה ליצור מפתחות לחשבונות שירות בפרויקט. ב-Google Cloud ההרשאה ניתנת דרך התפקיד Service Account Key Admin‏ (roles/iam.serviceAccountKeyAdmin); לבעלי פרויקט (Owner) היא בדרך כלל קיימת. אם הארגון שלכם ב-Google Cloud אוכף את המדיניות iam.disableServiceAccountKeyCreation, יצירת מפתחות חסומה - היא נאכפת כברירת מחדל בארגונים שנוצרו ב-3 במאי 2024 ואילך. בקשו ממנהל ה-Google Cloud שלכם להחריג את הפרויקט.
  • אפליקציית Android ב-Joryio עם Android SDK משולב. ליצירת אפליקציה, ראו יצירת אפליקציות.

שלב 1: הוספת אפליקציית ה-Android ל-Firebase​

האפליקציה צריכה את Firebase כדי שמכשירים יוכלו לקבל טוקן הרשמה של FCM. דלגו על השלב הזה אם האפליקציה שלכם כבר משתמשת ב-Firebase.

  1. ב-Firebase console, פתחו את הפרויקט.
  2. בעמוד סקירת הפרויקט, לחצו על סמל ה-Android או על Add app.
  3. הזינו את Android package name של האפליקציה (ה-applicationId בקובץ ה-Gradle ברמת המודול). הוא תלוי רישיות ואי אפשר לשנות אותו אחרי הרישום.
  4. לחצו על Register app.
  5. לחצו על Download google-services.json והעבירו את הקובץ לתיקיית השורש של מודול האפליקציה (בדרך כלל app/).
  6. הוסיפו את תוסף ה-Gradle של Google services, כפי ש-Firebase console מציגה:
    • בקובץ ה-Gradle ברמת השורש: id("com.google.gms.google-services") version "<version>" apply false
    • בקובץ ה-Gradle ברמת המודול (app): id("com.google.gms.google-services")
  7. השלימו את הגדרת הפוש באפליקציה כמתואר בחלק הפוש של Android SDK.

google-services.json מכיל מזהים של האפליקציה, לא סודות, והוא נארז בתוך האפליקציה. זה לא הקובץ ש-Joryio צריכה - הקובץ הנדרש הוא מפתח חשבון השירות שבשלב הבא.

שלב 2: יצירת מפתח חשבון השירות​

  1. ב-Firebase console, לחצו על סמל גלגל השיניים (Settings), פתחו את Project settings, ואז את הלשונית Service accounts.
  2. לחצו על Generate New Private Key, ואשרו עם Generate Key.
  3. קובץ JSON יורד. שמרו אותו במקום מאובטח - אי אפשר להוריד שוב את אותו קובץ מפתח. אם הוא אבד, צרו מפתח חדש.

הקובץ מכיל, בין השאר, את השדות "type": "service_account",‏ project_id,‏ private_key ו-client_email.

שלב 3: הזנת האישורים ב-Joryio​

  1. בלוח הבקרה של Joryio, עברו אל הגדרות → אפליקציות.
  2. מצאו את אפליקציית ה-Android ברשימה ולחצו על סמל התראות Push (הפעמון) בשורה שלה. העמוד התראות Push - [שם האפליקציה] נפתח.
  3. בכרטיס Firebase Cloud Messaging, לחצו על Upload service account JSON ובחרו את הקובץ משלב 2. Joryio מציגה מתחת לכפתור את מזהה הפרויקט שקראה מהקובץ. ודאו שזה אותו פרויקט כמו ה-project_id שב-google-services.json של האפליקציה.
  4. אופציונלי: הזינו את ה-Sender ID. Joryio לא משתמשת בו לשליחה, כך שאפשר להשאיר אותו ריק.
  5. לחצו על שמור הגדרות.

ברשימת האפליקציות מופיע עכשיו FCM מוגדר מתחת לשם האפליקציה. חשבון השירות מוצפן במנוחה ואינו מוצג שוב: כשפותחים את העמוד מחדש, מוצגת ההערה "מוגדר - השאירו ריק כדי לשמור את הערך הנוכחי, או הזינו ערך חדש כדי להחליפו." העלו קובץ רק כשאתם רוצים להחליף את הקובץ השמור.

שלב 4: שליחת פוש לבדיקה​

  1. התקינו את האפליקציה במכשיר או באמולטור עם Google Play services, פתחו אותה ואשרו התראות (Android 13 ואילך מבקש הרשאת התראות). ה-SDK רושם את טוקן ה-FCM של המכשיר ב-Joryio.
  2. צרו קמפיין פוש (או פתחו טיוטה) שנשלח מהאפליקציה הזו.
  3. לחצו על שלח push לבדיקה בווריאנט, בחרו את המשתמש שמחובר במכשיר שלכם ושלחו.

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

שגיאות נפוצות ופתרונות​

מה רואיםסיבה סבירהפתרון
"That does not look like a Firebase service account JSON (missing project_id / private_key / client_email)."הקובץ שהועלה אינו מפתח של חשבון שירות - לרוב זה google-services.json.העלו את הקובץ מ-Project settings → Service accounts → Generate New Private Key (שלב 2).
"Could not parse that file as JSON."הקובץ פגום או שאינו JSON.צרו מפתח חדש והעלו את הקובץ החדש בלי לשנות אותו.
"FCM not configured: this app needs a Firebase service account (the legacy server key is no longer supported)"לאפליקציה לא שמור חשבון שירות - למשל יש לה רק מפתח שרת ישן.העלו קובץ JSON של חשבון שירות ושמרו.
"Device token sender mismatch" (messaging/mismatched-credential או messaging/sender-id-mismatch)טוקן המכשיר הונפק לפרויקט Firebase אחר מזה של חשבון השירות.השתמשו בחשבון שירות מאותו פרויקט כמו ה-google-services.json שבגרסת האפליקציה, ואז פתחו שוב את האפליקציה במכשיר כדי שתרשום את הטוקן שלה מחדש.
"Device token unregistered" (messaging/registration-token-not-registered)האפליקציה הוסרה או שהטוקן כבר לא תקף.אין מה לתקן באישורים. Joryio מפסיקה לשלוח לטוקן הזה.
שגיאות אימות או הרשאההמפתח נמחק או הושבת ב-Google Cloud, או שחשבון השירות איבד את ההרשאות שלו.צרו מפתח חדש ב-Firebase והעלו אותו.
"no device accepted the notification"למשתמש אין מכשיר Android רשום לאפליקציה הזו.פתחו את האפליקציה עם ה-SDK המשולב במכשיר, אשרו התראות, וודאו שאתם בודקים עם אותו משתמש.

אבטחה והחלפת מפתחות​

  • התייחסו לקובץ ה-JSON של חשבון השירות כסוד: הוא מכיל מפתח פרטי שיכול לשלוח הודעות למשתמשי האפליקציה ולקרוא לממשקי Google אחרים שחשבון השירות מורשה להשתמש בהם. אל תכניסו אותו לבקרת גרסאות, אל תשלחו אותו במייל או בצ'אט, ואל תארזו אותו בתוך האפליקציה.
  • אם אתם חושדים שהמפתח דלף, צרו מפתח חדש, העלו אותו ב-Joryio, ואז מחקו את המפתח הישן ב-Google Cloud console: IAM & Admin → Service accounts, לחצו על חשבון השירות, פתחו את הלשונית Keys ומחקו את המפתח הישן. אי אפשר לשחזר מפתח שנמחק.
  • כדי להחליף מפתח בלי השבתה, עבדו באותו סדר: קודם המפתח החדש ב-Joryio, ורק אחר כך מחיקת הישן.