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

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

W przypadku dynamicznych linków aplikacji w Androidzie 15 lub nowszym plik assetlinks.json służy też do definiowania konfiguracji reguł dynamicznych, takich jak dopasowywanie wzorców do ścieżki, fragmentu i parametrów zapytania. Urządzenia z Androidem 15 (poziom interfejsu API 35) lub nowszym, na których zainstalowane są usługi Google, będą okresowo pobierać ten plik i łączyć konfigurację dynamiczną z konfiguracją statyczną w pliku manifestu aplikacji.

W tym przewodniku opisujemy, jak przygotować plik assetlinks.json i opublikować go w swojej witrynie. Jeśli wolisz, możesz wygenerować plik assetlinks.json za pomocą narzędzia Play Deep Links lub Asystenta linków do aplikacji w Android Studio. Więcej informacji znajdziesz w artykule Narzędzia dla programistów dotyczące linków aplikacji.

Deklarowanie powiązań z witryną

Aby wskazać aplikacje na Androida powiązane z witryną i zweryfikować intencje URL aplikacji, musisz opublikować w witrynie plik JSON protokołu Digital Asset Links. Plik JSON używa tych pól do identyfikowania powiązanych aplikacji:

  • package_name: identyfikator aplikacji zadeklarowany w build.gradle pliku aplikacji.
  • sha256_cert_fingerprints: odciski cyfrowe SHA256 certyfikatu podpisywania aplikacji. Aby wygenerować odcisk cyfrowy 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 cyfrowych, których można używać do obsługi różnych wersji aplikacji, np. wersji debugowania i wersji produkcyjnej. Jeśli używasz podpisywania aplikacji przez Google Play dla swojej aplikacji, odcisk cyfrowy certyfikatu wygenerowany przez uruchomienie narzędzia keytool lokalnie zwykle nie będzie zgodny z odciskiem cyfrowym na urządzeniach użytkowników. Możesz sprawdzić, czy używasz podpisywania aplikacji przez Google Play dla swojej aplikacji na koncie dewelopera w Konsoli Play w sekcji Release > Setup > App signing. Jeśli tak jest, na tej samej stronie znajdziesz też prawidłowy fragment kodu JSON protokołu Digital Asset Links dla swojej aplikacji.

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

[{
  "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 kilkoma aplikacjami

Witryna może deklarować powiązania z kilkoma aplikacjami w tym samym pliku assetlinks.json. Ten przykład pokazuje plik deklaracji, który deklaruje powiązanie z 2 aplikacjami oddzielnie i znajduje się w lokalizacji 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 deklarować filtr intencji dla adresu https://example.com/articles, a aplikacja 2 może deklarować filtr intencji dla adresu https://example.com/videos.

Powiązywanie kilku witryn z jedną aplikacją

Kilka witryn może deklarować powiązania z tą samą aplikacją w swoich plikach assetlinks.json. Te przykłady pokazują, jak zadeklarować powiązanie domen example.com i example.net z aplikacją 1. Pierwszy przykład pokazuje powiązanie domeny example.com z aplikacją 1:

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"]
  }
}]

Następny przykład pokazuje powiązanie domeny example.net z aplikacją 1. 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 w Androidzie 15 lub nowszym umożliwiają używanie po stronie serwera reguł dopasowywania precyzyjnych linków, które współpracują z regułami zdefiniowanymi statycznie w manifeście aplikacji. Reguły dynamiczne definiujesz w pliku assetlinks.json. Dodanie tego pliku jest opcjonalne.

Urządzenia z Androidem 15 (poziom interfejsu API 35) lub nowszym, 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 konfigurujesz reguły dynamiczne.
  • Reguły dynamiczne mogą zawierać dopasowywanie wzorców do ścieżki, fragmentu i parametrów zapytania.
  • Możesz też oznaczyć dowolny dopasowywanie wzorców jako wykluczone, aby pasujące adresy URL nie otwierały Twojej aplikacji.
  • Ten przykład pokazuje dopasowywanie wzorców do ścieżki ("/"), fragmentu ("#"), parametrów zapytania ("?") oraz wykluczone dopasowywanie wzorców ("exclude").
  • Jeśli którekolwiek z pól w pliku jest 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. Szczegółowe informacje znajdziesz poniżej.

Deklarowanie reguł dynamicznych

Dynamiczne linki aplikacji obsługują nowe rozszerzenie relacji dynamic_app_link_components, które zawiera tablicę obiektów reguł. Każda reguła jest definiowana za pomocą dopasowywania wzorców do ścieżek, fragmentów i parametrów zapytania, które będą otwierać Twoją aplikację. Dopasowywanie wzorców można też wykluczyć, aby nie otwierało aplikacji. Wszystkie te elementy są opcjonalne.

  • Dopasowywanie ścieżki
    • Klucz: "/"
    • Wartość: pojedynczy ciąg znaków, wyrażenie dopasowujące do ścieżki adresu URL
  • Dopasowywanie fragmentu
    • Klucz: "#"
    • Wartość: pojedynczy ciąg znaków, wyrażenie dopasowujące do fragmentu adresu URL
  • Dopasowywanie parametru zapytania
    • Klucz: "?"
    • Wartość: słownik dopasowujący pary klucz-wartość w parametrach zapytania adresu 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. Ponadto słownik nie musi pasować do wszystkich par klucz-wartość w ciągu zapytania, ale musi zostać znalezione dopasowanie dla każdego wpisu w słowniku.
    • Na przykład słownik będzie też 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ść true/false dla każdej reguły zdefiniowanej w dynamic_app_link_components (patrz przykład).

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

  • "*" pasuje do zera lub większej liczby znaków aż do znalezienia w pasującym ciągu znaku występującego po symbolu wieloznacznym we wzorcu.
  • "?" pasuje do dowolnego pojedynczego znaku.
  • "?*" pasuje do 1 lub większej liczby znaków.

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

Kolejność reguł dynamicznych

Kolejność deklarowania reguł ma znaczenie. Android ocenia każdą regułę po kolei, aż znajdzie dopasowanie.

Ten 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"}
]

Jednak w następnym przykładzie reguła „/path1” jest zadeklarowana jako pierwsza, więc zostanie oceniona jako pierwsza i otworzy aplikację dla adresu URL pasującego do „/path1”. Druga reguła, która wyklucza wszystkie adresy URL z otwierania aplikacji, zostanie oceniona 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 tym 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"}
]

To zachowanie jest ważne, jeśli chcesz, aby dynamic_app_link_components wykluczało tylko określone części adresu URL, ale zezwalało na wszystkie inne. W tym przykładzie pominięcie ostatniej reguły, która zezwala 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 w Androidzie 15 lub nowszym ważne jest, aby odpowiednio określić ich zakres, tak aby współpracowały z filtrami intencji zadeklarowanymi statycznie w manifeście aplikacji i je uzupełniały.

Reguły dynamiczne zadeklarowane w pliku assetlinks.json mogą określać tylko reguły dla hostów zadeklarowanych w pliku AndroidManifest.xml aplikacji. Reguły dynamiczne nie mogą rozszerzać zakresu reguł adresów 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 jak najszerszym zakresie, np. deklarując tylko schemat i domenę.
  • W przypadku dalszego doprecyzowania, np. routingu na poziomie ścieżki, polegaj na regułach dynamicznych po stronie serwera.

Dzięki tej idealnej konfiguracji będziesz mieć możliwość dynamicznego dodawania nowych ścieżek linków aplikacji w pliku assetlinks.json w razie potrzeby, wiedząc, że będą one mieścić się w szerokim zakresie ustawionym w manifeście aplikacji.

Aby reguły były prawidłowo obsługiwane, zadeklaruj tylko 1 obiekt dynamic_app_link_components w instrukcjach dla danej witryny, relacji i aplikacji.

  • Poszukaj wielu instrukcji dla tej samej witryny, relacji i aplikacji, które deklarują obiekt dynamic_app_link_components.
  • Poszukaj wielu obiektów dynamic_app_link_components zadeklarowanych w jednej instrukcji.

W takich przypadkach Android nie gwarantuje, która konfiguracja reguł dynamicznych będzie używana.

Zgodność reguł dynamicznych z wcześniejszymi konfiguracjami linków 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 weryfikowania linków aplikacji pozostają takie same, a pola nowego rozszerzenia relacji dla reguł dynamicznych możesz dodać bez żadnych innych zmian.

Urządzenia z Androidem 14 (poziom interfejsu API 34 lub starszy) ignorują nowe pola rozszerzenia relacji dla reguł dynamicznych, a urządzenia z Androidem 15 lub nowszym będą łączyć te reguły z regułami zdefiniowanymi w manifeście.

Publikowanie pliku weryfikacji JSON

Plik weryfikacji JSON musisz opublikować w tej lokalizacji:

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

Upewnij się, że:

Zapoznaj się z tymi powiązanymi przewodnikami: