Создавайте глубокие ссылки на контент приложения

Когда нажатая ссылка или программный запрос вызывают намерение веб-URI, система Android пытается выполнить каждое из следующих действий последовательно, пока запрос не будет выполнен успешно:

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

Следуйте инструкциям ниже, чтобы создать и протестировать ссылки на свой контент. Вы также можете использовать помощник App Links в Android Studio для добавления ссылок на приложения Android.

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

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

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

<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

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

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

• Намерения и фильтры намерений
• Разрешите другим приложениям запускать вашу активность
• Добавьте ссылки на приложения Android с помощью Android Studio

Когда нажатая ссылка или программный запрос вызывают намерение веб-URI, система Android пытается выполнить каждое из следующих действий последовательно, пока запрос не будет выполнен успешно:

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

Следуйте инструкциям ниже, чтобы создать и протестировать ссылки на свой контент. Вы также можете использовать помощник App Links в Android Studio для добавления ссылок на приложения Android.

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

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

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

<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

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

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

• Намерения и фильтры намерений
• Разрешите другим приложениям запускать вашу активность
• Добавьте ссылки на приложения Android с помощью Android Studio