קבלת אישורי APNs (iOS)
Joryio שולחת התראות פוש למכשירי iOS דרך Apple Push Notification service (APNs). לשם כך היא צריכה אישורים מחשבון Apple Developer שלכם. עמוד זה מסביר שלב אחר שלב איך יוצרים אותם בפורטל של Apple ואיך מזינים אותם ב-Joryio.
לכל אפליקציה ב-Joryio יש אישורי פוש משלה, ולכן התהליך נעשה פעם אחת לכל אפליקציית iOS. לפרויקט React Native או Unity יש אפליקציית iOS נפרדת ב-Joryio - אישורי ה-APNs שלו מוזנים בה. ראו מעקב רב-פלטפורמי.
מה Joryio מבקשת
Joryio משתמשת באימות מבוסס טוקן עם מפתח אימות של APNs (קובץ .p8). צריך ארבעה דברים:
| שדה ב-Joryio | מה זה | מאיפה זה מגיע |
|---|---|---|
| Environment | פיתוח (Sandbox) או סביבת ייצור - סביבת ה-APNs שאיתה נרשמות גרסאות האפליקציה שלכם | סוג הגרסה (build) - ראו בחירת הסביבה |
| Key ID | מזהה בן 10 תווים של מפתח האימות | חשבון Apple Developer, Keys |
| Team ID | מזהה בן 10 תווים של צוות המפתחים שלכם ב-Apple | חשבון Apple Developer, Membership details |
| Auth Key (.p8 Content) | כל הטקסט של קובץ ה-.p8 | הקובץ שמורידים פעם אחת בעת יצירת המפתח |
בהגדרות הפוש מוצעת גם שיטת האימות מבוסס תעודה (.p12). מדריך זה מכסה רק את מפתח ה-.p8 מבוסס הטוקן, שהוא השיטה המומלצת: למפתח אימות אין תאריך תפוגה, ומפתח אחד יכול לשלוח לכל האפליקציות בצוות המפתחים שלכם ב-Apple.
לפני שמתחילים
- חברות ב-Apple Developer Program. מפתחות APNs נוצרים בחשבון מפתחים בתשלום.
- תפקיד Account Holder או Admin בצוות המפתחים. Apple מאפשרת רק לתפקידים האלה ליצור מפתחות. אם יש לכם תפקיד אחר, בקשו מה-Account Holder או מ-Admin ליצור את המפתח ולשלוח לכם את ה-Key ID, ה-Team ID וקובץ ה-
.p8בערוץ מאובטח. - התראות פוש מופעלות באפליקציה. ב-Xcode, הוסיפו את היכולת Push Notifications ל-target של האפליקציה, וודאו שהתראות פוש מופעלות עבור ה-App ID (מזהה ה-bundle) בחשבון המפתחים. המפתח חייב להשתייך לאותו צוות מפתחים שאליו שייכת האפליקציה.
- אפליקציית iOS ב-Joryio עם iOS SDK משולב. ליצירת אפליקציה, ראו יצירת אפליקציות.
שלב 1: יצירת מפתח האימות של APNs
- התחברו לחשבון Apple Developer ופתחו את Certificates, Identifiers & Profiles.
- לחצו על Keys בסרגל הצד, ואז על כפתור ההוספה (+).
- תחת Key Name, הזינו שם שתזהו בהמשך, למשל "Joryio push".
- סמנו את תיבת הסימון ליד Apple Push Notification service (APNs), ואז לחצו על Configure לידה.
- בחרו את הסביבה של המפתח ואת סוג המפתח:
- סביבה - בחרו את הסביבה שתואמת לזו שתבחרו ב-Joryio (ראו בחירת הסביבה). מפתח שמוגבל ל-Sandbox לא עובד לשליחות בסביבת ייצור, וגם להפך.
- סוג מפתח - Team Scoped עובד לכל האפליקציות (מזהי ה-bundle) בצוות. Topic Specific מוגבל למזהי ה-bundle שתבחרו - אם בחרתם בו, כללו את מזהה ה-bundle של האפליקציה שלכם.
- לחצו על Continue, בדקו את הגדרות המפתח ולחצו על Confirm.
- לחצו על Download. המפתח נשמר כקובץ טקסט עם הסיומת
.p8. - לחצו על 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 יש שתי סביבות, וטוקן של מכשיר עובד רק בסביבה שעבורה הונפק:
- פיתוח (Sandbox) - לגרסאות שנחתמו עם provisioning profile של פיתוח, למשל כשמריצים את האפליקציה מ-Xcode על המכשיר שלכם.
- סביבת ייצור - לגרסאות שנחתמו עם provisioning profile של הפצה: App Store ו-TestFlight.
Xcode קובעת את סביבת הפוש של האפליקציה לפי ה-provisioning profile, כך שהגרסה היא שקובעת באיזו סביבה המכשירים שלה נרשמים. לכל אפליקציה ב-Joryio יש הגדרת סביבה אחת. אם אתם בודקים עם גרסאות פיתוח וגם משיקים ל-App Store, צרו אפליקציית iOS נפרדת ב-Joryio עבור גרסאות הפיתוח (עם מפתח SDK משלה), במקום להחליף את ההגדרה הלוך ושוב.
שלב 4: הזנת האישורים ב-Joryio
- בלוח הבקרה של Joryio, עברו אל הגדרות → אפליקציות.
- מצאו את אפליקציית ה-iOS ברשימה ולחצו על סמל התראות Push (הפעמון) בשורה שלה. העמוד התראות Push - [שם האפליקציה] נפתח.
- בכרטיס פרטי APNS:
- Environment - בחרו פיתוח (Sandbox) או סביבת ייצור.
- Authentication Method - בחרו מבוסס טוקן (מפתח .p8).
- Key ID - הדביקו את ה-Key ID משלב 2.
- Team ID - הדביקו את ה-Team ID משלב 2.
- Auth Key (.p8 Content) - פתחו את קובץ ה-
.p8בעורך טקסט והדביקו את כל התוכן שלו, כולל השורות-----BEGIN PRIVATE KEY-----ו------END PRIVATE KEY-----.
- לחצו על שמור הגדרות.
ברשימת האפליקציות מופיע עכשיו APNS מוגדר מתחת לשם האפליקציה. מפתח האימות מוצפן במנוחה ואינו מוצג שוב: כשפותחים את העמוד מחדש, השדה ריק עם ההערה "מוגדר - השאירו ריק כדי לשמור את הערך הנוכחי, או הזינו ערך חדש כדי להחליפו." השאירו אותו ריק כדי לשמור את המפתח השמור.
שלב 5: שליחת פוש לבדיקה
- התקינו גרסה של האפליקציה שהסביבה שלה תואמת לזו שבחרתם, פתחו אותה ואשרו התראות. ה-SDK רושם את הטוקן של המכשיר ב-Joryio.
- צרו קמפיין פוש (או פתחו טיוטה) שנשלח מהאפליקציה הזו.
- לחצו על שלח push לבדיקה בווריאנט, בחרו את המשתמש שמחובר במכשיר שלכם ושלחו.
אם הבדיקה נכשלת, הודעת השגיאה כוללת את הסיבה ש-APNs החזירה - חפשו אותה בטבלה למטה. לתהליך הקמפיין המלא ראו התראות פוש.
שגיאות נפוצות ופתרונות
| מה רואים | סיבה סבירה | פתרון |
|---|---|---|
BadDeviceToken | טוקן המכשיר הונפק לסביבה האחרת - למשל גרסת TestFlight כש-Joryio מוגדרת לפיתוח (Sandbox). | הגדירו את Environment כך שיתאים לגרסה (ראו שלב 3), ואז פתחו שוב את האפליקציה במכשיר כדי שתרשום את הטוקן שלה מחדש. |
DeviceTokenNotForTopic | הטוקן שייך לאפליקציה (מזהה bundle) אחרת מזו שהאישורים שולחים עבורה. | ודאו שבמכשיר רצה האפליקציה שמחוברת למפתח ה-SDK של אפליקציית Joryio הזו, ושהמפתח שייך לצוות המפתחים שהאפליקציה שייכת לו. |
InvalidProviderToken | ה-Key ID, ה-Team ID או תוכן ה-.p8 לא תואמים - למשל Key ID של מפתח אחד עם תוכן של מפתח אחר, או מפתח מצוות אחר. | הזינו מחדש את שלושת הערכים מאותו מפתח ומאותו צוות. הדביקו את כל קובץ ה-.p8, כולל שורות ה-BEGIN וה-END. |
TopicDisallowed | המפתח לא מורשה לשלוח לאפליקציה הזו - למשל מפתח Topic Specific שלא כולל את מזהה ה-bundle שלכם, או מפתח שמוגבל לסביבה האחרת. | צרו מפתח שמכסה את מזהה ה-bundle ואת הסביבה שלכם, או השתמשו במפתח Team Scoped. |
Unregistered | האפליקציה הוסרה או שהטוקן כבר לא פעיל. | אין מה לתקן באישורים. Joryio מפסיקה לשלוח לטוקן הזה. |
| "no device accepted the notification" | למשתמש אין מכשיר iOS רשום לאפליקציה הזו. | פתחו את האפליקציה עם ה-SDK המשולב במכשיר, אשרו התראות, וודאו שאתם בודקים עם אותו משתמש. |
| קובץ המפתח אבד | Apple מאפשרת הורדה אחת בלבד. | צרו מפתח חדש (שלב 1), הזינו אותו ב-Joryio, ואז בטלו את המפתח הישן. |
| מפתח בוטל (revoked) | כל שליחה עם המפתח הזה נכשלת. | צרו מפתח חדש והזינו אותו ב-Joryio. |
אבטחה והחלפת מפתחות
- התייחסו לקובץ ה-
.p8כסוד: כל מי שמחזיק בו, יחד עם ה-Key ID וה-Team ID, יכול לשלוח התראות למשתמשים שלכם. אל תכניסו אותו לבקרת גרסאות ואל תשלחו אותו במייל או בצ'אט. - אם אתם חושדים שהמפתח דלף, צרו מפתח חדש, הזינו אותו ב-Joryio, ואז בטלו את הישן: ב-Certificates, Identifiers & Profiles → Keys, לחצו על המפתח, לחצו על Revoke ואשרו. הביטול נכנס לתוקף מיד בכל שירות שמשתמש במפתח.
- כדי להחליף מפתח בלי השבתה, עבדו באותו סדר: קודם המפתח החדש ב-Joryio, ורק אחר כך ביטול הישן. Apple מגבילה את מספר המפתחות שצוות יכול להחזיק לכל סביבה, ולכן ייתכן שתצטרכו לבטל מפתח שאינו בשימוש לפני יצירת מפתח חדש.
קשור
- iOS SDK - שילוב ה-SDK והרשמה לפוש
- קבלת אישורי Firebase (FCM) - המקבילה ל-Android
- התראות פוש - יצירה ובדיקה של קמפייני פוש
- Apple: Create a private key to access a service, Establishing a token-based connection to APNs