Создавайте глубокие ссылки

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

В этом руководстве объясняется, как работают глубокие ссылки, а также как создавать и тестировать глубокие ссылки на ваш контент.

Для глубоких ссылок, ссылающихся на ваш собственный веб-сайт или домены, мы рекомендуем использовать App Links, которые обеспечивают бесперебойный и надежный опыт для ваших пользователей.

Как работают глубокие ссылки

Диплинкинг — это общая системная возможность Android, поддерживаемая во всех версиях и на всех устройствах. Он использует систему намерений Android для перенаправления диплинков к соответствующим приложениям. Приложения, которым требуется обрабатывать определённый URI диплинка, объявляют соответствующий фильтр намерений в файлах манифеста своего приложения.

Во время выполнения, когда пользователь нажимает на ссылку, Android активирует намерение и пытается направить его приложению. Поскольку несколько приложений могут объявлять фильтры намерений, соответствующие заданному URI, Android выполняет следующие действия в указанном порядке для направления намерения:

  1. Откройте приложение пользователя по умолчанию, которое может обрабатывать URI, если таковое было назначено.
  2. Откройте единственное доступное приложение, которое может обрабатывать URI.
  3. Разрешить пользователю выбирать приложение из диалогового окна устранения неоднозначности .

Это означает, что даже если ваши фильтры намерений соответствуют заданному URI, нет гарантии, что система направит намерение по глубинной ссылке в ваше приложение. Пользователь играет ключевую роль в выборе приложения, обрабатывающего намерение, что даёт ему контроль и возможность выбора. Для большего контроля над глубинными ссылками на ваш собственный веб-сайт и домены попробуйте использовать App Links.

Диалоговое окно устранения неоднозначности Android позволяет пользователю увидеть все установленные приложения, зарегистрированные для обработки намерения «глубокая ссылка». Пользователь также может выбрать приложение по умолчанию для этого типа ссылки. После установки приложения по умолчанию система перестает отображать диалоговое окно для данного намерения, и выбранное приложение открывается автоматически.

Рисунок 1. Диалог разрешения неоднозначностей

Поведение диалогового окна разрешения неоднозначности изменилось в разных версиях Android. Например, в Android 12 и более поздних версиях веб-ссылки, не прошедшие проверку App Links, обычно по умолчанию открываются в веб-браузере, тогда как в предыдущих версиях диалоговое окно разрешения неоднозначности могло появиться, если приложение могло обработать веб-ссылку.

Примечание : Начиная с Android 12 (уровень API 31), общее веб-намерение преобразуется в активность в вашем приложении только в том случае, если ваше приложение одобрено для домена, указанного в этом веб-намерении. Если ваше приложение не одобрено для домена, веб-намерение преобразуется в приложение браузера пользователя по умолчанию.

Типы глубоких ссылок

На Android поддерживается поддержка трех типов глубоких ссылок:

  • Пользовательские глубокие ссылки : это глубокие ссылки, использующие пользовательскую схему URI (например example://products/123 ), которые перенаправляют пользователя непосредственно к определённому контенту в приложении. Они эффективны для внутренней навигации или ссылок из контролируемых вами источников, но не являются стандартными веб-ссылками и могут вызывать диалоговое окно устранения неоднозначности, если другое приложение регистрирует ту же пользовательскую схему.
  • Веб-ссылки : это глубокие ссылки, использующие стандартные протоколы http и https . Они более универсальны, поскольку представляют собой стандартные URL-адреса, но на Android 12 и более поздних версиях они почти всегда вызывают диалоговое окно разрешения неоднозначности, а значит, скорее всего, будут обрабатываться веб-браузером пользователя по умолчанию, а не перенаправляться в ваше приложение.
  • Ссылки приложений : доступны начиная с Android 6.0 (API уровня 23) и представляют собой проверенные веб-ссылки. С помощью процесса связывания с веб-сайтом вы можете подтвердить системе Android, что являетесь владельцем домена. После проверки система автоматически направляет ссылки для этого домена непосредственно в ваше приложение, полностью минуя диалоговое окно разрешения неоднозначности. Это обеспечивает надёжный и бесперебойный интерфейс для ваших пользователей.

Добавить фильтры намерений для входящих ссылок

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

<action>

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

<data>

Добавьте один или несколько тегов <data> , каждый из которых представляет собой формат URI, соответствующий активности. Тег <data> должен как минимум включать атрибут android:scheme .

Вы можете добавить дополнительные атрибуты для уточнения типа URI, принимаемого действием. Например, у вас может быть несколько действий, принимающих похожие URI, но различающихся только именем пути. В этом случае используйте атрибут android:path или его варианты pathPattern или pathPrefix , чтобы различать, какие действия система должна открывать для разных путей URI.

<category>

Добавьте категорию BROWSABLE . Она необходима для доступа к фильтру намерений из веб-браузера. Без неё нажатие на ссылку в браузере не сможет открыть ваше приложение.

Также включите категорию DEFAULT . Это позволит вашему приложению реагировать на неявные намерения. Без неё действие может быть запущено только в том случае, если в намерении указано имя компонента вашего приложения.

Следующий фрагмент XML показывает, как можно указать фильтр намерений в манифесте для диплинкинга. URI "example://gizmos" и "http://www.example.com/gizmos" оба ведут к этому действию.

<activity
    android:name="com.example.android.GizmosActivity"
    android:label="@string/title_gizmos" >
    <intent-filter android:label="@string/filter_view_http_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "http://www.example.com/gizmos” -->
        <data android:scheme="http"
              android:host="www.example.com"
              android:pathPrefix="/gizmos" />
        <!-- note that the leading "/" is required for pathPrefix-->
    </intent-filter>
    <intent-filter android:label="@string/filter_view_example_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "example://gizmos” -->
        <data android:scheme="example"
              android:host="gizmos" />
    </intent-filter>
</activity>

Обратите внимание, что два фильтра намерений отличаются только элементом <data> . Хотя в один фильтр можно включить несколько элементов <data> , важно создавать отдельные фильтры, если вы хотите объявить уникальные URL-адреса (например, определённую комбинацию scheme и host ), поскольку несколько элементов <data> в одном фильтре намерений фактически объединяются для учёта всех вариаций их объединённых атрибутов. Например, рассмотрим следующий пример:

<intent-filter>
  ...
  <data android:scheme="https" android:host="www.example.com" />
  <data android:scheme="app" android:host="open.my.app" />
</intent-filter>

Может показаться, что поддерживаются только https://www.example.com и app://open.my.app . Однако на самом деле поддерживаются эти два адреса, а также app://www.example.com и https://open.my.app .

Внимание : если несколько действий содержат фильтры намерений, которые приводят к одной и той же проверенной ссылке на приложение Android, то нет никаких гарантий, какое действие обрабатывает ссылку.

После добавления фильтров намерений с URI для содержимого активности в манифест приложения Android сможет направлять любые Intent , имеющие соответствующие URI, в ваше приложение во время выполнения.

Дополнительную информацию об определении фильтров намерений см. в разделе Разрешить другим приложениям запускать вашу активность .

Чтение данных из входящих намерений

После того, как система запустит вашу активность через фильтр намерений, вы можете использовать данные, предоставленные Intent , чтобы определить, что именно нужно отрисовать. Вызовите методы getData() и getAction() для получения данных и действий, связанных с входящим Intent . Вы можете вызывать эти методы в любой момент жизненного цикла активности, но обычно это следует делать во время ранних обратных вызовов, таких как onCreate() или onStart .

Вот фрагмент, показывающий, как извлечь данные из Intent :

Котлин 

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    val action: String? = intent?.action
    val data: Uri? = intent?.data
}

Ява 

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent = getIntent();
    String action = intent.getAction();
    Uri data = intent.getData();
}

Чтобы улучшить пользовательский опыт, следуйте этим рекомендациям:

  • Глубокая ссылка должна перенаправлять пользователей непосредственно к контенту, без каких-либо подсказок, промежуточных страниц или входа в систему. Убедитесь, что пользователи видят контент приложения, даже если они никогда ранее его не открывали. Допустимо отображать подсказки при последующих взаимодействиях или при открытии приложения из панели запуска.
  • Следуйте рекомендациям по дизайну, описанным в разделе «Навигация с кнопками «Назад» и «Вверх» , чтобы ваше приложение соответствовало ожиданиям пользователей относительно обратной навигации после того, как они перешли в ваше приложение по глубинной ссылке.

Проверьте свои глубокие ссылки

Вы можете использовать Android Debug Bridge с инструментом Activity Manager (am), чтобы проверить, что URI фильтра намерений, указанные для диплинкинга, соответствуют правильной активности приложения. Вы можете запустить команду adb на устройстве или эмуляторе.

Общий синтаксис для тестирования URI фильтра намерений с помощью adb:

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d <URI> <PACKAGE>

Например, следующая команда пытается просмотреть целевую активность приложения, связанную с указанным URI.

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d "example://gizmos" com.example.android

Примечание : при определении коллекции примитивных типов в маршруте, например **@Serializable data class Product(val colors: List)** , автоматически генерируемый формат URL-адреса глубокой ссылки — **basePath?colors={value**} . При попытке указать URI с несколькими параметрами запроса (например, **basepath?colors=red&colors=blue** ) необходимо экранировать амперсанд (например, **basepath?colors=red\&colors=blue** ).

Объявление манифеста и заданный вами обработчик намерений определяют соединение между вашим приложением и веб-сайтом, а также действия с входящими ссылками. Однако, чтобы система рассматривала ваше приложение как обработчик по умолчанию для набора URI, необходимо также запросить у системы проверку этого соединения. В разделе «Проверка ссылок приложений» объясняется, как реализовать эту проверку.

Дополнительную информацию о намерениях и ссылках приложений можно найти в следующих ресурсах: