Как проверить файл Universal Links с облачного Mac

Ссылка на товар из релизной ветки работает в браузере, но на тестовом устройстве с установленным приложением неизменно открывает веб-страницу. Если сразу менять код перехода в приложении, можно упустить настоящую причину: сначала устройство должно получить файл ассоциации с домена и убедиться, что домен разрешает указанному приложению открывать соответствующие пути. Доставку файла удобно проверить с облачного Mac, а затем повторить тест на устройстве. Раздельные записи о сервере и устройстве дадут больше, чем многократные нажатия на ссылку.

Зафиксируйте воспроизводимый случай

Запишите полный URL, приложение, которое должно открыться, фактический результат, версию системы устройства и версию сборки приложения. Подготовьте как минимум две ссылки: одну должно открывать приложение, другая должна оставаться в браузере. Формулировки «не работает ни одна ссылка» недостаточно: для разных доменов, путей и параметров запроса могут действовать совершенно разные правила.

Уточните и способ проверки. Переход по ссылке и ручной ввод URL в адресную строку браузера — не одно и то же. При повторных проверках команда должна использовать один и тот же способ перехода. Если для продакшена и предпродакшена используются разные домены, заведите отдельную запись для каждого: файл одного домена не объясняет поведение другого.

Записывайте в двух колонках «что сейчас возвращает сервер» и «как сейчас открывает ссылку это устройство». Первое можно сразу проверить повторно, а второе может зависеть от состояния установки и кеша.

Проверьте прямую отдачу файла

В терминале облачного Mac укажите домен, который действительно контролирует команда, а не идентификатор пакета приложения. Файл ассоциации должен быть доступен напрямую по пути /.well-known/apple-app-site-association. Не включайте автоматическое следование перенаправлениям: иначе успешный ответ после редиректа легко принять за прямую отдачу файла.

export APP_DOMAIN='填入团队实际控制的域名'
test "$APP_DOMAIN" != '填入团队实际控制的域名' || exit 1
curl -sS -D aasa-headers.txt \
  -o aasa-body.json \
  "https://${APP_DOMAIN}/.well-known/apple-app-site-association"
cat aasa-headers.txt
wc -c aasa-body.json
plutil -lint -- aasa-body.json

Убедитесь, что HTTP-статус — 200, заголовок Location не ведёт на страницу входа или другой путь, тело ответа не является HTML-страницей с ошибкой, а Content-Type равен application/json. Успешная проверка plutil подтверждает только корректность синтаксиса, но не правил. Если команда завершилась из-за сетевой ошибки, сначала проверьте разрешение домена и TLS-соединение; не считайте старый файл aasa-body.json на диске результатом текущего запроса. Перед повторным запуском можно удалить старый файл, а затем сохранить вместе заголовки и тело ответа.

Сравните результаты из разных сетей

Если файл проходит через кеш или обратный прокси, запросите один и тот же адрес из сети, которой обычно пользуется команда, и с облачного Mac. Сравните тело ответа и сведения о кешировании в заголовках. Если результаты различаются, сначала проверьте путь публикации, ключ кеша и процедуру обновления кеша. Не ослабляйте все правила кеширования, чтобы скрыть проблему: файл ассоциации одного и того же домена должен стабильно возвращать ожидаемое содержимое.

Сверьте идентификаторы и правила путей

Найдите соответствующую запись в applinks.details JSON-файла и посимвольно сверьте appID, составленный из идентификатора команды и идентификатора пакета приложения. Затем проверьте пути URL из неудачных примеров по каждому применимому правилу. Учитываются ли регистр символов и завершающий слеш, влияет ли правило исключения на результат раньше более общего правила — всё это нужно проверять с учётом формата правил, фактически использованного в файле. Доступность пути на сайте сама по себе не означает, что его откроет приложение.

Параметры запроса могут помочь приложению найти нужный контент после открытия, но не заменяют проверку соответствия пути URL. Если команда переходит со старого формата paths на components, сначала убедитесь, что целевая версия системы на устройствах поддерживает выбранную запись, а затем проверьте её на реальных тестовых ссылках. Не меняйте одновременно идентификаторы, правила и код приложения без контрольных примеров.

Затем проверьте сборку и устройство

Когда серверный файл проверен, сверьте конфигурацию связанных доменов, с которой собрано приложение. Запись домена должна указывать на имя хоста, действительно отдающего файл; поддомены нельзя по умолчанию считать взаимозаменяемыми. Убедитесь, что на устройстве установлена именно проверяемая сборка, а не пакет из другой релизной ветки. После изменения конфигурации приложение нужно пересобрать и установить заново: одно лишь обновление файла на сервере не изменит конфигурацию уже установленного приложения.

Сохраните запись о поведении тестового устройства «до изменения», затем установите новую сборку и откройте ту же ссылку тем же способом. Если сервер уже отдаёт новые правила, а устройство по-прежнему ведёт себя по-старому, переустановите приложение и повторите проверку, записав оба результата. Не предполагайте, что получение и проверка файла ассоциации происходят мгновенно; одного нажатия недостаточно, чтобы объявить изменение на сервере неработающим.

Ищите сбой на конкретном этапе, а не повторяйте всё сразу

Если файл недоступен или возвращается перенаправление, исправляйте доставку. Если файл доступен, но идентификаторы или пути не совпадают, исправляйте правила либо конфигурацию сборки. Если и то и другое совпадает, а ошибка возникает на одном устройстве, сравните историю установки, версию системы и способ перехода по ссылке. Меняйте только один уровень за раз и сохраняйте заголовки ответа, тело файла, идентификатор сборки и наблюдения на устройстве до и после изменения. Так можно установить, какое именно исправление подействовало.

Добавьте проверку в процесс выпуска

В задачу выпуска можно включить небольшую проверку: запросить файл ассоциации с рабочего домена, убедиться в отсутствии перенаправления, правильном статусе и корректном JSON, а затем сверить правила на двух путях — один должно открывать приложение, другой не должно. Автоматическая проверка охватывает только сервер и статическую конфигурацию; кто откроет ссылку после нажатия на устройстве, по-прежнему нужно проверять с установленной сборкой.

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

Часто задаваемые вопросы