Tworzenie precyzyjnego linku dla miejsca docelowego

Na Androidzie precyzyjny link to link, który prowadzi bezpośrednio do określonego miejsca w aplikacji.

Komponent Nawigacja umożliwia tworzenie 2 rodzajów precyzyjnych linków: wyraźnych i domyślnych.

Tworzenie precyzyjnego linku typu explicit

Wyraźny precyzyjny link to pojedynczy precyzyjny link, który używa PendingIntentdo kierowania użytkowników do określonego miejsca w aplikacji. Możesz wyświetlić wyraźny precyzyjny link na przykład w ramach powiadomienia lub widżetu aplikacji.

Gdy użytkownik otworzy Twoją aplikację za pomocą precyzyjnego linku, stos zadań zostanie wyczyszczony i zastąpiony miejscem docelowym precyzyjnego linku. Podczas zagnieżdżania wykresów do stosu jest też dodawane miejsce docelowe z początku każdego poziomu zagnieżdżania, czyli miejsce docelowe z początku każdego elementu <navigation> w hierarchii. Oznacza to, że gdy użytkownik kliknie przycisk Wstecz w miejscu docelowym precyzyjnego linku, wróci do poprzedniego poziomu nawigacji tak, jakby wszedł do aplikacji od jej punktu wejścia.

Aby utworzyć obiekt PendingIntent, możesz użyć klasy NavDeepLinkBuilder, jak pokazano w przykładzie poniżej. Pamiętaj, że jeśli podany kontekst nie jest obiektem Activity, konstruktor używa parametru PackageManager.getLaunchIntentForPackage() jako domyślnej aktywności do uruchomienia (jeśli jest dostępna).

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent();

Domyślnie NavDeepLinkBuilder uruchamia precyzyjny link do domyślnego Activity, który jest zadeklarowany w manifeście aplikacji. Jeśli NavHost znajduje się w innej aktywności, podczas tworzenia kreatora precyzyjnych linków musisz podać nazwę jego komponentu:

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(DestinationActivity::class.java)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(DestinationActivity.class)
        .createPendingIntent();

Jeśli masz ComponentName, możesz przekazać go bezpośrednio do konstruktora:

Kotlin

val componentName = ...

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(componentName)
    .createPendingIntent()

Java

ComponentName componentName = ...;

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(componentName)
        .createPendingIntent();

Jeśli masz już NavController, możesz też utworzyć precyzyjny link za pomocą NavController.createDeepLink().

Uwaga: jeśli na ekranie użytkownik musi wykonać jakieś działanie, np. zalogować się, aby uzyskać do niego dostęp, postępuj zgodnie z instrukcjami dotyczącymi warunkowej nawigacji, aby kierować użytkownika na ten ekran za pomocą linku docelowego.

Tworzenie precyzyjnego linku typu implicit

Implicytny precyzyjny link odnosi się do określonego miejsca docelowego w aplikacji. Gdy wywołany zostanie precyzyjny link (np. gdy użytkownik kliknie link), Android może otworzyć Twoją aplikację w odpowiednim miejscu docelowym.

Precyzyjne linki można dopasowywać na podstawie identyfikatora URI, działań związanych z intencją i typów MIME. Możesz określić wiele typów dopasowania dla jednego linku głębokiego, ale pamiętaj, że najpierw jest dopasowywany argument URI, potem działanie, a na końcu typ MIME.

Oto przykład precyzyjnego linku zawierającego identyfikator URI, działanie i typ MIME:

<fragment android:id="@+id/a"
          android:name="com.example.myapplication.FragmentA"
          tools:layout="@layout/a">
        <deepLink app:uri="www.example.com"
                app:action="android.intent.action.MY_ACTION"
                app:mimeType="type/subtype"/>
</fragment>

Za pomocą Edytora nawigacji możesz też utworzyć do ukrytego celu precyzyjny link w ten sposób:

1. Na karcie Projekt w Edytorze nawigacji wybierz miejsce docelowe precyzyjnego linku.
2. W sekcji Linki dogłębne w panelu Atrybuty kliknij +.

3. W wyświetlonym oknie Dodaj precyzyjny link wpisz informacje o precyzyjnym linku.

   Uwaga:

   • Identyfikatory URI bez schematu są uznawane za identyfikatory http lub https. Na przykład: www.google.com pasuje zarówno do http://www.google.com, jak i do https://www.google.com.
   • Zakładki parametrów ścieżki w postaci {placeholder_name} pasują do co najmniej 1 znaku. Na przykład http://www.example.com/users/{id} pasuje do http://www.example.com/users/4. Komponent Nawigacja próbuje przeanalizować wartości zastępcze i przypisać je do odpowiednich typów, dopasowując nazwy zastępcze do zdefiniowanych argumentów, które są zdefiniowane dla miejsca docelowego precyzyjnego linku. Jeśli nie zdefiniowano żadnego argumentu o tym samym imieniu, do wartości argumentu zostanie użyty domyślny typ String. Za pomocą symbolu wieloznacznego „.” możesz dopasować 0 lub więcej znaków.
   • Zakładki parametrów zapytania można używać zamiast parametrów ścieżki lub razem z nimi. Na przykład: http://www.example.com/users/{id}?myarg={myarg} pasuje do http://www.example.com/users/4?myarg=28.
   • Zakładki parametrów zapytań dla zmiennych zdefiniowanych za pomocą wartości domyślnych lub wartości dozwolonych niewymagają dopasowania. Na przykład http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2} pasuje do http://www.example.com/users/4?arg2=28 lub http://www.example.com/users/4?arg1=7. W przypadku parametrów ścieżki jest to niemożliwe. Na przykład http://www.example.com/users?arg1=7&arg2=28nie pasuje do powyższego wzoru, ponieważ nie podano wymaganego parametru ścieżki.
   • Nieistotne parametry zapytania nie wpływają na dopasowywanie identyfikatorów URI precyzyjnych linków. Na przykład http://www.example.com/users/{id} pasuje do http://www.example.com/users/4?extraneousParam=7, mimo że extraneousParam nie jest zdefiniowana we wzorze adresu URL.

4. (Opcjonalnie) Zaznacz Automatyczna weryfikacja, aby wymagać od Google potwierdzenia, że jesteś właścicielem adresu URI. Więcej informacji znajdziesz w artykule Weryfikowanie linków aplikacji na Androida.

5. Kliknij Dodaj. Nad wybranym miejscem docelowym pojawi się ikona linka , aby wskazać, że to miejsce ma link głęboki.

6. Kliknij kartę Kod, aby przełączyć się na widok kodu XML. Do miejsca docelowego został dodany zagnieżdżony element <deepLink>:

   <deepLink app:uri="https://www.google.com" />
   

Aby włączyć domyślne precyzyjne linki, musisz też wprowadzić zmiany w pliku manifest.xml aplikacji. Dodaj pojedynczy element <nav-graph> do aktywności, która wskazuje na istniejący graf nawigacyjny, jak w tym przykładzie:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapplication">

    <application ... >

        <activity name=".MainActivity" ...>
            ...

            <nav-graph android:value="@navigation/nav_graph" />

            ...

        </activity>
    </application>
</manifest>

Podczas tworzenia projektu element Nawigacja zastępuje element <nav-graph> wygenerowanymi elementami <intent-filter>, aby pasowały do wszystkich precyzyjnych linków w grafie nawigacji.

Stan stosu poprzednich elementów zależy od tego, czy uruchomiono go za pomocą flagi Intent: Intent.FLAG_ACTIVITY_NEW_TASK.

• Jeśli flaga jest ustawiona, stos zadań do cofnięcia jest czyszczony i zastępowany miejscem docelowym linku głębokiego. Podobnie jak w przypadku wyraźnych precyzyjnych linków, podczas zagnieżdżania wykresów do stosu jest też dodawane miejsce docelowe początkowe z każdego poziomu zagnieżdżenia, czyli miejsce docelowe początkowe z każdego elementu <navigation> w hierarchii. Oznacza to, że gdy użytkownik naciśnie przycisk Wstecz w miejscu docelowym precyzyjnego linku, wróci do poprzedniego poziomu nawigacji tak, jakby wszedł do aplikacji od jej punktu wejścia.
• Jeśli flaga nie jest ustawiona, pozostaniesz w grupie zadań poprzedniej aplikacji, w której został wywołany domyślny precyzyjny link. W takim przypadku przycisk Wstecz spowoduje powrót do poprzedniej aplikacji, a przycisk W górę uruchomi zadanie aplikacji w hierarchicznej lokalizacji nadrzędnej w grafu nawigacji.

Obsługa precyzyjnych linków

Podczas korzystania z nawigacji zdecydowanie zalecamy zawsze używanie domyślnego ustawienia launchMode standard. W trybie standard nawigacja automatycznie obsługuje precyzyjne linki, wywołując funkcję handleDeepLink(), aby przetworzyć wszystkie precyzyjne linki jawne i domyślne w ramach Intent. Nie dzieje się tak jednak, jeśli Activity jest ponownie używany przy użyciu alternatywnego launchMode, takiego jak singleTop. W takim przypadku musisz ręcznie wywołać funkcję handleDeepLink() w funkcji onNewIntent(), jak pokazano w tym przykładzie:

Kotlin

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    navController.handleDeepLink(intent)
}

Java

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    navController.handleDeepLink(intent);
}

Dodatkowe materiały

Więcej informacji o nawigacji znajdziesz w tych materiałach.

Ćwiczenia z programowania

• Nawigacja – ćwiczenie z programowania

Filmy

• Android Jetpack: zarządzanie nawigacją w interfejsie za pomocą kontrolera nawigacji (Google I/O 2018)