תעודת מפתח iOS ו-provisioning profile עם Expo

תעודת מפתח iOS מוכיחה מי חתם על האפליקציה שלך. ה-provisioning profile (פרופיל הקצאה) מקשר את התעודה הזו לאפליקציה מסוימת וקובע איפה מותר לה לרוץ. עם Expo כמעט אף פעם לא תצטרך ליצור אותם ידנית: EAS יוצר אותם, שומר אותם ומחדש אותם כשאתה מריץ build.

עדיין כדאי להבין מה כל קובץ עושה. ביום שבו build מסרב להיות מותקן או שהעלאה נתקעת, הידע הזה חוסך לך יום שלם. המדריך הזה עובר על ארבעת הרכיבים, משך החיים שלהם, המגבלות של Apple והשגיאות הנפוצות, עם הפתרון לכל אחת.

אני מפרסם את אפליקציות ה-iOS שלי עם Expo ו-EAS, ביניהן Solys ו-TradaZen. התהליך המלא נמצא בפרסום אפליקציית iOS בלי Mac. כאן אנחנו פותחים את מכסה המנוע של החתימה.

למה Apple דורשת חתימה

אפליקציית iOS חייבת להיות חתומה כדי שאפשר יהיה להתקין אותה על אייפון או לשלוח אותה ל-App Store Connect. החתימה מבטיחה שהאפליקציה מגיעה ממפתח ש-Apple מכירה ושאף אחד לא שינה אותה מאז.

לגבי ה-App Store, יש פרט אחד מרגיע. לפי ההערה הטכנית TN3161 של Apple, ה-App Store בודק שתעודת ההפצה שלך תקפה בזמן ההעלאה, ואז חותם מחדש על האפליקציה, כך שהיא כבר לא תלויה בתאריך התפוגה של התעודה שלך. התעודות שלך צריכות להיות תקפות ברגע ההעלאה, לא לאורך כל חיי האפליקציה.

ארבעת הרכיבים שצריך להכיר

התיעוד של Expo על credentials מונה שלושה ל-iOS: תעודת ההפצה, הפרופילים ומפתח ה-push notifications. אני מוסיף את ה-App ID, שבלעדיו אין שום פרופיל.

תעודת ההפצה

זו החתימה שלך כמפתח. העזרה של Apple על תעודות מבחינה בין שתי משפחות:

• Apple Development משמשת להרצת האפליקציה על המכשירים שלך בזמן הפיתוח. היא שייכת לאדם אחד.
• Apple Distribution משמשת להפצה למכשירי בדיקה מוגדרים או להעלאה ל-App Store Connect. היא שייכת לצוות, ורק בעל החשבון או admin יכולים ליצור אותה.

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

מזהה האפליקציה (App ID)

ה-App ID מזהה את האפליקציה שלך בתוך פרופיל. הוא מבוסס על ה-bundle identifier שלך, למשל com.exemple.monapp (דוגמה בדויה). לפי העזרה של Apple, הוא כולל גם את רשימת היכולות המותרות: push notifications, ‏App Groups, ‏Sign in with Apple ועוד.

ב-Expo זה השדה ios.bundleIdentifier בקונפיגורציה שלך. תבחר אותו פעם אחת ולתמיד: הוא חייב להיות זהה בכל מקום, גם בקונפיגורציה וגם ב-App Store Connect. ה-App ID לא פג. ולפי התיעוד של Expo על יכולות iOS, ‏EAS מסנכרן את היכולות שלו עם הקונפיגורציה שלך בכל build.

פרופיל ההקצאה

הפרופיל הוא החוליה המקשרת. הוא מכיל App ID, תעודה, ובהתאם לסוג שלו, רשימת מכשירים מורשים. שלושה סוגים רלוונטיים לך:

• Development: אפליקציית הבדיקה שלך על המכשירים הרשומים שלך.
• Ad hoc: build שאפשר להתקין על רשימה מסוימת של מכשירים, שכל אחד מהם מזוהה לפי ה-UDID שלו. זו ה"הפצה הפנימית" (internal distribution) של EAS.
• App Store: בשביל App Store Connect ו-TestFlight. הוא לא מכיל שום רשימת מכשירים, כמו שמסבירה ההערה TN3125.

לכל פרופיל יש תאריך תפוגה: בדרך כלל לא יותר משנה לפי Apple, ו-12 חודשים לפי Expo.

מפתח ה-push notifications ‏(APNs)

מפתח ה-APNs מאשר לשרת שלך, או לשרת של Expo, לשלוח התראות לאפליקציה שלך. זה קובץ ‎.p8 שאפשר להוריד רק פעם אחת: Apple לא שומרת אותו בחשבון שלך. אותו מפתח משמש לכל האפליקציות שלך, והוא אף פעם לא פג.

טבלת סיכום

רכיב	משמש ל	משך	מי מנהל אותו עם Expo
תעודת הפצה	חתימה על ה-builds שלך	בדרך כלל שנה	‏EAS, אחרי התחברות
App ID	זיהוי האפליקציה שלך	לא פג	אתה, ואז EAS
פרופיל App Store	שליחה ל-Apple	עד 12 חודשים	EAS
פרופיל ad hoc	התקנה על האייפונים שלך	עד 12 חודשים	‏EAS והמכשירים שלך
מפתח push ‏APNs	שליחת התראות	לא פג	‏EAS או אתה
פרופיל של חשבון חינמי	בדיקה דרך Xcode	7 ימים	‏Xcode, לא EAS

"אתה, ואז EAS": אתה בוחר את ה-bundle identifier, ו-EAS מטפל ביכולות. "EAS והמכשירים שלך": אתה רושם כל אייפון בדיקה, ו-EAS בונה את הפרופיל. השורה האחרונה נוגעת לחשבון Apple החינמי: לפי העזרה של Apple על חשבונות, הפרופילים שלו פגים 7 ימים אחרי שנוצרו.

המגבלות של Apple שכדאי להכיר

• תעודות הפצה: מעט מאוד לכל חשבון. העזרה של Apple מדברת על אחת לכל סוג הפצה ולכל צוות, והטבלה של Expo על מגבלה של 2. תזכור את הכלל: אל תיצור תעודה חדשה בכל build או בכל מחשב.
• מפתחות APNs: לכל היותר 2 לחשבון, לפי Expo.
• פרופילים: אין מגבלה, לפי Expo.
• מכשירים: עד 100 לכל משפחת מוצרים ולכל שנת מנוי, לפי העזרה של Apple על מכשירים. השבתת מכשיר לא משחררת מקום. המונה חוזר ל-100 בתחילת שנת המנוי הבאה, אם אתה מסיר את המכשירים.

מה EAS עושה בשבילך

לפי העמוד של Expo על managed credentials, ה-build הראשון שלך ל-iOS מציע לך ליצור את מה שחסר. אתה מתחבר לחשבון ה-Apple Developer שלך, ו-EAS יוצר את תעודת ההפצה, את הפרופיל ואת מפתח ה-push, ואז שומר אותם בשרתים שלו. ה-builds הבאים משתמשים בהם שוב.

שלוש נקודות שימושיות:

• הסיסמה שלך ל-Apple נשארת על המחשב שלך. עמוד האבטחה של Expo מבהיר שהיא לא נשלחת לשרתים שלהם, ושה-credentials השמורים מוצפנים.
• ‏eas credentials מראה לך הכל: תעודה, פרופילים, מפתח push. הפקודה מאפשרת גם להחליף או להסיר אותם.
• מחיקה ב-EAS לא מוחקת אצל Apple. כדי לשחרר מקום, צריך לבטל (revoke) בפורטל של Apple.

אפשר גם לשמור שליטה עם credentials מקומיים: קובץ credentials.json מצביע על התעודה שלך (‎.p12) ועל הפרופיל שלך (‎.mobileprovision). ‏Expo מבקשת להוסיף את הקבצים האלה ל-.gitignore. זה אותו כלל כמו במפתחות API של אפליקציית Expo: סוד אף פעם לא נכנס ל-repo.

שגיאות נפוצות ואיך לפתור אותן

פרופיל שפג תוקפו

build מסוג ad hoc כולל בתוכו את הפרופיל שלו: כשהוא פג, האפליקציה כבר לא נפתחת על אייפוני הבדיקה שלך. לעומת זאת, ב-App Store, ‏Expo מאשרת שלתפוגה אין שום השפעה על האפליקציה ב-production. הפתרון: תריץ build מחדש. ‏EAS יוצר פרופיל חדש, או שאתה עושה את זה בעצמך עם eas credentials. אחר כך תתקין מחדש את ה-build החדש על המכשירים שלך.

אל תתבלבל עם TestFlight: ‏build של TestFlight פג אחרי 90 יום, בלי קשר לתעודה שלך. הפרטים נמצאים בTestFlight לבדיקת אפליקציית האייפון שלך.

תעודה שפגה או בוטלה

‏Apple ברורה: אם המנוי שלך בתוקף, האפליקציות שכבר ב-App Store לא נפגעות. אבל אי אפשר יותר להעלות build שחתום בתעודה הזו. ‏build שהועלה אבל עוד לא הוגש לבדיקה יכול להיות מסומן כ-Invalid Binary אם התעודה שלו בוטלה. ופרופילים שמכילים תעודה מבוטלת הופכים ללא תקפים.

הפתרון: תיצור תעודה חדשה דרך eas credentials או ב-build הבא, ואז תן ל-EAS לבנות מחדש את הפרופילים. ואף פעם אל תבטל מתוך רפלקס תעודה שעובדת.

מכשיר שלא נמצא בפרופיל ה-ad hoc

קישור ההתקנה עובד אצלך, אבל לא באייפון של בודק. הסיבה: התיעוד של Expo על internal distribution מסביר שרק מכשירים שהיו בפרופיל בזמן ה-build יכולים להתקין את האפליקציה.

הפתרון:

1. תרשום את המכשיר עם eas device:create.
2. תריץ build מחדש במצב אינטראקטיבי, מחובר לחשבון ה-Apple שלך, כדי ש-EAS יעדכן את הפרופיל. או שתחתום מחדש על ה-build הקיים עם eas build:resign, בלי לקמפל הכל מחדש.
3. ב-CI, המצב הלא אינטראקטיבי משתמש שוב בפרופיל בלי לעדכן את הרשימה שלו. תוסיף את האפשרות --refresh-ad-hoc-provisioning-profile.

בחשבון חדש או כזה שחודש הרגע, ל-Apple יכולות לקחת 24 עד 72 שעות לעבד מכשיר חדש. ה-build הראשון שכולל אותו עלול אז להיכשל: תחכה, ואז תריץ שוב.

הגעת למגבלת התעודות

‏Apple מסרבת ליצור תעודת הפצה חדשה. הרבה פעמים יש תעודות ישנות שמסתובבות: שנוצרו מ-Xcode על Mac אחר או על ידי שירות build אחר. תשתמש שוב בתעודה הקיימת אם יש לך את קובץ ה-‎.p12 שלה. אחרת, תבטל את זו שכבר לא בשימוש בפורטל של Apple. ביטול לא משפיע על האפליקציות שכבר באוויר, אבל הוא הופך ללא תקפים את הפרופילים שהכילו אותה.

‏"Provisioning profile doesn't include signing certificate"

ההודעה הזו של Xcode אומרת שהפרופיל לא מכיל את התעודה שהמפתח הפרטי שלה נמצא על המחשב שלך. הסיבה הטיפוסית: ערבוב של החתימה האוטומטית של Xcode עם ה-credentials של EAS. תבחר מקור אמת אחד: ‏builds של EAS עם managed credentials, או credentials מקומיים, אבל לא את שניהם.

התראות שנפסקו אחרי ביטול מפתח

אם אתה מבטל את מפתח ה-APNs שלך, ‏Expo מזהירה שכל האפליקציות שמשתמשות בו מפסיקות לקבל התראות. תיצור מפתח חדש ותעלה אותו עם eas credentials. ה-Expo Push tokens של המשתמשים שלך לא משתנים.

הוספת יכולת, פרופיל לא תקף

הפעלה של שירות כמו push notifications או App Groups הופכת את הפרופיל ללא תקף: צריך ליצור אותו מחדש. עם EAS, סנכרון היכולות קורה בכל build. אם הפרופיל עדיין נדחה, ‏eas credentials מאפשר ליצור אחד חדש.

מה הלאה אחרי החתימה

‏build חתום הוא רק שלב אחד. דף האפליקציה, צילומי המסך, הפרטיות וההגשה לבדיקה מרוכזים בפרסום אפליקציה ב-App Store. אם עוד אין לך מנוי, תתחיל מחשבון המפתח של Apple. וכדי להבין למה אני ממליץ על Expo למתחילים, תקרא את React Native ו-Expo לאפליקציית מובייל.

אם אתה מתכונן לפרסום הראשון שלך

לפני ההעלאה הראשונה, תעשה את האבחון החינמי: הוא אומר לך מה באמת תוקע את הפרויקט שלך ושולח לך את הצ'קליסט שלי נגד דחיות של Apple.

כדי לבנות את האפליקציה, לחבר מנויים ולפרסם אותה בלי להילחם בחתימה, ה-iOS & Android Kit מלווה את התהליך בארבעה שלבים עם קוד הבסיס של האפליקציות שלי, בקצב שלך.

שאלות נפוצות

מה זה provisioning profile?

זה הקובץ שמאשר לאפליקציה שלך לרוץ או להישלח ל-Apple. הוא מקשר App ID, תעודה, ובהתאם לסוג שלו, רשימת מכשירים. פרופיל App Store לא מכיל אף מכשיר, ופרופיל ad hoc מונה כמה מהם.

האם תעודת מפתח iOS חינמית?

אין לה מחיר נפרד: תעודת ההפצה כלולה ב-Apple Developer Program, ב-99 דולר לשנה. עם חשבון Apple חינמי, ‏Xcode נותן לך לבדוק על 3 מכשירים לכל היותר, אבל הפרופילים פגים אחרי 7 ימים ואי אפשר לפרסם.

כמה זמן תעודת הפצה של Apple בתוקף?

בדרך כלל שנה מרגע יצירתה, לפי Apple. גם פרופילי ההקצאה תקפים 12 חודשים לכל היותר. מפתח ה-push notifications, לעומת זאת, אף פעם לא פג.

מה קורה אם תעודת ההפצה שלי פגה?

כלום לאפליקציות שכבר ב-App Store, כל עוד המנוי שלך בתוקף. פשוט אי אפשר יותר להעלות build חדש שחתום בתעודה הזו. עם EAS, תעודה חדשה נוצרת ב-build הבא או עם eas credentials.

צריך Mac כדי ליצור תעודת iOS?

לא, אם אתה עובד עם EAS. אתה מתחבר לחשבון ה-Apple שלך משורת הפקודה, ו-EAS יוצר את התעודה ואת הפרופיל, גם ב-Windows וגם ב-Linux. בלי EAS, השיטה הקלאסית עוברת דרך Xcode או ה-Keychain Access של Mac.

כמה מכשירים יכול להכיל פרופיל ad hoc?

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