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ą uprawnione 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 artykule Narzędzia dla programistów do 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 dotyczące 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 przez uruchomienie keytool lokalnie zwykle nie będzie zgodny z odciskiem na urządzeniach użytkowników. Aby sprawdzić, czy używasz podpisywania aplikacji w Google Play, otwórz konto dewelopera w Konsoli Play i kliknij 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 oświadczeniem, który deklaruje powiązanie z 2 aplikacjami (osobno) 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 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 dla ś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 dopasowujący pary 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:

  • „*” dopasowuje zero lub więcej znaków, aż do momentu, gdy w dopasowywanym ciągu znaków zostanie znaleziony znak występujący po symbolu wieloznacznym w 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 reguły w kolejności, aż znajdzie dopasowanie.

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 sprawdzona.

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ę dla 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}
]

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 z deklarowanymi w manifeście aplikacji statycznymi filtrami intencji i je uzupełniały.

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, korzystaj z 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ą nie być dostę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: