Коды ошибок Universal Links и App Links: что они значат

Сначала убедитесь, что всё действительно сломано

Многие жалобы «Universal Links не работают» на деле описывают ссылки, которые ведут себя ровно так, как задумала Apple. В техническом документе TN3155 Apple перечисляет случаи, когда приложение и не должно открываться: URL, набранный или вставленный в адресную строку Safari, — это прямая навигация, и браузер оставляет его себе. Ссылка на тот же домен, что и текущая страница, тоже остаётся в браузере. А сторонние браузеры, включая встроенные в другие приложения, сами решают, передавать ли ссылку вашему приложению.

Поэтому сначала проверьте честно и только потом трогайте файлы. Вставьте ссылку в Заметки на iPhone и долго нажмите на неё. Если всё настроено правильно, меню предложит открыть её не только в браузере, но и в вашем приложении. Что пользователь выберет в этом меню, станет поведением по умолчанию для домена — ещё одна незаметная причина, по которой ссылка, работавшая вчера, сегодня открывает Safari.

Если Заметки не предлагают приложение, проблема в связке с доменом, и код ошибки подскажет, в чём именно.

Короткий путь: бесплатный валидатор Appy

Прежде чем открывать терминал, вставьте свой домен в валидатор Universal Links от Appy. Он загружает файл apple-app-site-association отдельно с вашего сервера и из CDN Apple, так что вы сразу видите, тот ли файл у Apple, что и у вас. Заодно он спрашивает у Digital Asset Links API от Google, что Android читает из вашего assetlinks.json. Бесплатно, без регистрации, а результат умещается на одной странице, которую можно сразу переслать разработчикам.

Если проблема в самих файлах, генератор AASA и assetlinks.json от Appy соберёт оба по вашему Team ID, bundle ID и отпечатку SHA-256. Дальше в руководстве разобрана каждая ошибка, так что, когда валидатор её покажет, вы будете точно знать, что исправлять.

Спросите у CDN Apple, что у него есть

Начиная с iOS 14 телефоны никогда не скачивают файл apple-app-site-association с вашего сервера. Они получают его из CDN Apple, а CDN забирает его у вас. Поэтому первый вопрос не «правильный ли у меня файл?», а «что есть у Apple?».

curl -sD - "https://app-site-association.cdn-apple.com/a/v1/links.example.com" -o /dev/null

HTTP/1.1 404 Not Found
Apple-Failure-Reason: SWCERR00101 Bad HTTP Response: 404 Not Found
Cache-Control: max-age=3600,public

curl -v -A "AASA-Bot/1.0" https://links.example.com/.well-known/apple-app-site-association

Коды SWCERR и как их исправить

Apple не публикует список этих кодов. Ниже — сообщения, которые CDN Apple возвращает в заголовке Apple-Failure-Reason; каждое подтверждено в обсуждениях на Apple Developer Forums или нашими собственными запросами к CDN.

Проверьте пути через swcutil

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

sudo swcutil dl -d links.example.com

sudo swcutil verify -d links.example.com -j ./apple-app-site-association -u https://links.example.com/promo

{ s = applinks, a = ABCD123.com.example.app, d = links.example.com }:
Pattern "https://links.example.com/promo" matched.

Что думает сам телефон

Если включён режим разработчика, в разделе Настройки › Для разработчиков › Universal Links есть экран Diagnostics: введите полный URL, и он покажет, заявляет ли на него права какое-нибудь установленное приложение. Чтобы увидеть всю картину, снимите sysdiagnose и откройте swcutil_show.txt. Найдите ID своего приложения и прочитайте три строки.

В Site/Fmwk Approval должно стоять approved. Unspecified или denied значит, что телефон так и не получил одобренный файл для этого приложения и домена: проверьте entitlement, публичный доступ и префикс Team ID. User Approval показывает, выбрал ли человек браузер для этого домена. Last Checked и Next Check показывают, когда Apple в последний раз забирала ваш файл.

Последний пункт объясняет большинство ситуаций «я всё починил, а ничего не изменилось». После установки телефон перепроверяет файл примерно раз в неделю. Чтобы проверить исправление сразу, переустановите приложение. Для staging добавьте ?mode=developer к записи applinks: так CDN пропускается, но только для сборок с подписью разработчика и только на устройствах, где вы это включили.

Цифры, которые стоит запомнить

столько CDN Apple хранил рабочий файл в наших тестах

6 ч

столько CDN Apple хранил рабочий файл в наших тестах

столько он хранил ошибку

1 ч

столько он хранил ошибку

как часто iPhone перепроверяет файл после установки

~1 неделя

как часто iPhone перепроверяет файл после установки

минимальное ожидание на Android перед проверкой верификации

20 с

минимальное ожидание на Android перед проверкой верификации

Android App Links: какие состояния показывает pm get-app-links

На Android посредника в виде CDN нет. Верификатор на устройстве сам загружает https://your-host/.well-known/assetlinks.json, и начиная с Android 12 непроверенная ссылка больше не показывает окно выбора: она просто открывается в браузере. Поэтому пропущенный отпечаток выглядит ровно как «ссылка работает, только не в моём приложении».

В Android 12 изменилась и проверка нескольких хостов. Теперь каждый хост проверяется отдельно; на Android 11 и ниже, если один хост не прошёл верификацию, не проходят все. А на Android 15 изменение в assetlinks.json может доходить до всех устройств до семи дней.

Перезапустите верификацию с ноутбука

adb shell pm set-app-links --package com.example.app 0 all
adb shell pm verify-app-links --re-verify com.example.app
adb shell pm get-app-links com.example.app

example.com: verified
sub.example.com: legacy_failure
example.org: 1026

Что означает каждое состояние

Отпечаток, который верен на ноутбуке и неверен в Play Store

Самая частая поломка на Android вообще не связана с хостингом. При Play App Signing Google заново подписывает ваше приложение своим ключом подписи. SHA-256, который keytool выдаёт для вашего ключа загрузки, — не тот, что стоит на телефонах пользователей, поэтому релизная сборка не проходит, а локальная проходит.

Берите отпечаток в Play Console › Release › Setup › App signing. Массив sha256_cert_fingerprints принимает несколько значений, так что оставьте там и отладочный ключ, в верхнем регистре. И помните: редирект с example.com на www.example.com или с http на https означает, что Android не подтвердит ни одну вашу ссылку.

Посмотрите, что Google читает из вашего файла

curl "https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://example.com&relation=delegate_permission/common.handle_all_urls"

Пока вы чините, кампании работают

Сломанные файлы связки не должны стоить вам установок. Ссылка Appy на любом тарифе отправляет каждый телефон в нужный стор, включая Huawei AppGallery, а на Pro сначала пробует открыть ваше приложение, так что те, у кого оно уже есть, попадают прямо в него. Без файла AASA, без SDK, без нового релиза. Когда Universal Links снова заработают, оставьте ту же ссылку Appy: напечатанные коды и посты менять не придётся.

Что почитать дальше

• Валидатор Universal LinksЗа один раз проверяет ваш AASA на вашем сервере и в CDN Apple, а заодно assetlinks.json.
• Генератор AASA и assetlinks.jsonСоздаёт оба файла по Team ID, bundle ID и SHA-256.
• Universal Links открывают Safari вместо приложенияПричины на уровне поведения: от правила одного домена до выбора пользователя.
• Android App Links не проходят верификациюПодробный разбор Android-стороны.

Вопросы о кодах ошибок