Tworzenie precyzyjnego linku dla miejsca docelowego

Na Androidzie precyzyjny link to link prowadzący bezpośrednio do określonego miejsca w aplikacji.

Komponent Nawigacja umożliwia tworzenie 2 różnych typów precyzyjnych linków: jawnych i niejawnych.

Tworzenie precyzyjnego linku

Precyzyjny link to pojedyncze wystąpienie precyzyjnego linku, który używa elementu PendingIntent, aby kierować użytkowników do określonego miejsca w aplikacji. Precyzyjny link może wyświetlać się na przykład w powiadomieniu lub w widżecie aplikacji.

Gdy użytkownik otworzy aplikację za pomocą wyraźnego precyzyjnego linku, stos zadań wstecz zostanie wyczyszczony i zastąpiony miejscem docelowym precyzyjnego linku. 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 z miejsca docelowego precyzyjnego linku, przejdzie z powrotem na stos nawigacji, tak jak gdyby wszedł do aplikacji z punktu wejścia.

Do utworzenia PendingIntent możesz użyć klasy NavDeepLinkBuilder, jak pokazano w poniższym przykładzie. Pamiętaj, że jeśli podany kontekst nie jest elementem Activity, konstruktor użyje PackageManager.getLaunchIntentForPackage() jako domyślnej aktywności do uruchomienia (o ile 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 Twój wyraźny precyzyjny link do domyślnego uruchomienia Activity, które jest zadeklarowane w pliku manifestu aplikacji. Jeśli element NavHost znajduje się w innej aktywności, podczas tworzenia kreatora precyzyjnych linków musisz podać nazwę 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 go przekazać bezpośrednio do kreatora:

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().

Tworzenie precyzyjnego linku

niejawny precyzyjny link odnosi się do określonego miejsca docelowego w aplikacji. Po wywołaniu precyzyjnego linku, np. gdy użytkownik kliknie link, Android może otworzyć aplikację w odpowiednim miejscu docelowym.

Precyzyjne linki można dopasowywać według identyfikatora URI, działań intencji i typów MIME. Możesz określić wiele typów dopasowania dla 1 precyzyjnego linku, ale pamiętaj, że w pierwszej kolejności priorytet ma dopasowanie argumentów URI, potem działanie, a potem 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>

Możesz też użyć edytora nawigacji, aby utworzyć niejawny precyzyjny link do miejsca docelowego w ten sposób:

  1. Na karcie Projekt w edytorze nawigacji wybierz miejsce docelowe precyzyjnego linku.
  2. Kliknij + w sekcji Precyzyjne linki w panelu Atrybuty.

  3. W wyświetlonym oknie Dodaj precyzyjny link wpisz informacje dotyczące precyzyjnego linku.

    Uwaga:

    • Identyfikatory URI bez schematu zakłada się jako http lub https. Na przykład właściwość www.google.com będzie pasować zarówno do wartości http://www.google.com, jak i https://www.google.com.
    • Zmienne 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 obiektów zastępczych pod kątem odpowiednich typów, dopasowując ich nazwy do zdefiniowanych argumentów zdefiniowanych na potrzeby miejsca docelowego precyzyjnego linku. Jeśli nie zdefiniowano żadnego argumentu o tej samej nazwie, jako wartość argumentu używany jest domyślny typ String. Za pomocą symbolu wieloznacznego .* możesz dopasować 0 lub więcej znaków.
    • Obiektów zastępczych parametrów zapytania można używać zamiast parametrów ścieżki lub w połączeniu z nimi. Na przykład http://www.example.com/users/{id}?myarg={myarg} pasuje do http://www.example.com/users/4?myarg=28.
    • Zmienne parametrów zapytania dla zmiennych zdefiniowanych z wartościami domyślnymi lub zerowymi nie muszą być dopasowane. 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 inaczej. Na przykład http://www.example.com/users?arg1=7&arg2=28 nie pasuje do powyższego wzorca, ponieważ nie podano wymaganego parametru ścieżki.
    • Zbędne parametry zapytania nie mają wpływu 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 zdefiniowany we wzorcu identyfikatora URI.

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

  5. Kliknij Dodaj. Nad wybranym miejscem docelowym pojawi się ikona wskazująca, że miejsce docelowe zawiera precyzyjny link.

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

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

Aby włączyć niejawne precyzyjne linki, musisz też dodać do pliku manifest.xml swojej aplikacji. Dodaj pojedynczy element <nav-graph> do działania, które wskazuje istniejący wykres nawigacyjny, jak pokazano 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 komponent Nawigacja zastępuje element <nav-graph> wygenerowanymi elementami <intent-filter>, aby dopasować wszystkie precyzyjne linki na wykresie nawigacyjnym.

Gdy aktywujesz niejawny precyzyjny link, stan stosu wstecznego zależy od tego, czy niejawny Intent został uruchomiony z flagą Intent.FLAG_ACTIVITY_NEW_TASK:

  • Jeśli flaga jest ustawiona, stos wsteczny zadań zostanie wyczyszczony i zastąpiony miejscem docelowym precyzyjnych linków. Podobnie jak w przypadku 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 punkt początkowy z każdego elementu <navigation> w hierarchii. Oznacza to, że gdy użytkownik naciśnie przycisk Wstecz z miejsca docelowego precyzyjnego linku, przejdzie z powrotem do stosu nawigacji, tak jak gdyby wszedł do aplikacji z punktu wejścia.
  • Jeśli flaga nie jest ustawiona, pozostaniesz na stosie zadań poprzedniej aplikacji, w której aktywowano niejawny precyzyjny link. W tym przypadku przycisk Wstecz powoduje powrót do poprzedniej aplikacji, a przycisk W górę powoduje rozpoczęcie zadania aplikacji w hierarchicznym miejscu docelowym na wykresie nawigacyjnym.

Obsługa precyzyjnych linków

Podczas korzystania z nawigacji zdecydowanie zalecamy, aby zawsze używać domyślnej wartości launchMode wartości standard. W trybie uruchamiania standard Nawigacja automatycznie obsługuje precyzyjne linki, wywołując handleDeepLink() w celu przetworzenia wszelkich jawnych lub niejawnych takich linków w obrębie Intent. Nie dzieje się to jednak automatycznie, jeśli właściwość Activity jest ponownie używana z alternatywnym elementem launchMode, takim jak singleTop. W takim przypadku musisz ręcznie wywołać handleDeepLink() w 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.

Próbki

Ćwiczenia z programowania

Filmy