Provisioning Profile: ano ito, ano ang mga uri, at paano ito gumagana

Ano ang Provisioning Profile

Ang Provisioning Profile ay isang digital configuration file sa format na .mobileprovision (para sa iOS) o .provisionprofile (para sa macOS) na ginagamit ng Apple para kontrolin ang pag-install at pagpapatakbo ng mga app sa mga device. Naglalaman ang profile ng metadata ng pag-sign ng code, kung wala nito ay hindi maipapatakbo ang app sa pisikal na iPhone, iPad, o Apple Watch — hindi kailangan ng profile ang simulator dahil hindi naka-sign ang code para patakbuhin sa totoong processor.

Inilalabas ang profile sa pamamagitan ng Apple Developer Portal at may validity period — kadalasang isang taon para sa Development at Distribution profile. Ayon sa patakaran ng Apple, awtomatikong naka-ugnay ang profile sa sertipikado ng Apple Developer Program kung saan ito naka-sign: kung marevoke o mag-expire ang sertipikado, hihinto ang paggana ng profile.

Ang bawat profile ay naglalaman ng natatanging UUID na ginagamit ng Xcode para kilalanin ang profile sa keychain. Xcode ay awtomatikong pumipili ng angkop na profile habang nagbu-build, ngunit maaaring baguhin ng developer ang pagpili sa mga setting ng Signing & Capabilities. Sa isang device ay maaaring mag-install ng walang limitasyong bilang ng profile — ginagamit ito ng system ng Apple para sa pamamahala ng device (MDM) para sa corporate distribution ng mga app.

Para saan ang Provisioning Profile

Ang pag-sign ng code ang pangunahing dahilan kung bakit umiiral ang mga profile. Kinakailangan ng Apple na ang bawat app na patatakbuhin sa device na may iOS ay naka-sign sa sertipikadong inilabas ng Apple. Ang Provisioning Profile ay nagsisilbing ugnay: kinukumpirma nito na may karapatan ang developer na patakbuhin ang app sa device na ito. Ayon sa Apple Security Guide (2025), pinipigilan ng mekanismo ng profile ang pag-install ng malisyosong software sa mga device ng mga user kahit na ma-compromise ang sertipikado ng developer.

Tumutukoy din ang profile kung aling mga system service ang available sa app. Kung gumagamit ang app ng Push notifications, kinakailangan ng Apple Push Notification service (APNs) ang tamang entitlements sa loob ng profile. Kung wala ito, hindi maihahatid ang mga notification ng server sa device. May katulad na patakaran para sa iCloud, App Groups, Wallet, HealthKit, at iba pang framework ng Apple.

Pagkakaiba sa sertipikado

Madalas na ikinalilito ng mga developer ang Provisioning Profile at Apple Certificate. Ang sertipikado ay isang digital na dokumento na nagkukumpirma ng identidad (sino ang pumipirma), habang ang profile ay isang configuration (anong app, sa anong device, may anong karapatan). Maaaring gamitin ang isang sertipikado sa ilang profile, at ang isang profile ay naka-ugnay sa eksaktong isang sertipikado. Inirerekomenda ng Apple ang paggawa ng hiwalay na profile para sa bawat app at bawat senaryo — Development, Ad Hoc, App Store.

Paano gumagana ang Provisioning Profile

Binubuo ang proseso ng pag-sign ng app ng ilang hakbang na isinasagawa nang sunud-sunod. Xcode ay kumukuha ng binary file ng app (App Bundle), pinipirmahan ito ng pribadong key ng developer, inilalagay ang Provisioning Profile dito, at ipinapadala sa device. Sinusuri ng device ang lagda gamit ang pampublikong key ng Apple, ikinukumpara ang UUID ng profile sa listahan ng mga pinagkakatiwalaang profile sa system, at pinapatakbo lamang ang app kung lahat ng pagsusuri ay matagumpay.

Kapag nag-download ang user ng app mula sa App Store, iba ang mekanismo. App Store Connect ay pinipirmahan muli ang app gamit ang sariling Distribution sertipikado ng Apple, na pinapalitan ang profile ng developer ng Store profile. Nangangahulugan ito na ang app na na-publish sa pamamagitan ng App Store ay technically naka-sign ng Apple, hindi ng developer — bagama't sinusuri ang orihinal na lagda ng developer sa yugto ng pag-upload ng build sa App Store Connect.

Para sa Ad Hoc distribution, nirerehistro ng profile ang mga partikular na UDID ng device kung saan pinapayagan ang pagpapatakbo. Ang libreng account ng Apple Developer Program ay limitado sa 100 device bawat taon para sa pag-test. Ang Enterprise profile (para sa internal distribution sa loob ng organisasyon) ay walang limitasyon sa bilang ng device, ngunit nangangailangan ng aktibong subscription sa Apple Developer Enterprise Program na nagkakahalaga ng $299 bawat taon.

Life cycle ng profile

Ang validity period ng Provisioning Profile ay isang taon mula sa sandaling ito ay ginawa. 30 araw bago mag-expire, nagsisimula ang Apple na magpadala ng push notification sa developer sa pamamagitan ng Xcode at Developer Portal. Kung mag-expire ang profile, patuloy na gagana ang app sa device (kung na-install na), ngunit hindi mai-install ang bagong build gamit ang profile na ito. Xcode ay magbibigay ng error sa pag-sign ng code na may code -402620394 kapag nagtangkang mag-build gamit ang expired na profile. Inirerekomenda ng Apple ang pag-set up ng awtomatikong pag-renew ng profile sa pamamagitan ng Xcode Accounts Preferences — kung gayon, ina-update ng Xcode ang profile 24 oras bago mag-expire.

Mga uri ng Provisioning Profile

Nagbibigay ang Apple ng apat na pangunahing uri ng Provisioning Profile, bawat isa ay para sa partikular na yugto ng life cycle ng app. Ang Development profile ay nagpapahintulot sa pagpapatakbo ng app sa mga pisikal na device na idinagdag sa Apple Developer Portal at ginagamit sa yugto ng pag-develop at QA testing. Para sa paggawa ng Development profile, sapat na ang libreng developer account ng Apple.

Ang Ad Hoc profile ay para sa pamamahagi ng app sa limitadong grupo ng mga tester nang hindi ginagamit ang App Store. Nirerehistro ng profile ang hanggang 100 device ayon sa UDID, at maaaring mai-install ang app nang direkta sa pamamagitan ng iTunes, Apple Configurator, o MDM solutions. Ang Ad Hoc build ay may validity period na 12 buwan at hindi kinakailangan ang pagdaan sa review ng Apple.

Ang App Store profile ay ginagamit lamang para sa pag-publish ng app sa App Store at hindi naglalaman ng listahan ng device — ang Apple mismo ang namamahala sa pamamahagi pagkatapos maaprubahan ang build. Kapag nag-upload ng archive sa App Store Connect, awtomatikong ginagamit ng Xcode ang App Store profile kung naka-install ito sa system. Ang Enterprise profile ay para sa mga organisasyong may Apple Developer Enterprise Program at nagpapahintulot sa pamamahagi ng mga app sa loob ng kumpanya nang walang limitasyon sa bilang ng device at walang review ng Apple.

Istruktura ng Provisioning Profile

Ang Provisioning Profile ay isang file sa DER format na naka-sign ng Apple, na ang nilalaman ay maaaring tingnan sa pamamagitan ng command line. Ang Security framework ng macOS ay nagbibigay-daan sa pag-decode ng .mobileprovision sa nababasang XML plist. Sa loob ng profile ay makikita ang: UUID ng profile, App ID (prefix ng team + Bundle Identifier), listahan ng mga sertipikado, listahan ng mga pinapayagang device (para lamang sa Development at Ad Hoc), entitlements, at validity period.

Ang App ID — ang natatanging identificador ng app na binubuo ng Team ID (10 karakter na itinalaga ng Apple) at Bundle Identifier (halimbawa, com.example.myapp). Ang App ID ay maaaring explicit (eksaktong tugma sa Bundle Identifier) o wildcard (pattern na *.example.com para sa ilang app). Hindi inirerekomenda ng Apple ang paggamit ng wildcard para sa mga app na gumagamit ng Push notifications o iCloud — ang mga serbisyong ito ay nangangailangan ng explicit App ID.

Ang Entitlements — XML block sa loob ng profile na tumutukoy sa mga karapatan ng app sa access sa mga system resource. Kasama sa karaniwang entitlements ang: aps-environment (Push notifications), com.apple.developer.icloud-services (iCloud), com.apple.security.application-groups (App Groups para sa Widget at Share Extension). Awtomatikong idinaragdag ng Apple ang entitlements sa profile batay sa mga naka-enable na Capabilities sa Xcode. Anumang hindi pagkakatugma sa pagitan ng entitlements sa profile at ng mga hinihingi sa code ay nagdudulot ng error sa pag-sign.

Paggawa ng Provisioning Profile sa Apple Developer

Posible ang paggawa ng profile sa dalawang paraan: sa pamamagitan ng web interface ng Apple Developer Portal o awtomatiko sa pamamagitan ng Xcode. Para sa karaniwang proyekto, awtomatikong pinamamahalaan ng Xcode ang mga profile kapag naka-enable ang opsyong Automatically manage signing. Gumagawa ang Xcode ng sertipikado, profile, at App ID sa loob ng ilang segundo, na naka-sync sa Apple Developer Portal. Gayunpaman, para sa CI/CD pipeline ay kinakailangan ang manu-manong pamamahala.

Para sa manu-manong paggawa ng profile sa Apple Developer Portal, kinakailangan: pumunta sa seksyong Certificates, Identifiers & Profiles, piliin ang Profiles, at i-click ang "+". Pagkatapos ay piliin ang uri ng profile (Development, Ad Hoc, App Store, o Enterprise), piliin ang App ID mula sa listahan ng mga naka-register, piliin ang sertipikado ng developer, at (para sa Development at Ad Hoc) piliin ang mga device. Pagkatapos gawin, dina-download ang profile sa format na .mobileprovision at ini-install sa pamamagitan ng dobleng pag-click sa Xcode.

Ang CI/CD server ay nangangailangan ng espesyal na pamamaraan: ang profile at sertipikado ay dapat iimbak sa secure na repository (halimbawa, sa mga secret ng GitHub Actions). Habang nagbu-build, nilo-load ang profile sa agent, inilalagay sa folder na ~/Library/MobileDevice/Provisioning Profiles, at ini-import ang sertipikado sa keychain. Ang Fastlane — sikat na tool para sa pag-automate ng pag-sign — ay nagbibigay ng command na match, na nagsi-sync ng mga profile at sertipikado sa pagitan ng mga developer sa pamamagitan ng naka-encrypt na git repository.

Halimbawa: pagsusuri ng profile sa pamamagitan ng command line

Para sa pag-diagnose ng mga problema sa pag-sign ng code, maaari mong i-decode ang .mobileprovision at suriin ang nilalaman nito. Ang command sa ibaba ay kumukuha ng XML plist mula sa profile at ini-save ito sa nababasang format:

# Pag-decode ng .mobileprovision sa XML
security cms -D -i "path/to/embedded.mobileprovision" \
  -o "profile.plist"

# Pagsusuri ng validity period ng profile
plist -convert xml1 profile.plist -o -
grep -A 1 "ExpirationDate" profile.plist

Ang utility na Security mula sa macOS Command Line Tools ay nagde-decode ng CMS-signed file ng profile. Ang flag na -D ay nangangahulugang decode, -i — ang input file. Pagkatapos i-decode, kino-convert ng utility na plist ang binary plist sa XML, at kinukuha ng grep ang petsa ng pag-expire. Kapaki-pakinabang ang paraang ito sa CI/CD para suriin na hindi expired ang profile bago buuin ang release build.

Mga karaniwang error sa Provisioning Profile

Ang pinakakaraniwang error ay ang "No matching provisioning profiles found" habang nagbu-build sa Xcode. Lumalabas ito kapag hindi makahanap ang Xcode ng profile na tumutugma sa configuration ng build: ang Bundle Identifier ay hindi tumutugma sa App ID sa profile, ang sertipikado ay hindi naka-install sa keychain, o expired na ang profile. Solusyon — suriin ang mga setting ng Signing & Capabilities sa target at kung kinakailangan ay lumipat sa Automatically manage signing.

Ang error na "Provisioning profile doesn't include the selected device" ay lumalabas kapag nagtangkang patakbuhin ang Development o Ad Hoc build sa device na ang UDID ay hindi pa idinagdag sa profile. Pinapayagan ng Apple Developer Portal ang pagdaragdag ng device sa umiiral na profile — pagkatapos nito, kailangang i-download muli at i-install ang profile. Xcode sa awtomatikong pamamahala ng pag-sign ay awtomatikong idinaragdag ang konektadong device sa profile.

Ang problema sa entitlements ay lumalabas sa pamamagitan ng error na "The executable was signed with invalid entitlements" habang nag-upload sa App Store Connect. Ang dahilan — hindi pagkakatugma ng entitlements sa profile at ng .entitlements file ng proyekto. Kinakailangan ng Apple na ang set ng mga karapatan sa profile ay superset ng mga karapatang hinihingi ng app. Solusyon — suriin ang Capabilities sa target ng Xcode at tiyakin na ang lahat ng naka-enable na serbisyo ay may kaukulang entitlements sa profile. Ang Fastlane ay may kasamang command na produce, na nagsi-sync ng App ID at mga profile na may updated na entitlements.