Приложение не открывается по ссылке из письма? Пользователи жалуются, что сайт открывается в браузере, а не в приложении? Universal Links решают эту проблему напрямую: ссылка вида https://example.com/product/123 открывает приложение на нужном экране, минуя браузер. Никаких кастомных схем (myapp://product/123), которые не работают в Safari и блокируются корпоративными MDM. Мы, команда мобильных разработчиков с опытом более 5 лет, настроили Universal Links для 15+ iOS-проектов с общей аудиторией свыше 2 млн пользователей. На одном из проектов с аудиторией 500 тысяч пользователей мы обнаружили, что пользователи не могли перейти из email-рассылки в конкретный товар — конверсия упала на 20%. После внедрения Universal Links она восстановилась и выросла на 15%. В этой статье — проверенная методика и типовые грабли.
Почему Universal Links лучше кастомных схем?
Кастомные URL-схемы (myapp://) имеют фундаментальные недостатки:
- Не работают в Safari по умолчанию — пользователь видит ошибку «Не удалось открыть приложение».
- Не поддерживаются в корпоративных MDM-средах.
- Не имеют fallback на веб-версию.
Universal Links лишены этих проблем: они используют стандартный HTTPS, поддерживают fallback на сайт и не требуют дополнительных действий от пользователя. Безопасность выше — схема не может быть перехвачена другим приложением.
| Критерий | Universal Links | Custom URL Scheme |
|---|---|---|
| Работа в Safari | Да | Нет (ошибка) |
| Fallback на сайт | Автоматически | Требуется JS |
| MDM-совместимость | Да | Нет |
| Безопасность | Высокая (https) | Низкая |
Как работают Universal Links и где они ломаются?
AASA-файл. На сервере по адресу https://example.com/.well-known/apple-app-site-association должен лежать JSON без расширения файла, с заголовком Content-Type: application/json, доступный по HTTPS без редиректов. Apple парсит этот файл при установке приложения и кэширует на CDN — обновление может занять до 24 часов.
Самая частая ошибка: сервер отдаёт файл с редиректом с http на https, или с 301 на www-версию домена. Apple не следует редиректам при скачивании AASA. Проверяем через curl -v https://example.com/.well-known/apple-app-site-association — должен вернуть 200 с правильным Content-Type.
Формат для iOS 13+ (applinks с details):
{ "applinks": { "details": [{ "appIDs": ["TEAMID.com.example.app"], "components": [ { "/": "/product/*", "comment": "Product pages" }, { "/": "/order/*" } ] }] } } App Entitlements. В Entitlements.plist нужен com.apple.developer.associated-domains с записью applinks:example.com. Забытый entitlement — приложение просто не получает universal link колбек.
Обработка в коде. В AppDelegate или SceneDelegate реализуем application(_:continue:restorationHandler:) (UIKit) или onOpenURL (SwiftUI). Получаем NSUserActivity с типом NSUserActivityTypeBrowsingWeb и webpageURL. Парсим путь, определяем нужный экран, строим навигационный стек.
Разбор URL должен быть устойчивым: webpageURL может прийти с query-параметрами, фрагментами, в верхнем регистре. Используем URLComponents вместо ручного разбора строк.
Тестирование. В симуляторе universal links работают через xcrun simctl openurl booted 'https://example.com/product/123'. На реальном устройстве — через Safari (долгое нажатие на ссылку → «Открыть в приложении»). Xcode → Diagnostics не покажет проблему с AASA — нужен swcutil на Mac и Console.app для логов swcd (Apple's universal links daemon).
Режим разработчика (developer mode)
Для enterprise-приложений или staging-окружений добавляем applinks:example.com?mode=developer в entitlements. В этом режиме iOS не кэширует AASA и запрашивает файл напрямую с сервера — удобно при разработке.
Как проверить, что AASA-файл корректен?
Для проверки выполните следующие шаги:
- Выполните
curl -v https://example.com/.well-known/apple-app-site-association. ОжидайтеHTTP/1.1 200 OKиContent-Type: application/json. - Используйте AASA Validator от Apple (встроен в Apple Developer). Apple Developer Documentation рекомендует этот инструмент.
- На Mac откройте Console.app, отфильтруйте по
swcd— увидите логи загрузки AASA. - На iOS: в Safari введите ссылку, после открытия приложения проверьте логи через устройство.
Типовые проблемы при настройке
Часто разработчики сталкиваются с тем, что ссылка открывает сайт вместо приложения. Причина — AASA-файл недоступен или неверен: сервер отдаёт редирект или неправильный формат. Решение — удалить редиректы и проверить соответствие формата iOS 13+. Другая проблема — universal link не обрабатывается из-за отсутствия entitlement com.apple.developer.associated-domains в целевом таргете. Третья — AASA-файл не обновляется из-за кэширования Apple (до 24 часов). Для ускорения используйте developer mode.
Сценарии и edge-cases
Несколько доменов. Приложение может обрабатывать до 5 доменов — просто добавляем несколько записей в entitlements. AASA нужен на каждом домене отдельно.
Ссылки из email-клиентов. Gmail и Outlook в приложениях на iOS оборачивают ссылки через свой redirect-сервис. Universal link в этом случае не срабатывает — Apple видит redirect URL, а не целевой. Это ограничение платформы, не баг в реализации.
Что входит в работу
- Настройка AASA-файла на сервере с нужными паттернами путей
- Entitlements и конфигурация в Xcode для всех таргетов и схем (Debug, Release, Staging)
- Реализация обработчика в
SceneDelegate/AppDelegateс роутингом на нужные экраны - Тестирование на реальных устройствах и через симулятор
- Проверка через Apple's validator и логи swcd
- Гарантия корректной работы на iOS 14+ (проверено на 15+ проектах)
Свяжитесь с нами для обсуждения вашего проекта. Закажите настройку под ключ и получите консультацию инженера с опытом более 5 лет.
Сроки
Реализация с несколькими паттернами путей и интеграцией в существующую навигацию: от 1 до 2 дней. С поддержкой нескольких доменов и кастомной логикой роутинга — от 2 до 3 дней. Стоимость рассчитывается индивидуально.
Получите консультацию инженера — мы поможем разобраться с вашим проектом.