Μετάβαση στο κύριο περιεχόμενο

Λήψη διαπιστευτηρίων Firebase (FCM) (Android)

Το Joryio στέλνει push notifications σε συσκευές Android μέσω του Firebase Cloud Messaging (FCM), χρησιμοποιώντας το FCM HTTP v1 API. Για να το κάνει, χρειάζεται ένα κλειδί λογαριασμού υπηρεσίας (service account) από το έργο Firebase που χρησιμοποιεί η Android εφαρμογή σας. Αυτή η σελίδα εξηγεί βήμα προς βήμα πώς ρυθμίζετε το Firebase, πώς δημιουργείτε το κλειδί και πώς το εισαγάγετε στο Joryio.

Κάθε εφαρμογή του Joryio έχει τα δικά της διαπιστευτήρια push, οπότε η διαδικασία γίνεται μία φορά για κάθε Android εφαρμογή. Ένα έργο React Native ή Unity έχει ξεχωριστή Android εφαρμογή στο Joryio - εκεί μπαίνουν τα διαπιστευτήρια FCM του. Δείτε το Multi-Platform Tracking.

Τι ζητά το Joryio​

Πεδίο στο JoryioΤι είναιΥποχρεωτικό
Firebase service account (JSON)Το αρχείο ιδιωτικού κλειδιού ενός λογαριασμού υπηρεσίας στο έργο Firebase σας. Το Joryio στέλνει κάθε Android push με αυτό.Ναι
Sender IDΑριθμητικό αναγνωριστικό του έργου Firebase. Το Joryio το αποθηκεύει αλλά δεν το χρησιμοποιεί για αποστολή.Όχι - μπορεί να μείνει κενό

Το Joryio υποστηρίζει μόνο το JSON λογαριασμού υπηρεσίας (FCM HTTP v1). Το παλιό «server key» του FCM δεν υποστηρίζεται - η Google έχει καταργήσει τα παλιά FCM APIs, και μια αποστολή από Android εφαρμογή που έχει μόνο server key αποτυγχάνει.

Οι συσκευές 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 ώστε οι συσκευές να μπορούν να λάβουν registration token του FCM. Παραλείψτε αυτό το βήμα αν η εφαρμογή σας χρησιμοποιεί ήδη Firebase.

  1. Στο Firebase console, ανοίξτε το έργο σας.
  2. Στη σελίδα επισκόπησης του έργου, επιλέξτε το εικονίδιο Android ή Add app.
  3. Εισαγάγετε το Android package name της εφαρμογής (το applicationId στο αρχείο Gradle επιπέδου module). Κάνει διάκριση πεζών-κεφαλαίων και δεν αλλάζει μετά την καταχώρηση.
  4. Επιλέξτε Register app.
  5. Επιλέξτε Download google-services.json και μετακινήστε το αρχείο στον ριζικό φάκελο του module της εφαρμογής (συνήθως app/).
  6. Προσθέστε το Gradle plugin των Google services, όπως δείχνει το Firebase console:
    • Στο αρχείο Gradle ριζικού επιπέδου: id("com.google.gms.google-services") version "<version>" apply false
    • Στο αρχείο Gradle επιπέδου module (app): id("com.google.gms.google-services")
  7. Ολοκληρώστε τη ρύθμιση push στην εφαρμογή όπως περιγράφεται στην ενότητα push του 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. Στο dashboard του Joryio, μεταβείτε στις Ρυθμίσεις → Εφαρμογές.
  2. Βρείτε την Android εφαρμογή σας στη λίστα και επιλέξτε το εικονίδιο Ειδοποιήσεις push (καμπανάκι) στη γραμμή της. Ανοίγει η σελίδα Ειδοποιήσεις push - [όνομα εφαρμογής].
  3. Στην κάρτα Firebase Cloud Messaging, επιλέξτε Upload service account JSON και διαλέξτε το αρχείο από το βήμα 2. Το Joryio εμφανίζει κάτω από το κουμπί το project ID που διάβασε από το αρχείο. Ελέγξτε ότι είναι το ίδιο έργο με το project_id στο google-services.json της εφαρμογής σας.
  4. Προαιρετικά: εισαγάγετε το Sender ID. Το Joryio δεν το χρησιμοποιεί για αποστολή, οπότε μπορεί να μείνει κενό.
  5. Επιλέξτε Αποθήκευση διαμόρφωσης.

Η λίστα εφαρμογών δείχνει τώρα Το FCM έχει ρυθμιστεί κάτω από το όνομα της εφαρμογής. Ο λογαριασμός υπηρεσίας κρυπτογραφείται κατά την αποθήκευση και δεν εμφανίζεται ξανά: όταν ανοίγετε ξανά τη σελίδα, εμφανίζεται η σημείωση «Διαμορφωμένο - αφήστε το κενό για να διατηρήσετε την τρέχουσα τιμή, ή εισαγάγετε νέα για αντικατάσταση.» Ανεβάστε αρχείο μόνο όταν θέλετε να αντικαταστήσετε το αποθηκευμένο.

Βήμα 4: Στείλτε μια δοκιμαστική push​

  1. Εγκαταστήστε την εφαρμογή σε συσκευή ή emulator με Google Play services, ανοίξτε την και επιτρέψτε τις ειδοποιήσεις (το Android 13 και νεότερα ζητούν άδεια ειδοποιήσεων). Το SDK καταχωρεί το FCM token της συσκευής στο Joryio.
  2. Δημιουργήστε μια καμπάνια push (ή ανοίξτε ένα πρόχειρο) που στέλνει από αυτή την εφαρμογή.
  3. Επιλέξτε Αποστολή δοκιμαστικής push στην παραλλαγή, διαλέξτε τον χρήστη που είναι συνδεδεμένος στη συσκευή σας και στείλτε.

Αν η δοκιμή αποτύχει, το μήνυμα σφάλματος περιλαμβάνει τον λόγο που επέστρεψε το FCM - αναζητήστε τον στον παρακάτω πίνακα. Για ολόκληρη τη ροή της καμπάνιας, δείτε Push Notifications.

Συνηθισμένα σφάλματα και λύσεις​

Τι βλέπετεΠιθανή αιτίαΛύση
«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)»Η εφαρμογή δεν έχει αποθηκευμένο λογαριασμό υπηρεσίας - για παράδειγμα έχει μόνο παλιό server key.Ανεβάστε ένα JSON λογαριασμού υπηρεσίας και αποθηκεύστε.
«Device token sender mismatch» (messaging/mismatched-credential ή messaging/sender-id-mismatch)Το token της συσκευής εκδόθηκε για διαφορετικό έργο Firebase από αυτό του λογαριασμού υπηρεσίας.Χρησιμοποιήστε λογαριασμό υπηρεσίας από το ίδιο έργο με το google-services.json του build σας και ανοίξτε ξανά την εφαρμογή στη συσκευή ώστε να καταχωρήσει ξανά το token της.
«Device token unregistered» (messaging/registration-token-not-registered)Η εφαρμογή απεγκαταστάθηκε ή το token δεν είναι πλέον έγκυρο.Δεν χρειάζεται διόρθωση στα διαπιστευτήρια. Το Joryio σταματά να στέλνει σε αυτό το token.
Σφάλματα ελέγχου ταυτότητας ή δικαιωμάτωνΤο κλειδί διαγράφηκε ή απενεργοποιήθηκε στο Google Cloud, ή ο λογαριασμός υπηρεσίας έχασε τα δικαιώματά του.Δημιουργήστε νέο κλειδί στο Firebase και ανεβάστε το.
«no device accepted the notification»Ο χρήστης δεν έχει καταχωρημένη Android συσκευή για αυτή την εφαρμογή.Ανοίξτε στη συσκευή την εφαρμογή με το ενσωματωμένο SDK, επιτρέψτε τις ειδοποιήσεις και βεβαιωθείτε ότι δοκιμάζετε με τον ίδιο χρήστη.

Ασφάλεια και εναλλαγή κλειδιών​

  • Χειριστείτε το JSON του λογαριασμού υπηρεσίας ως μυστικό: περιέχει ιδιωτικό κλειδί που μπορεί να στείλει μηνύματα στους χρήστες της εφαρμογής σας και να καλέσει άλλα Google APIs που επιτρέπονται στον λογαριασμό υπηρεσίας. Μην το προσθέτετε σε source control, μην το στέλνετε με email ή chat και μην το συμπεριλαμβάνετε μέσα στην εφαρμογή.
  • Αν πιστεύετε ότι το κλειδί διέρρευσε, δημιουργήστε νέο κλειδί, ανεβάστε το στο Joryio και μετά διαγράψτε το παλιό στο Google Cloud console: IAM & Admin → Service accounts, επιλέξτε τον λογαριασμό υπηρεσίας, ανοίξτε την καρτέλα Keys και διαγράψτε το παλιό κλειδί. Ένα διαγραμμένο κλειδί δεν μπορεί να επανέλθει.
  • Για να αλλάξετε κλειδί χωρίς διακοπή, ακολουθήστε την ίδια σειρά: πρώτα το νέο κλειδί στο Joryio, μετά η διαγραφή του παλιού.