Глубокие ссылки

1Что такое глубокие ссылки?#

Глубокие ссылки позволяют внешним источникам (браузерам, SMS, письмам, соцсетям, push-уведомлениям, QR-кодам) открывать ваше приложение сразу на нужной странице, а не на главной.

Ваше приложение поддерживает два вида ссылок, и настроить их НЕ одинаково просто:

1. ⚡ Собственная схема (myapp://path) — работает сразу, ничего настраивать не нужно. Лучше всего подходит для push-уведомлений и QR-кодов.

1. 🌐 Ссылки https:// (https://mysite.com/page) — нужно загрузить ОДИН файл на ваш сайт. Без него Android оставляет ссылку в браузере, и ваше приложение не открывается. Это самая частая причина, по которой глубокие ссылки «не работают».

Обе описаны ниже. Если вам нужно что-то рабочее уже сегодня, используйте собственную схему.

2Как работают URL с собственной схемой#

Когда нажимают на ссылку с собственной схемой (например, myapp://products/shoes), приложение:

1. Получает URL с собственной схемой
2. Автоматически сопоставляет его с URL вашего сайта
3. Открывает WebView на нужной странице

✅ Схема берётся из названия вашего приложения (строчные буквы, только буквы).

✅ Пример соответствия:
myapp://products/shoes
→ https://mysite.com/products/shoes

Части пути после схемы сохраняются и добавляются к домену вашего сайта.

Custom scheme format:
  <appname>://<path>

Examples:
  myshop://cart
  → https://myshop.com/cart

  puma://in/en/help
  → https://in.puma.com/in/en/help

3Ссылки https:// — на ваш сайт нужно загрузить один файл#

Этот момент часто упускают, поэтому прочитайте его до тестирования.

AppMint автоматически добавляет ваш домен в приложение. Но Android НЕ откроет ваше приложение по ссылке https://, пока ваш САЙТ не докажет, что приложение принадлежит вам. На Android 12 и новее непроверенная ссылка просто открывает браузер — без диалога и выбора. Поэтому ссылка может выглядеть так, будто «ничего не делает».

Доказательство — один небольшой файл. AppMint уже создал его для вас: после сборки ищите assetlinks.json в папке «Загрузки». В нём указаны имя пакета и отпечаток подписи вашего приложения.

Загрузите его на свой сайт РОВНО по этому адресу (имя папки начинается с точки):

https://yoursite.com/.well-known/assetlinks.json

Rules — all four must be true:
  1. Served over https (not http)
  2. Content-Type: application/json
  3. NO redirect (a redirect to www breaks it)
  4. Reachable publicly — no login, no Cloudflare challenge

Check it from any computer:
  curl -i https://yoursite.com/.well-known/assetlinks.json

4Публикуете в Google Play? Используйте отпечаток Play#

Google Play переподписывает ваше приложение СВОИМ ключом. Поэтому отпечаток в assetlinks.json, созданном AppMint, — а это ваш локальный ключ — не совпадёт с тем, что пользователи реально устанавливают из Play.

Если вы публикуетесь в Google Play, замените отпечаток:

1. Play Console → ваше приложение → Test and release → Setup → App integrity
2. Скопируйте SHA-256 из «App signing key certificate»
3. Поместите это значение в assetlinks.json и загрузите файл заново

В одном файле можно указать ОБА отпечатка: локальный — для APK, которые вы раздаёте напрямую, и отпечаток Play — для установок из Play. Тогда работает и то, и другое.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourapp.name",
    "sha256_cert_fingerprints": [
      "AA:BB:...",   // your local key (direct APK)
      "11:22:..."    // Play App Signing key
    ]
  }
}]

5Проверьте, принял ли Android ссылку#

После загрузки файла ПЕРЕУСТАНОВИТЕ приложение (Android проверяет только при установке, и это может занять минуту).

