Установлено ли ваше приложение? API Get Install Related Apps вам подскажет!

Пит ЛеПейдж
Алексей Родионов
Alexey Rodionov
X GitHub LinkedIn

API Get Installed Related Apps позволяет получить список установленных связанных приложений, а также подробную информацию о них.

Это позволяет проверить, установлено ли ваше прогрессивное веб-приложение (PWA), приложение для Android или приложение для универсальной платформы Windows (UWP) на текущем устройстве, как из самого PWA, так и со страницы соответствующего веб-сайта (например, сайта маркетинга продукта).

Если приложение уже установлено, вы можете настроить пользовательский интерфейс.

Например:

  • Не предлагайте установить ваше PWA-приложение, если другое ваше приложение уже установлено.
  • Перенаправление пользователя с сайта, посвященного маркетингу продукта, непосредственно в ваше приложение.
  • Централизация некоторых функций, таких как уведомления, в другом приложении для предотвращения дублирования уведомлений.

Что такое API для получения информации об установленных связанных приложениях?

Вызов асинхронного метода navigator.getInstalledRelatedApps() возвращает промис, который разрешается массивом объектов, содержащих подробную информацию о следующих приложениях:

  • установлено на текущем устройстве,
  • определяется в поле related_applications манифеста веб-приложения.
  • имеет подтвержденную связь со страницей, где вызывается метод navigator.getInstalledRelatedApps() (подробности см. в следующих разделах). 
const installedRelatedApps = await navigator.getInstalledRelatedApps?.();

Вызов функции console.log(installedRelatedApps) возвращает примерно следующий результат:

[
  {
    platform: "webapp",
    id: "https://example.com/?utm_source=home_screen",
    url: "https://example.com/manifest.json"
  },
  {
    platform: "play",
    id: "com.example.twa",
    url: "https://play.google.com/store/apps/details?id=com.example.twa",
    version: "0.1.0"
  }
]

Например, чтобы проверить, установлены ли на устройстве пользователя какие-либо связанные приложения, можно использовать следующую однострочную команду:

const hasInstalledRelatedApps = !!(await navigator.getInstalledRelatedApps?.())?.length;

Если вам известен идентификатор пакета, то для получения номера версии установленного соответствующего Android-приложения можно использовать следующую однострочную команду:

const installedRelatedAndroidAppVersion = (await navigator.getInstalledRelatedApps?.())?.find(app => app.id === 'com.example.twa')?.version;

Поддерживаемые типы приложений, которые вы можете проверить.

тип приложения Проверяется с
Приложение для Android Только для Android:
Chrome 80 или более поздняя версия
Приложение для универсальной платформы Windows (UWP) Только для Windows:
Chrome 85 или более поздняя версия
Edge 85 или более поздняя версия
Прогрессивное веб-приложение (PWA), установленное в той же области видимости на том же источнике. Android:
Chrome 84 или более поздняя версия
Настольные приложения (Windows, macOS, Linux, ChromeOS):
Chrome 140 или более поздняя версия
Edge 140 или более поздняя версия
Прогрессивное веб-приложение (PWA)
установлен в разных областях, но по одному и тому же или различному происхождению		 Только для Android:
Chrome 84 или более поздняя версия

Проверьте, установлено ли ваше приложение для Android.

Ваш веб-сайт может проверить, установлено ли ваше приложение для Android.

Поддерживается на:

  • Только для Android: Chrome 80 или более поздняя версия.

Расскажите своему Android-приложению о вашем веб-сайте

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

В файл AndroidManifest.xml вашего Android-приложения добавьте запись asset_statements :

<manifest>
  <application>
   …
    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
   …
  </application>
</manifest>

Затем в strings.xml добавьте следующее выражение asset, заменив site на ваш домен. Обязательно укажите символы экранирования.

<string name="asset_statements">
  [
    {
      \"relation\": [\"delegate_permission/common.handle_all_urls\"],
      \"target\": {
        \"namespace\": \"web\",
        \"site\": \"https://example.com\"
      }
    }
  ]
</string>

Полезный совет: это массив. Это означает, что вы можете определить проверенную связь между вашим Android-приложением и несколькими вашими веб-сайтами.

После завершения установите обновленное приложение на устройство или опубликуйте его в Google Play Store или на любой другой платформе распространения приложений для Android.

Расскажите своему сайту о своем приложении для Android.

Далее, сообщите своему веб-сайту о вашем Android-приложении , добавив на страницу манифест веб-приложения . Манифест должен включать свойство related_applications , массив, содержащий подробную информацию о вашем приложении, включая platform и id .

  • platform должна быть play
  • id — это идентификатор пакета Android. 
{
  ...
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.twa"
    }
  ]
  ...
}

Полезный совет: это массив. Это означает, что вы можете определить проверенную связь между вашим веб-сайтом и несколькими вашими приложениями для Android.

Проверьте, установлено ли ваше приложение.

Наконец, вызовите асинхронную функцию navigator.getInstalledRelatedApps() , чтобы проверить, установлено ли ваше приложение для Android.

Проверьте, установлено ли ваше приложение для Windows (UWP).

Ваш веб-сайт может проверить, установлено ли ваше приложение для Windows (созданное с использованием UWP).

Поддерживается на:

  • Только для Windows: Chrome 85 или более поздняя версия, Edge 85 или более поздняя версия.

Расскажите своему приложению для Windows о вашем веб-сайте

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

Добавьте регистрацию расширения Windows.appUriHandler в файл манифеста вашего приложения AppxManifest.xml или Package.appxmanifest . Например, если адрес вашего веб-сайта — example.com , вам следует добавить следующую запись в манифест вашего приложения:

<Applications>
  <Application Id="App" ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="example.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

Обратите внимание, что вам может потребоваться добавить пространство имен uap3 в атрибут <Package> .

Если у вашего веб-сайта несколько адресов, добавьте отдельную запись <uap3:Host Name=... /> внутри <uap3:AppUriHandler> для каждого адреса.

Затем создайте JSON-файл (без расширения .json ) с именем windows-app-web-link и укажите имя семейства пакетов вашего приложения. Разместите этот файл либо в каталоге /.well-known/ , либо в корневом каталоге вашего сервера.

[
  {
    "packageFamilyName": "MyApp_9jmtgj1pbbz6e",
    "paths": [ "*" ]
  }
]

Полезный совет: это массив. Это означает, что вы можете определить проверенную связь между вашим веб-сайтом и несколькими вашими приложениями для Windows.

Чтобы определить название семейства пакетов, вы можете установить приложение, выполнить следующую команду в PowerShell и найти свое приложение в списке: 

Get-AppxPackage | Select-Object PackageFamilyName

Подробную информацию о настройке обработчиков URI см. в разделе «Включение приложений для веб-сайтов с использованием обработчиков URI приложений» .

Расскажите своему сайту о вашем приложении для Windows.

Далее, сообщите своему веб-сайту о вашем приложении для Windows, добавив на страницу манифест веб-приложения . Манифест должен включать свойство related_applications , массив, содержащий подробную информацию о вашем приложении, включая platform и id .

  • platform должна быть windows
  • id — это имя семейства пакетов вашего приложения с добавлением !App в качестве суффикса в конце. 
{
  ...
  "related_applications": [
    {
      "platform": "windows",
      "id": "MyApp_9jmtgj1pbbz6e!App"
    }
  ]
  ...
}

Полезный совет: это массив. Это означает, что вы можете определить проверенную связь между вашим веб-сайтом и несколькими вашими приложениями для Windows.

Проверьте, установлено ли ваше приложение.

Наконец, вызовите асинхронную функцию navigator.getInstalledRelatedApps() , чтобы проверить, установлено ли ваше приложение для Windows.

Посмотрите эту демонстрацию .

Проверьте, установлено ли ваше прогрессивное веб-приложение (входит ли оно в область действия)?

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

Поддерживается на:

  • Android: Chrome 84 или более поздняя версия.
  • Настольные приложения (Windows, macOS, Linux, ChromeOS): Chrome 140 или более поздняя версия, Edge 140 или более поздняя версия.

Расскажите своему PWA о себе

Чтобы сообщить своему PWA о себе, добавьте запись related_applications в манифест веб-приложения .

  • platform должна быть webapp
  • url — это путь (может быть относительным) к файлу манифеста веб-приложения вашего PWA.
  • id это идентификатор веб-приложения, указанный в поле id манифеста веб-приложения или вычисленный браузером (обязательно для настольных компьютеров, не требуется для Android). 
{
  ...
  "scope": "/",
  "start_url": "/?utm_source=home_screen",
  "related_applications": [
    {
      "platform": "webapp",
      "url": "/manifest.json",
      "id": "https://example.com/?utm_source=home_screen"
    }
  ],
  ...
}

Проверьте, установлено ли у вас PWA.

Наконец, вызовите асинхронную функцию navigator.getInstalledRelatedApps() из области видимости вашего PWA, чтобы проверить, установлено ли приложение. Если navigator.getInstalledRelatedApps() вызывается вне области видимости вашего PWA, она вернет [] . Подробности см. в следующем разделе.

Проверьте, установлено ли ваше прогрессивное веб-приложение (не входит в область действия).

Ваш веб-сайт может проверить, установлено ли ваше PWA, даже если страница находится вне области действия вашего PWA. Например, целевая страница, размещенная по адресу /landing/ может проверить, установлено ли PWA, размещенное по адресу /pwa/ , или если ваша целевая страница размещена по адресу www.example.com , а ваше PWA — по адресу app.example.com .

Поддерживается на:

  • Только для Android: Chrome 84 или более поздняя версия.

Расскажите своему PWA о вашем веб-сайте.

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

Добавьте файл assetlinks.json в каталог /.well-known/ домена, где размещено PWA, например, app.example.com . В свойстве site укажите полный путь к манифесту веб-приложения, который будет выполнять проверку (а не к манифесту вашего PWA). 

// Served from https://app.example.com/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.query_webapk"],
    "target": {
      "namespace": "web",
      "site": "https://www.example.com/manifest.json"
    }
  }
]

Полезный совет: это массив. Это означает, что вы можете определить подтвержденную связь между вашим PWA и несколькими вашими веб-сайтами.

Расскажите своему сайту о вашем PWA.

Далее, сообщите своему веб-сайту о вашем PWA-приложении , добавив на страницу манифест веб-приложения . Манифест должен включать свойство related_applications , массив, содержащий подробную информацию о вашем PWA, включая platform и url .

  • platform должна быть webapp
  • url — это полный путь к файлу манифеста веб-приложения вашего PWA. 
{
  ...
  "related_applications": [
    {
      "platform": "webapp",
      "url": "https://app.example.com/manifest.json"
    }
  ]
  ...
}

Полезный совет: это массив. Это означает, что вы можете определить подтвержденную связь между вашим веб-сайтом и несколькими вашими PWA.

Проверьте, установлено ли у вас PWA.

Наконец, вызовите асинхронную функцию navigator.getInstalledRelatedApps() , чтобы проверить, установлено ли ваше PWA.

Остались вопросы?

Остались вопросы? Проверьте тег getInstalledRelatedApps на StackOverflow, чтобы узнать, были ли у кого-нибудь еще похожие вопросы. Если нет, задайте свой вопрос там, обязательно добавив тег progressive-web-apps . Наша команда регулярно отслеживает этот тег и старается отвечать на ваши вопросы.

Обратная связь

Вы обнаружили ошибку в реализации Chrome? Или реализация отличается от спецификации?

  • Сообщите об ошибке на сайте https://new.crbug.com. Укажите как можно больше подробностей, предоставьте инструкции по воспроизведению ошибки и введите Mobile>WebAPKs в поле Components .

Полезные ссылки

Спасибо

Особая благодарность Сунггуку Чу из Microsoft за помощь в проработке деталей тестирования приложений для Windows, а также Райану Кансо за помощь в проработке деталей Chrome.