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

Λήψη διαπιστευτηρίων APNs (iOS)

Το Joryio στέλνει push notifications σε συσκευές iOS μέσω του Apple Push Notification service (APNs). Για να το κάνει, χρειάζεται διαπιστευτήρια από τον λογαριασμό σας Apple Developer. Αυτή η σελίδα εξηγεί βήμα προς βήμα πώς τα δημιουργείτε στην πύλη της Apple και πώς τα εισαγάγετε στο Joryio.

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

Τι ζητά το Joryio​

Το Joryio χρησιμοποιεί έλεγχο ταυτότητας με token με ένα κλειδί ελέγχου ταυτότητας APNs (αρχείο .p8). Χρειάζεστε τέσσερα πράγματα:

Πεδίο στο JoryioΤι είναιΑπό πού προέρχεται
EnvironmentΑνάπτυξη (Sandbox) ή Παραγωγή - το περιβάλλον APNs στο οποίο εγγράφονται τα builds της εφαρμογής σαςΟ τύπος του build - δείτε Επιλογή περιβάλλοντος
Key IDΑναγνωριστικό 10 χαρακτήρων του κλειδιού ελέγχου ταυτότηταςΛογαριασμός Apple Developer, Keys
Team IDΑναγνωριστικό 10 χαρακτήρων της ομάδας προγραμματιστών σας στην AppleΛογαριασμός Apple Developer, Membership details
Auth Key (.p8 Content)Ολόκληρο το κείμενο του αρχείου .p8Το αρχείο που κατεβάζετε μία φορά όταν δημιουργείτε το κλειδί

Οι ρυθμίσεις push προσφέρουν επίσης τη μέθοδο Με πιστοποιητικό (.p12). Αυτός ο οδηγός καλύπτει μόνο το κλειδί .p8 με token, που είναι η συνιστώμενη μέθοδος: ένα κλειδί ελέγχου ταυτότητας δεν λήγει, και ένα κλειδί μπορεί να στέλνει για όλες τις εφαρμογές της ομάδας προγραμματιστών σας στην Apple.

Πριν ξεκινήσετε​

  • Συνδρομή στο Apple Developer Program. Τα κλειδιά APNs δημιουργούνται σε επί πληρωμή λογαριασμό προγραμματιστή.
  • Ρόλος Account Holder ή Admin στην ομάδα προγραμματιστών. Η Apple επιτρέπει μόνο σε αυτούς τους ρόλους να δημιουργούν κλειδιά. Αν έχετε άλλον ρόλο, ζητήστε από τον Account Holder ή από έναν Admin να δημιουργήσει το κλειδί και να σας στείλει το Key ID, το Team ID και το αρχείο .p8 μέσω ασφαλούς καναλιού.
  • Ενεργοποιημένα push notifications για την εφαρμογή. Στο Xcode, προσθέστε τη δυνατότητα Push Notifications στο target της εφαρμογής και βεβαιωθείτε ότι τα push notifications είναι ενεργά για το App ID (το bundle ID) στον λογαριασμό προγραμματιστή. Το κλειδί πρέπει να ανήκει στην ίδια ομάδα προγραμματιστών με την εφαρμογή.
  • Μια iOS εφαρμογή στο Joryio με ενσωματωμένο το iOS SDK. Για να δημιουργήσετε μία, δείτε Δημιουργία εφαρμογών.

Βήμα 1: Δημιουργήστε το κλειδί ελέγχου ταυτότητας APNs​

  1. Συνδεθείτε στον λογαριασμό σας Apple Developer και ανοίξτε το Certificates, Identifiers & Profiles.
  2. Επιλέξτε Keys στην πλαϊνή στήλη και μετά το κουμπί προσθήκης (+).
  3. Στο Key Name, εισαγάγετε ένα όνομα που θα αναγνωρίζετε αργότερα, π.χ. «Joryio push».
  4. Επιλέξτε το πλαίσιο ελέγχου δίπλα στο Apple Push Notification service (APNs) και μετά το Configure δίπλα του.
  5. Επιλέξτε το περιβάλλον του κλειδιού και τον τύπο κλειδιού:
    • Περιβάλλον - επιλέξτε το περιβάλλον που ταιριάζει με αυτό που θα επιλέξετε στο Joryio (δείτε Επιλογή περιβάλλοντος). Ένα κλειδί περιορισμένο στο Sandbox δεν λειτουργεί για αποστολές παραγωγής, και αντίστροφα.
    • Τύπος κλειδιού - το Team Scoped λειτουργεί για κάθε εφαρμογή (bundle ID) της ομάδας. Το Topic Specific περιορίζεται στα bundle IDs που επιλέγετε - αν το επιλέξετε, συμπεριλάβετε το bundle ID της εφαρμογής σας.
  6. Επιλέξτε Continue, ελέγξτε τη διαμόρφωση του κλειδιού και επιλέξτε Confirm.
  7. Επιλέξτε Download. Το κλειδί αποθηκεύεται ως αρχείο κειμένου με κατάληξη .p8.
  8. Επιλέξτε Done.
Μπορείτε να κατεβάσετε το κλειδί μόνο μία φορά

Η Apple δεν κρατά αντίγραφο του ιδιωτικού κλειδιού. Φυλάξτε το αρχείο .p8 σε ασφαλές σημείο, για παράδειγμα στον διαχειριστή κωδικών της ομάδας σας. Αν αργότερα το κουμπί Download είναι απενεργοποιημένο, το κλειδί έχει ήδη ληφθεί. Αν χάσετε το αρχείο, δημιουργήστε νέο κλειδί και ανακαλέστε το παλιό.

Βήμα 2: Σημειώστε το Key ID και το Team ID​

  • Key ID - Στο Certificates, Identifiers & Profiles → Keys, επιλέξτε το κλειδί που δημιουργήσατε. Το Key ID εμφανίζεται στα στοιχεία του κλειδιού, κάτω από το όνομά του.
  • Team ID - Στον λογαριασμό σας Apple Developer, ανοίξτε το Membership details. Το Team ID είναι μια συμβολοσειρά 10 χαρακτήρων.

Βήμα 3: Επιλογή περιβάλλοντος​

Το APNs έχει δύο περιβάλλοντα, και ένα token συσκευής λειτουργεί μόνο στο περιβάλλον για το οποίο εκδόθηκε:

  • Ανάπτυξη (Sandbox) - για builds υπογεγραμμένα με development provisioning profile, για παράδειγμα όταν τρέχετε την εφαρμογή από το Xcode στη συσκευή σας.
  • Παραγωγή - για builds υπογεγραμμένα με distribution provisioning profile: App Store και TestFlight.

Το Xcode ορίζει το περιβάλλον push της εφαρμογής από το provisioning profile, οπότε το build καθορίζει σε ποιο περιβάλλον εγγράφονται οι συσκευές του. Κάθε εφαρμογή του Joryio έχει μία ρύθμιση περιβάλλοντος. Αν δοκιμάζετε με development builds και παράλληλα κυκλοφορείτε στο App Store, δημιουργήστε ξεχωριστή iOS εφαρμογή στο Joryio για τα development builds (με δικό της κλειδί SDK), αντί να αλλάζετε τη ρύθμιση πέρα δώθε.

Βήμα 4: Εισαγάγετε τα διαπιστευτήρια στο Joryio​

  1. Στο dashboard του Joryio, μεταβείτε στις Ρυθμίσεις → Εφαρμογές.
  2. Βρείτε την iOS εφαρμογή σας στη λίστα και επιλέξτε το εικονίδιο Ειδοποιήσεις push (καμπανάκι) στη γραμμή της. Ανοίγει η σελίδα Ειδοποιήσεις push - [όνομα εφαρμογής].
  3. Στην κάρτα Διαπιστευτήρια APNS:
    • Environment - επιλέξτε Ανάπτυξη (Sandbox) ή Παραγωγή.
    • Authentication Method - επιλέξτε Με token (κλειδί .p8).
    • Key ID - επικολλήστε το Key ID από το βήμα 2.
    • Team ID - επικολλήστε το Team ID από το βήμα 2.
    • Auth Key (.p8 Content) - ανοίξτε το αρχείο .p8 σε επεξεργαστή κειμένου και επικολλήστε ολόκληρο το περιεχόμενό του, μαζί με τις γραμμές -----BEGIN PRIVATE KEY----- και -----END PRIVATE KEY-----.
  4. Επιλέξτε Αποθήκευση διαμόρφωσης.

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

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

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

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

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

Τι βλέπετεΠιθανή αιτίαΛύση
BadDeviceTokenΤο token της συσκευής εκδόθηκε για το άλλο περιβάλλον - για παράδειγμα ένα build TestFlight ενώ το Joryio είναι ρυθμισμένο σε Ανάπτυξη (Sandbox).Ορίστε το Environment ώστε να ταιριάζει με το build (δείτε βήμα 3) και ανοίξτε ξανά την εφαρμογή στη συσκευή ώστε να καταχωρήσει ξανά το token της.
DeviceTokenNotForTopicΤο token ανήκει σε διαφορετική εφαρμογή (bundle ID) από αυτή για την οποία στέλνουν τα διαπιστευτήρια.Ελέγξτε ότι η συσκευή τρέχει την εφαρμογή που είναι συνδεδεμένη με το κλειδί SDK αυτής της εφαρμογής Joryio, και ότι το κλειδί ανήκει στην ομάδα προγραμματιστών στην οποία ανήκει η εφαρμογή.
InvalidProviderTokenΤο Key ID, το Team ID ή το περιεχόμενο του .p8 δεν ταιριάζουν - για παράδειγμα το Key ID ενός κλειδιού με το περιεχόμενο άλλου, ή κλειδί άλλης ομάδας.Εισαγάγετε ξανά και τις τρεις τιμές από το ίδιο κλειδί και την ίδια ομάδα. Επικολλήστε ολόκληρο το αρχείο .p8, μαζί με τις γραμμές BEGIN και END.
TopicDisallowedΤο κλειδί δεν επιτρέπεται να στέλνει σε αυτή την εφαρμογή - για παράδειγμα κλειδί Topic Specific που δεν περιλαμβάνει το bundle ID σας, ή κλειδί περιορισμένο στο άλλο περιβάλλον.Δημιουργήστε κλειδί που καλύπτει το bundle ID και το περιβάλλον σας, ή χρησιμοποιήστε κλειδί Team Scoped.
UnregisteredΗ εφαρμογή απεγκαταστάθηκε ή το token δεν είναι πλέον ενεργό.Δεν χρειάζεται διόρθωση στα διαπιστευτήρια. Το Joryio σταματά να στέλνει σε αυτό το token.
«no device accepted the notification»Ο χρήστης δεν έχει καταχωρημένη iOS συσκευή για αυτή την εφαρμογή.Ανοίξτε στη συσκευή την εφαρμογή με το ενσωματωμένο SDK, επιτρέψτε τις ειδοποιήσεις και βεβαιωθείτε ότι δοκιμάζετε με τον ίδιο χρήστη.
Το αρχείο του κλειδιού χάθηκεΗ Apple επιτρέπει μόνο μία λήψη.Δημιουργήστε νέο κλειδί (βήμα 1), εισαγάγετέ το στο Joryio και μετά ανακαλέστε το παλιό.
Ένα κλειδί ανακλήθηκεΚάθε αποστολή με αυτό το κλειδί αποτυγχάνει.Δημιουργήστε νέο κλειδί και εισαγάγετέ το στο Joryio.

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

  • Χειριστείτε το αρχείο .p8 ως μυστικό: όποιος το έχει, μαζί με το Key ID και το Team ID σας, μπορεί να στείλει ειδοποιήσεις στους χρήστες σας. Μην το προσθέτετε σε source control και μην το στέλνετε με email ή chat.
  • Αν πιστεύετε ότι το κλειδί διέρρευσε, δημιουργήστε νέο κλειδί, εισαγάγετέ το στο Joryio και μετά ανακαλέστε το παλιό: στο Certificates, Identifiers & Profiles → Keys, επιλέξτε το κλειδί, επιλέξτε Revoke και επιβεβαιώστε. Η ανάκληση ισχύει αμέσως για κάθε υπηρεσία που χρησιμοποιεί το κλειδί.
  • Για να αλλάξετε κλειδί χωρίς διακοπή, ακολουθήστε την ίδια σειρά: πρώτα το νέο κλειδί στο Joryio, μετά η ανάκληση του παλιού. Η Apple περιορίζει πόσα κλειδιά μπορεί να έχει μια ομάδα ανά περιβάλλον, οπότε ίσως χρειαστεί να ανακαλέσετε ένα αχρησιμοποίητο κλειδί πριν δημιουργήσετε νέο.