Команда ниже скажет вам правду. Найдите свой домен со статусом «verified». Если там «legacy_failure» или домена нет, файл читается неправильно — вернитесь и проверьте четыре правила.

# Does Android consider your domain verified?
adb shell pm get-app-links com.yourapp.name

# Force a re-check without reinstalling (Android 12+):
adb shell pm verify-app-links --re-verify com.yourapp.name

# Google's own checker (open in a browser):
https://digitalassetlinks.googleapis.com/v1/statements:list?
  source.web.site=https://yoursite.com&
  relation=delegate_permission/common.handle_all_urls

6Почему обычно не работает#

В порядке убывания частоты причин:

1. Файл не загружен или лежит не по тому пути. Он должен быть по адресу /.well-known/assetlinks.json — с точкой.

1. www и без www. Android считает https://example.com и https://www.example.com РАЗНЫМИ доменами. AppMint регистрирует именно тот хост, что указан в URL вашего сайта. Если используете оба, разместите файл на обоих и сообщите нам, какой хост вы указали.

1. Перенаправление. Многие хостинги перенаправляют основной домен на www. Это ломает проверку, хотя файл в браузере открывается.

1. Опубликовано в Play, но используется локальный отпечаток — см. предыдущий шаг.

1. Приложение не переустановлено после загрузки файла. Android проверяет при установке.

Ссылкам с собственной схемой (myapp://...) всё это НЕ нужно, и они работают всегда — используйте их для push-уведомлений и QR-кодов, если хотите получить рабочий результат уже сегодня.

7Проверка глубоких ссылок через ADB#

Проверьте глубокие ссылки с компьютера, подключённого по отладке USB:

1. Включите отладку по USB на телефоне
2. Подключитесь по USB
3. Выполните команды ниже.

⚠️ Важно: «am start» со ссылкой https может открыть ваше приложение, даже когда проверка НЕ пройдена, потому что вы передаёте ссылку прямо в Android. Это не доказывает, что настоящее нажатие в Gmail или Chrome сработает. Это показывает только «pm get-app-links» (предыдущий шаг). Используйте am start, чтобы проверить маршрутизацию ВАШЕЙ СТРАНИЦЫ, а не настройку домена.

# Test custom scheme:
adb shell am start -a android.intent.action.VIEW \
  -d "myapp://some/page"

# Test website URL:
adb shell am start -a android.intent.action.VIEW \
  -d "https://mysite.com/some/page"

# Verify which app handles it:
adb shell cmd package resolve-activity --brief \
  -a android.intent.action.VIEW \
  -d "myapp://some/page"

8Глубокие ссылки в push-уведомлениях#

При отправке push-уведомления через OneSignal вставьте любой URL глубокой ссылки в поле «Launch URL». Приложение откроется и сразу перейдёт на эту страницу.

Работают оба типа URL:
✅ https://mysite.com/flash-sale
✅ myapp://flash-sale

OneSignal Dashboard → New Push:

Launch URL: https://mysite.com/flash-sale
  OR
Launch URL: myapp://flash-sale

Both will open the app on the sale page.

9Важно: поведение при тёплом запуске#

Если ваше приложение уже работает в фоне, когда срабатывает глубокая ссылка, Android передаёт ссылку напрямую, не перезапуская приложение, — это называется «тёплый запуск».

✅ Ваше приложение обрабатывает это автоматически. WebView перейдёт на новую страницу, даже если приложение уже открыто.

⚠️ Если глубокие ссылки открывают только главную страницу, проверьте, что:

• URL вашего сайта в конфигурации совпадает с доменом в глубокой ссылке
• Путь в URL с собственной схемой указан верно

⚠️ Если ссылки https:// вообще НЕ открывают приложение, это не проблема тёплого запуска — дело в шаге с assetlinks.json выше. Классический признак: ссылки с собственной схемой работают, а ссылки https ничего не делают.

Warm launch works automatically.
No extra setup needed.