Особенности сборки и доставки iOS-приложений

В этой статье мы делимся опытом сборки и доставки пользователям приложений для iOS, который накопился у студии Plarium Krasnodar в процессе отладки CI/CD.

Подготовка

Каждый человек, так или иначе связанный с разработкой приложений для устройств Apple, уже успел оценить спорное удобство инфраструктуры. Сложности встречаются повсюду: начиная с меню профиля разработчика и заканчивая инструментами отладки и сборки.

Статей об «азах» предостаточно в сети, поэтому постараемся выделить главное. Вот что нужно для успешной сборки приложения:

• аккаунт разработчика;
• устройство на базе macOS, выступающее в роли билд-сервера;
• сгенерированный сертификат разработчика, который будет далее использоваться для подписи приложения;
• созданное приложение с уникальным ID (следует отметить важность Bundle Identifier, потому что применение wildcard ID делает невозможным использование многих функций приложения, например: Associated Domains, Push Notifications, Apple Sign In и прочих);
• профиль подписи приложения.

Сертификат разработчика следует сгенерировать через Keychain на любом устройстве на базе macOS. Очень важным является тип сертификата. В зависимости от среды приложения (Dev, QA, Staging, Production) он будет различаться (Development или Distribution), так же как и тип профиля подписи приложения.

Основные типы профилей:

• Development — предназначен для подписи приложения команды разработчиков, используется Development-сертификат (имя вида iPhone Developer: XXXXX);
• Ad Hoc — предназначен для подписи тестового приложения и внутренней проверки QA-отделом, используется Distribution-сертификат разработчика (имя вида iPhone Distribution: XXXXX);
• App Store — релизный билд для внешнего тестирования через TestFlight и выгрузки в App Store, используется Distribution-сертификат разработчика.

При генерации профилей Development и Ad Hoc также указывается список устройств, на которые можно установить билд, что позволяет дополнительно разграничить доступ для пользователей. В профиле App Store нет списка устройств, так как разграничением доступа при закрытом бета-тестировании занимается TestFlight, о котором будет рассказано позже.

Для наглядности можно представить профиль разработчика в виде таблички ниже. Так проще понять, какие параметры для сборки нам нужны и откуда их брать.

Сборка

Чтобы было проще разделять сборки по проекту и среде, используем имена профилей вида ${ProjectName}_${Instance}, то есть имя проекта + инстанс (зависит от среды приложения: Dev, QA, GD, Staging, Live и так далее).

При импорте на билд-сервер профиль меняет название на уникальный ID и перемещается в папку /Users/$Username/Library/MobileDevice/Provisioning Profiles (где $Username соответствует имени учетной записи пользователя билд-сервера).

Существует два способа сборки файла *.ipa — устаревший (PackageApplication) и современный (через создание XcAchive и экспорт). Первый способ считается устаревшим, так как с версии 8.3 модуль упаковки app-файла убран из дистрибутива Xcode. Для его использования надо скопировать модуль из старого Xcode (версии 8.2 и более ранних) в папку:
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/

И затем выполнить команду:

chmod +x /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/*

Далее нужно собрать *.app-файл приложения:

xcodebuild \
-workspace $ProjectDir/$ProjectName.xcworkspace \
-scheme $SchemeName \
-sdk iphoneos \
build \
-configuration Release \
-derivedDataPath build \
CODE_SIGN_IDENTITY=”$DevAccName”\
PROVISIONING_PROFILE=”$ProfileId”
DEPLOYMENT_POSTPROCESSING=YES \
SKIP_INSTALL=YES \
ENABLE_BITCODE=NO

Где:

-workspace — путь к файлу проекта.

-scheme — используемая схема, указанная в проекте.

-derivedDataPath — путь выгрузки собранного приложения (*.app).

CODE_SIGN_IDENTITY — имя аккаунта разработчика, которое можно проверить в Keychain (iPhone Developer: XXXX XXXXXXX, без TeamID в скобках).



PROVISIONING_PROFILE — ID профиля для подписи приложения, который можно получить командой:

cd "/Users/$Username/Library/MobileDevice/Provisioning Profiles/" && find *.mobileprovision -type f | xargs grep -li ">${ProjectName}_${Instance}<" | sed -e 's/.mobileprovision//'

Если в приложении используется дополнительный профиль (например, для Push Notifications), то вместо PROVISIONING_PROFILE указываем:

APP_PROFILE=”$AppProfile” \
EXTENSION_PROFILE=”$ExtProfile” \

Далее полученный файл *.app следует упаковать в *.ipa. Для этого можно использовать команду вида:

/usr/bin/xcrun --sdk iphoneos PackageApplication \
-v $(find "$ProjectDir/build/Build/Products/Release-iphoneos" -name "*.app") \
-o "$ProjectDir/$ProjectName_$Instance.ipa"

Однако данный способ считается устаревшим с точки зрения Apple. Актуальным является получение *.ipa путем экспорта из архива приложения.

Для начала нужно собрать архив командой:

xcodebuild \
-workspace $ProjectDir/$ProjectName.xcworkspace \
-scheme $SchemeName \
-sdk iphoneos \
-configuration Release \
archive \
-archivePath $ProjectDir/build/$ProjectName.xcarchive \
CODE_SIGN_IDENTITY=”$DevAccName” \
PROVISIONING_PROFILE=”$ProfileId”
ENABLE_BITCODE=NO \
SYNCHRONOUS_SYMBOL_PROCESSING=FALSE

Отличия заключаются в методе сборки и опции SYNCHRONOUS_SYMBOL_PROCESSING, которая отключает выгрузку символов во время сборки.

Далее нам надо сгенерировать файл с настройками экспорта:

ExportSettings="$ProjectDir/exportOptions.plist"

cat << EOF > $ExportSettings
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>compileBitcode</key>
<false/>
<key>uploadBitcode</key>
<false/>
<key>uploadSymbols</key>
<false/>
<key>method</key>
<string>$Method</string>
<key>provisioningProfiles</key>
<dict>
<key>$BundleID</key>
<string>$ProfileId</string>
</dict>
<key>signingCertificate</key>
<string>$DevAccName</string>
<key>signingStyle</key>
<string>manual</string>
<key>stripSwiftSymbols</key>
<true/>
<key>teamID</key>
<string>$TeamID</string>
<key>thinning</key>
<string><none></string>
</dict>
</plist>
EOF

Где:

$Method — метод доставки, соответствует типу профиля подписи приложения, то есть для Development значение будет development, для Ad Hoc — ad-hoc, а для App Store — app-store.

$BundleID — ID приложения, который указан в настройках приложения. Проверить можно командой:

defaults read $ProjectDir/Info CFBundleIdentifier

$DevAccName и $ProfileId — настройки имени разработчика и ID профиля подписи, которые использовались ранее и должны совпадать со значениями в настройках экспорта.

$TeamID — десятизначный ID в скобках после имени разработчика, пример: iPhone Developer: …… (XXXXXXXXXX); можно проверить в Keychain.

Далее с помощью команды экспорта получаем необходимый файл *.ipa:

xcodebuild \
-exportArchive \
-archivePath $ProjectDir/build/$ProjectName.xcarchive \
-exportPath $ProjectDir \
-exportOptionsPlist $ExportSettings

Доставка

Теперь собранный файл нужно доставить конечному пользователю, то есть установить на устройство.

Для распространения билдов Development и Ad Hoc существует множество сервисов вроде HockeyApp, AppBlade и прочих, однако в рамках данной статьи речь пойдет об автономном сервере для раздачи приложений.

Установка приложения для iOS проходит в 2 этапа:

1. Получение манифеста установки приложения через Items Service.
2. Установка файла *.ipa согласно информации, указанной в манифесте, через HTTPS.

Таким образом, нам для начала надо сгенерировать манифест установки (тип файла *.plist) командой:

cat << EOF > $manifest
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>items</key>
<array>
<dict>
<key>assets</key>
<array>
<dict>
<key>kind</key>
<string>software-package</string>
<key>url</key>
<string>$ipaUrl</string>
</dict>
</array>
<key>metadata</key>
<dict>
<key>bundle-identifier</key>
<string>$BundleID</string>
<key>bundle-version</key>
<string>$AppVersion</string>
<key>kind</key>
<string>software</string>
<key>title</key>
<string>$ProjectName_$Instance</string>
<key>subtitle</key>
<string>$Instance</string>
</dict>
</dict>
</array>
</dict>
</plist>
EOF

Как видим, манифест содержит практически все параметры, участвующие в сборке приложения.

Версию приложения ($AppVersion) можно проверить командой:

defaults read $ProjectDir/Info CFBundleVersion

Параметр $ipaUrl содержит прямую ссылку на скачивание файла *.ipa. С седьмой версии iOS приложение должно быть установлено через HTTPS. В восьмой версии немного изменился формат манифеста: были удалены блоки с настройками иконок приложения вида

<images>
   <image>...</image>
</images>

Таким образом, для установки приложения достаточно простой html-страницы со ссылкой вида:

itms-services://?action=download-manifest&url=https://$ServerUrl/$ProjectName/$Instance/iOS/$AppVersion/manifest.plist

Для нужд отделов разработки и тестирования компания Plarium создала свое приложение установки билдов, которое дает нам:

• автономность и независимость,
• централизацию управления доступом и безопасную установку приложений через «временные», динамически создаваемые ссылки,
• расширяемый функционал (то есть команда разработки при необходимости может интегрировать недостающие функции в уже существующее приложение).

Тестирование

Теперь речь пойдет о предрелизном тестировании приложения с помощью TestFlight.

Обязательными условиями для загрузки являются тип профиля подписи App Store и наличие сгенерированных API-ключей.

Есть несколько способов загрузки приложения:

• через Xcode (Organizer),
• через altool,
• через Application Loader для старых версий Xcode (теперь Transporter).

Для автоматической загрузки используется altool, в котором тоже есть два способа авторизации:

• App-Specific Password,
• API Key.

Более предпочтительной является загрузка приложения с помощью API Key.

Для получения API Key переходим по ссылке и генерируем ключ. Кроме самого ключа в формате *.p8, нам понадобятся два параметра: IssuerID и KeyID.



Далее скачанный ключ импортируем на билд-сервер:

mkdir -p ~/.appstoreconnect/private_keys
mv ~/Downloads/AuthKey_${KeyID}.p8 ~/.appstoreconnect/private_keys/

Перед загрузкой приложения в TestFlight нужно выполнить валидацию приложения, делаем это командой:

xcrun altool \
--validate-app \
-t ios \
-f $(find "$ProjectDir" -name "*.ipa") \
--apiKey “$KeyID” \
--apiIssuer “$IssuerID” 

Где apiKey и apiIssuer имеют значения полей со страницы генерации API-ключа.

Далее при успешной валидации выполняем загрузку приложения командой --upload-app c теми же параметрами.

Приложение будет проверено Apple в течение одного-двух дней и после станет доступным внешним тестировщикам: им пришлют на почту ссылки для установки.

Другим способом загрузки приложения через altool является использование App-Specific Password.

Для получения App-Specific Password нужно перейти по ссылке и сгенерировать его в разделе Security.



Далее следует создать в Keychain запись билд-сервера с этим паролем. С 11 версии Xcode это можно сделать командой:

xcrun altool --store-password-in-keychain-item "Altool" -u "$DeveloperName" -p $AppPswd

Где:

$DeveloperName — имя аккаунта iOS-разработчика, используемое для логина в сервисы Apple.

$AppPswd — сгенерированный App-Specific Password.

Далее получаем значение параметра asc-provider и проверяем успешность импорта пароля командой:

xcrun altool --list-providers -u "$DeveloperName" -p "@keychain:Altool"

Получаем вывод:

Provider listing:
- Long Name - - Short Name -
XXXXXXX        XXXXXXXXX

Как видим, искомое значение Short Name (asc-provider) совпадает с параметром $TeamID, который мы использовали при сборке приложения.

Для валидации и загрузки приложения в TestFlight применяем команду:

xcrun altool \
--(validate|upload)-app \  
-f $(find "$ProjectDir" -name "*.ipa") \
-u "$DeveloperName" \
-p "@keychain:Altool" \

В качестве значение параметра -p можно взять значение $AppPswd в незашифрованном (явном) виде.

Однако, как уже было сказано, с точки зрения работоспособности для авторизации altool лучше выбрать API Key, так как в разных версиях Xcode встречаются те или иные проблемы («не видит» Keychain, ошибки авторизации при выгрузке и прочее).

На этом, собственно, все. Желаю всем причастным успешных сборок и беспроблемных релизов в App Store.