Konfigurowanie powiązań z witryną i reguł dynamicznych

Aby obsługiwać linki do aplikacji, musisz utworzyć plik JSON Digital Asset Links o nazwie assetlinks.json i opublikować go w znanej lokalizacji w swojej witrynie. Ten plik publicznie deklaruje, które aplikacje są autoryzowane do obsługi linków do Twojej domeny. Urządzenia z Androidem pobierają ten plik z Twojego serwera, aby weryfikować precyzyjne linki.

W przypadku dynamicznych linków aplikacji na Androidzie 15 lub nowszym w pliku assetlinks.json określasz też konfigurację reguł dynamicznych, np. wzorce dopasowywania ścieżki, fragmentu i parametrów zapytania. Urządzenia z Androidem w wersji 15 (poziom interfejsu API 35) lub nowszej, na których zainstalowane są usługi Google, będą okresowo pobierać plik i łączyć konfigurację dynamiczną z konfiguracją statyczną w manifeście aplikacji.

Z tego przewodnika dowiesz się, jak przygotować plik assetlinks.json i opublikować go w swojej witrynie. Jeśli wolisz, możesz wygenerować plik assetlinks.json za pomocą narzędzia Precyzyjne linki w Google Play lub Asystenta linków aplikacji w Android Studio. Więcej informacji znajdziesz w narzędziach dla programistów linków do aplikacji.

Deklarowanie powiązań z witrynami

Musisz opublikować w swojej witrynie plik JSON Digital Asset Links, aby wskazać aplikacje na Androida powiązane z witryną i zweryfikować intencje adresów URL aplikacji. Plik JSON zawiera te pola, które służą do identyfikowania powiązanych aplikacji:

  • package_name: Identyfikator aplikacji zadeklarowany w pliku build.gradle aplikacji.
  • sha256_cert_fingerprints: odciski cyfrowe SHA256 certyfikatu podpisywania aplikacji. Aby wygenerować odcisk palca za pomocą narzędzia Java keytool, możesz użyć tego polecenia:

keytool -list -v -keystore my-release-key.keystore

  • To pole obsługuje wiele odcisków palców, które mogą być używane do obsługi różnych wersji aplikacji, np. wersji debugowania i produkcyjnej. Jeśli w przypadku aplikacji używasz podpisywania aplikacji w Google Play, odcisk certyfikatu wygenerowany lokalnie za pomocą polecenia keytool zwykle nie będzie zgodny z odciskiem na urządzeniach użytkowników. W Konsoli Play na koncie dewelopera możesz sprawdzić, czy używasz podpisywania aplikacji w Google Play. W tym celu otwórz sekcjęRelease > Setup > App signing. Jeśli używasz tej funkcji, na tej samej stronie znajdziesz też prawidłowy fragment kodu JSON Digital Asset Links dla swojej aplikacji.

Ten przykładowy plik assetlinks.json przyznaje uprawnienia do otwierania linków aplikacji na Androida:com.example

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Powiązywanie witryny z wieloma aplikacjami

Witryna może deklarować powiązania z wieloma aplikacjami w tym samym plikuassetlinks.json. Poniżej znajdziesz przykład pliku z instrukcjami, który deklaruje powiązanie z 2 aplikacjami oddzielnie i znajduje się pod adresem https://www.example.com/.well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Różne aplikacje mogą obsługiwać linki do różnych zasobów w ramach tego samego hosta internetowego. Na przykład aplikacja 1 może zadeklarować filtr intencji dla https://example.com/articles, a aplikacja 2 może zadeklarować filtr intencji dla https://example.com/videos.

Powiązywanie wielu witryn z jedną aplikacją

Wiele witryn może deklarować powiązania z tą samą aplikacją w odpowiednich plikach assetlinks.json. Poniższe listy plików pokazują przykład deklarowania powiązania domen example.com i example.net z aplikacją app1. Pierwsza pozycja na liście pokazuje powiązanie domeny example.com z aplikacją app1:

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Kolejna lista pokazuje powiązanie domeny example.net z aplikacją app1. Różni się tylko lokalizacja, w której są hostowane te pliki (.com i .net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Konfigurowanie reguł dynamicznych

Dynamiczne linki aplikacji na Androidzie 15 lub nowszym umożliwiają korzystanie z reguł dopasowywania precyzyjnych linków po stronie serwera, które działają razem z regułami zdefiniowanymi statycznie w pliku manifestu aplikacji. W pliku assetlinks.json określasz reguły dynamiczne. Uwzględnienie tego elementu jest opcjonalne.

Urządzenia z Androidem w wersji 15 (poziom interfejsu API 35) lub nowszej, na których zainstalowane są usługi Google, będą okresowo pobierać ten plik z Twojego serwera i łączyć konfigurację reguł dynamicznych z konfiguracją statyczną w manifeście aplikacji. Oto przykład pliku assetlinks.json z regułami dynamicznymi:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

Najważniejsze informacje o kodzie

  • Dynamiczne linki aplikacji dodają nowe rozszerzenie relacji Digital Asset Links o nazwie dynamic_app_link_components, w którym możesz skonfigurować dynamiczne reguły.
  • Reguły dynamiczne mogą zawierać dopasowania wzorców ścieżki, fragmentu i parametrów zapytania.
  • Możesz też oznaczyć dowolny wzorzec jako wykluczony, aby pasujące adresy URL nie otwierały aplikacji.
  • Ten przykład zawiera przykłady dopasowań ścieżki ("/"), fragmentu ("#") i parametrów zapytania ("?"), a także wykluczonych dopasowań ("exclude").
  • Jeśli którekolwiek z pól w pliku są nieprawidłowe lub puste, Android odrzuca reguły dynamiczne, a urządzenie wraca do reguł zdefiniowanych statycznie w manifeście aplikacji.

Reguły dynamiczne mogą określać tylko reguły, które obowiązują w zakresie domen zadeklarowanych w pliku manifestu aplikacji. (Patrz niżej).

Deklarowanie reguł dynamicznych

Dynamiczne linki aplikacji obsługują nowe rozszerzenie dynamic_app_link_components relation, które zawiera tablicę obiektów reguł. Każda reguła jest definiowana za pomocą wzorców dopasowywania ścieżek, fragmentów i parametrów zapytania, które otwierają aplikację. Wzorce można też wykluczać, aby nie otwierały aplikacji. Wszystkie te elementy są opcjonalne.

  • Dopasowywanie ścieżek
    • Klucz: „/”
    • Wartość: pojedynczy ciąg znaków pasujący do wyrażenia ścieżki adresu URL
  • Dopasowywanie fragmentów
    • Klucz: „#”
    • Wartość: pojedynczy ciąg znaków, wyrażenie dopasowywania fragmentu adresu URL
  • Dopasowywanie parametrów zapytania
    • Klucz: „?”
    • Wartość: słownik do dopasowywania par klucz-wartość w parametrach zapytania w adresie URL.
    • Na przykład słownik {"?", {"dl": "*", "in_app":"true"} będzie pasować do ciągu zapytania „?in_app=true&dl=abc”.
    • Kolejność par klucz/wartość w słowniku nie musi być zgodna z kolejnością par w ciągu zapytania. Słownik nie musi też pasować do wszystkich par klucz/wartość w ciągu zapytania, ale musi pasować do każdego wpisu w słowniku.
    • Na przykład słownik będzie pasować do ciągu zapytania „?lang=en&in_app=true&tz=pst&dl=abc”, ale nie do ciągu zapytania „?lang=en&tz=pst&dl=abc”.
  • Wykluczone
    • Klucz: „exclude”
    • Wartość: opcjonalna wartość prawda/fałsz dla każdej reguły zdefiniowanej w dynamic_app_link_components (patrz przykład).

W wyszukiwarkach wzorców możesz używać tych znaków specjalnych:

  • Symbol „*” dopasowuje zero lub więcej znaków, dopóki w dopasowywanym ciągu nie zostanie znaleziony znak występujący po symbolu wieloznacznym we wzorcu.
  • „?” odpowiada dowolnemu pojedynczemu znakowi
  • „?*” pasuje do co najmniej 1 znaku.

W przypadku wartości nie obowiązują żadne inne ograniczenia dotyczące znaków.

Określanie kolejności reguł dynamicznych

Kolejność deklarowania reguł ma znaczenie. Android sprawdza każdą regułę po kolei, dopóki nie znajdzie dopasowania.

Poniższy przykład pokazuje, jak kolejność może wpływać na obsługę. Pierwsza reguła pasuje do wszystkich ścieżek („*”), ale wyklucza dopasowania (exclude: true), co oznacza, że wyklucza wszystkie adresy URL z otwierania aplikacji. W tym przypadku druga reguła, która zezwala na „/path1”, nigdy nie zostanie oceniona.

dynamic_app_link_components: [
  {"/": "*", "exclude": true},
  {"/": "/path1"}
]

W następnym przykładzie reguła „/path1” jest jednak zadeklarowana jako pierwsza, więc zostanie oceniona jako pierwsza i otworzy aplikację w przypadku adresu URL pasującego do „/path1”. Druga reguła, która wyklucza wszystkie adresy URL z otwierania aplikacji, będzie sprawdzana jako druga, ale tylko wtedy, gdy pierwsza reguła nie będzie pasować.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "*", "exclude": true}
]

Jeśli na liście zadeklarowanych komponentów nie zostaną znalezione żadne dopasowania, adres URL nie otworzy aplikacji. W poniższym przykładzie żadna ze ścieżek nie pasuje do „/path3”, więc urządzenie potraktuje tę ścieżkę jako wykluczoną.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

Jest to ważne, jeśli chcesz, aby warunek dynamic_app_link_components wykluczał tylko niektóre części adresu URL, ale zezwalał na wszystkie inne. W poniższym przykładzie pominięcie ostatniej reguły zezwalającej na wszystkie pozostałe ścieżki oznaczałoby, że wszystkie adresy URL są wykluczone z aplikacji.

dynamic_app_link_components: [
  {"/": "/path1", "exclude": true},
  {"/": "*"}
]

Prawidłowe określanie zakresu reguł dynamicznych

Podczas definiowania reguł po stronie serwera do użycia z dynamicznymi linkami aplikacji na Androidzie 15 i nowszych ważne jest, aby odpowiednio je określić, tak aby działały i uzupełniały statyczne filtry intencji zadeklarowane w manifeście aplikacji.

Reguły dynamiczne zadeklarowane w pliku assetlinks.json mogą określać reguły tylko dla hostów zadeklarowanych w pliku AndroidManifest.xml aplikacji. Reguły dynamiczne nie mogą rozszerzać zakresu reguł URL zadeklarowanych statycznie w manifeście aplikacji.

Z tego powodu zalecamy stosowanie tego podejścia w przypadku reguł dynamicznych i statycznych:

  • W manifeście aplikacji ustaw reguły o najszerszym możliwym zakresie, np. deklarując tylko schemat i domenę.
  • Aby uzyskać dalsze doprecyzowanie, np. routing na poziomie ścieżki, użyj dynamicznych reguł po stronie serwera.

Dzięki tej idealnej konfiguracji możesz w razie potrzeby dynamicznie dodawać nowe ścieżki linków aplikacji w pliku assetlinks.json, wiedząc, że będą one mieścić się w szerokim zakresie ustawionym w pliku manifestu aplikacji.

Aby reguły były prawidłowo obsługiwane, w instrukcjach dotyczących danej witryny, relacji i aplikacji zadeklaruj tylko jeden obiekt dynamic_app_link_components.

  • Sprawdź, czy nie ma wielu instrukcji dotyczących tej samej witryny, relacji i aplikacji, które deklarują obiekt dynamic_app_link_components.
  • Wyszukaj wiele obiektów dynamic_app_link_components zadeklarowanych w jednym wyrażeniu.

W takich przypadkach Android nie gwarantuje, która konfiguracja reguł dynamicznych zostanie użyta.

Zgodność reguł dynamicznych z wcześniejszymi konfiguracjami linków do aplikacji

Jeśli obsługujesz już linki aplikacji, możesz dodać obsługę dynamicznych linków aplikacji bezpośrednio w istniejącym pliku assetlinks.json. Pola relacji do weryfikacji linków aplikacji pozostają bez zmian. Możesz dodać nowe pola rozszerzenia relacji dla reguł dynamicznych bez wprowadzania innych zmian.

Urządzenia z Androidem 14 (API na poziomie 34 lub starszym) ignorują nowe pola rozszerzenia relacji w przypadku reguł dynamicznych, a urządzenia z Androidem 15 i nowszymi będą łączyć te reguły z regułami zdefiniowanymi w pliku manifestu.

Opublikuj plik weryfikacyjny JSON

Musisz opublikować plik weryfikacyjny JSON w tej lokalizacji:

https://domain.name/.well-known/assetlinks.json

Upewnij się, że:

  • assetlinks.json plik jest udostępniany z typem treści application/json.
  • assetlinks.json musi być dostępny przez połączenie HTTPS, niezależnie od tego, czy filtry intencji aplikacji wskazują HTTPS jako schemat danych.
  • Plik assetlinks.json musi być dostępny bez przekierowań (bez przekierowań 301 ani 302).
  • Jeśli linki do aplikacji obsługują wiele domen hosta, musisz opublikować plik assetlinks.json w każdej domenie. Zobacz Obsługa połączeń z aplikacjami na wielu hostach.
  • Nie publikuj aplikacji z adresami URL testów w pliku manifestu, które mogą być niedostępne publicznie (np. takie, do których dostęp jest możliwy tylko przez VPN). W takich przypadkach można skonfigurować warianty kompilacji, aby generować inny plik manifestu dla kompilacji deweloperskich.

Zapoznaj się z tymi przewodnikami: