Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

Aby obsługiwać linki do aplikacji, musisz utworzyć plik JSON protokołu 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 do aplikacji na Androidzie 15 lub nowszym plik assetlinks.json jest też miejscem, w którym definiujesz konfigurację reguł dynamicznych, np. wzorce dopasowywania ś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 scalać 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.jsonza pomocą narzędzia Precyzyjne linki w Google Play lub Asystenta linków do aplikacji w Android Studio. Więcej informacji znajdziesz w artykule Narzędzia dla programistów linków do aplikacji.

Deklarowanie powiązań z witrynami

Aby wskazać aplikacje na Androida powiązane z witryną i zweryfikować intencje dotyczące adresów URL aplikacji, musisz opublikować w witrynie plik JSON Digital Asset Links. 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, użyj tego polecenia:

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

To pole obsługuje wiele odcisków palców, których można używać do obsługi różnych wersji aplikacji, np. wersji debugowania i produkcyjnej. Jeśli używasz podpisywania aplikacji przez Google Play, odcisk cyfrowy certyfikatu wygenerowany przez uruchomienie keytool lokalnie 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 przez 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 pliku.assetlinks.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 lista 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. To pole 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 pliku 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 dopasowania 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 pliku manifestu aplikacji.

Reguły dynamiczne mogą określać tylko reguły, które obowiązują w zakresie domen zadeklarowanych w pliku manifestu aplikacji. Zapoznaj się z sekcją Deklarowanie reguł dynamicznych.

Deklarowanie reguł dynamicznych

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

Dopasowywanie ścieżek
- Klucz: „/”
- Wartość: pojedynczy ciąg znaków, wyrażenie dopasowania ś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 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ść 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, dopóki w dopasowywanym ciągu nie 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.

Porządkowanie 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 „/ścieżka1” jest zadeklarowana jako pierwsza, więc zostanie oceniona jako pierwsza i otworzy aplikację dla adresu URL pasującego do „/ścieżka1”. Druga reguła, która wyklucza otwieranie aplikacji przez wszystkie adresy URL, zostanie oceniona jako druga, ale tylko wtedy, gdy pierwsza reguła nie pasuje.

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 dynamic_app_link_components wykluczał tylko niektóre części adresu URL, ale zezwalał na wszystkie inne. W przykładzie poniżej 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 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 jeszcze bardziej doprecyzować reguły, np. w przypadku routingu 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 manifeście aplikacji.

Deklarowanie dynamic_app_link_components tylko raz

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

Wyszukaj wiele instrukcji dotyczących tej samej witryny, relacji i aplikacji, które deklarują obiekt dynamic_app_link_components.
Sprawdź, czy w jednej instrukcji nie zadeklarowano wielu obiektów dynamic_app_link_components.

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 do aplikacji, możesz dodać obsługę dynamicznych linków do aplikacji bezpośrednio w istniejącym pliku assetlinks.json. Pola relacji do weryfikacji linków do aplikacji pozostają bez zmian, a nowe pola rozszerzenia relacji dla reguł dynamicznych możesz dodać 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.
Plik assetlinks.json musi być dostępny przez połączenie HTTPS, niezależnie od tego, czy filtry intencji aplikacji deklarują 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: