Bir hedef için derin bağlantı oluşturma

Android'de derin bağlantı, sizi doğrudan bir uygulamanın belirli bir hedefine yönlendiren bağlantıdır.

Uygulamanızda iki farklı derin bağlantı türünü destekleyebilirsiniz: açık ve örtülü. Derin bağlantıları uygulama şekliniz, uygulamanızın kullandığı grafik türüne (XML or programmatic) bağlı olarak değişir.

Açık derin bağlantı oluşturma

Açık derin bağlantı, kullanıcıları uygulamanızdaki belirli bir konuma yönlendirmek için PendingIntent kullanan tek bir derin bağlantı örneğidir. Örneğin, açık derin bağlantıyı bildirim veya uygulama widget'ı kapsamında gösterebilirsiniz.

Bir kullanıcı, uygulamanızı açık bir derin bağlantı aracılığıyla açtığında görev geri yığını temizlenir ve derin bağlantı hedefiyle değiştirilir. Grafikler iç içe yerleştirildiğinde, iç içe yerleştirmenin her seviyesindeki başlangıç hedefi (yani hiyerarşideki her <navigation> öğesinin başlangıç hedefi) de yığına eklenir. Bu, bir kullanıcının derin bağlantı hedefinden Geri düğmesine bastığında, uygulamanıza giriş noktasından girmiş gibi gezinme yığınında geriye doğru gezinmesini sağlar.

Koşullu Gezinme ile ilgili yönergeleri uygulayın.

Programatik grafikler

Gezinme grafiğiniz programatik olarak tanımlanmışsa (Navigation Compose veya Kotlin DSL'de olduğu gibi) derin bağlantı oluşturmak için TaskStackBuilder kullanmanızı öneririz PendingIntent.

val id = "exampleId"
val context = LocalContext.current
val deepLinkIntent = Intent(
    Intent.ACTION_VIEW,
    "https://www.example.com/profile/$id".toUri(),
    context,
    MyActivity::class.java
)

val pendingIntent: PendingIntent? = TaskStackBuilder.create(context).run {
    addNextIntentWithParentStack(deepLinkIntent)
    getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT)
}

XML grafikleri

Aşağıdaki örnekte gösterildiği gibi, NavDeepLinkBuilder sınıfını kullanarak PendingIntent oluşturabilirsiniz. Sağlanan bağlam bir Activity değilse oluşturucunun, varsa başlatılacak varsayılan etkinlik olarak PackageManager.getLaunchIntentForPackage() kullandığını unutmayın.

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

Varsayılan olarak NavDeepLinkBuilder, uygulamanızın manifestinde belirtilen varsayılan başlatma Activity için açık derin bağlantınızı başlatır. NavHost öğeniz başka bir etkinlikteyse derin bağlantı oluşturucuyu oluştururken bileşen adını belirtmeniz gerekir:

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

ComponentName varsa bunu doğrudan oluşturucuya iletebilirsiniz:

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

Mevcut bir NavController varsa NavController.createDeepLink() kullanarak da derin bağlantı oluşturabilirsiniz.

Kapalı derin bağlantı oluşturma

Kapalı derin bağlantı, uygulamadaki belirli bir hedefi ifade eder. Derin bağlantı çağrıldığında (ör. kullanıcı bir bağlantıyı tıkladığında) Android, uygulamanızı ilgili hedefte açabilir.

Derin bağlantılar URI, amaç işlemleri ve MIME türlerine göre eşleştirilebilir. Tek bir derin bağlantı için birden fazla eşleme türü belirtebilirsiniz. Ancak URI bağımsız değişken eşlemesinin önce, ardından işlemin ve son olarak MIME türünün öncelikli olduğunu unutmayın.

Programatik grafikler

Navigasyon grafiğinizi programatik olarak (Navigation Compose veya Kotlin DSL kullanarak) tanımlarsanız derin bağlantıları kodda tanımlarsınız.

Oluştur

Navigation Compose'da, composable() parametresini kullanarak derin bağlantıları deepLinks hedef oluşturucunun bir parçası olarak tanımlayabilirsiniz. NavDeepLink nesnelerinin listesini kabul eder. Bu nesneleri navDeepLink() işlevini kullanarak oluşturabilirsiniz:

@Serializable
data class Profile(val id: String)

val uri = "https://www.example.com"

composable<Profile>(
  deepLinks = listOf(
    navDeepLink<Profile>(basePath = "$uri/profile")
  )
) { backStackEntry ->
  val profile: Profile = backStackEntry.toRoute()
  ProfileScreen(id = profile.id)
}

Kotlin DSL

Kotlin DSL'yi kullanırken hedef bloktaki deepLink() oluşturucu işlevini kullanarak derin bağlantılar tanımlayabilirsiniz:

@Serializable
data class Profile(val id: String)

val uri = "https://www.example.com"

fragment<ProfileFragment, Profile> {
    deepLink<Profile>(basePath = "$uri/profile")
}

Programatik grafikler için amaç filtreleri ekleme

Programatik gezinme grafikleri çalışma zamanında oluşturulduğundan Navigation bileşeni, AndroidManifest.xml öğenizde eşleşen <intent-filter> öğelerini otomatik olarak oluşturamaz. Bunun yerine, uygun <intent-filter> öğelerini manuel olarak eklemeniz gerekir.

Önceki örneklerde derin bağlantıyı etkinleştirmek için manifestinizdeki ilgili <activity> öğesinin içine aşağıdakileri ekleyin:

<activity …>
  <intent-filter>
    ...
    <data android:scheme="https" android:host="www.example.com" />
  </intent-filter>
</activity>

XML grafikleri

XML tabanlı bir grafikte kapalı derin bağlantı oluşturmak için <deepLink> öğesini doğrudan XML'de tanımlayabilir veya Gezinme Düzenleyici'yi kullanabilirsiniz.

URI, işlem ve MIME türü içeren bir örnek derin bağlantıyı aşağıda bulabilirsiniz:

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

Ayrıca, bir hedefe kapalı derin bağlantı oluşturmak için Gezinme Düzenleyici'yi de aşağıdaki şekilde kullanabilirsiniz:

  1. Gezinme Düzenleyicisi'nin Tasarım sekmesinde derin bağlantının hedefini seçin.
  2. Özellikler panelinin Derin Bağlantılar bölümünde + simgesini tıklayın.

  3. Açılan Derin Bağlantı Ekle iletişim kutusunda derin bağlantınızla ilgili bilgileri girin.

    Aşağıdakileri göz önünde bulundurun:

    • Şeması olmayan URI'lerin http veya https olduğu varsayılır. Örneğin, www.google.com hem http://www.google.com hem de https://www.google.com ile eşleşir.
    • {placeholder_name} biçimindeki yol parametresi yer tutucuları bir veya daha fazla karakterle eşleşir. Örneğin, http://www.example.com/users/{id}, http://www.example.com/users/4 ile eşleşir. Navigation bileşeni, yer tutucu adlarını derin bağlantı hedefi için tanımlanan arguments ile eşleştirerek yer tutucu değerlerini uygun türlere ayrıştırmaya çalışır. Aynı ada sahip bir bağımsız değişken tanımlanmamışsa bağımsız değişken değeri için varsayılan String türü kullanılır. 0 veya daha fazla karakteri eşleştirmek için .* joker karakterini kullanabilirsiniz.
    • Sorgu parametresi yer tutucuları, yol parametreleri yerine veya bunlarla birlikte kullanılabilir. Örneğin, http://www.example.com/users/{id}?myarg={myarg}, http://www.example.com/users/4?myarg=28 ile eşleşir.
    • Varsayılan veya null değerlerle tanımlanan değişkenler için sorgu parametresi yer tutucularının eşleşmesi gerekmez. Örneğin, http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2}, http://www.example.com/users/4?arg2=28 veya http://www.example.com/users/4?arg1=7 ile eşleşir. Bu durum, yol parametreleri için geçerli değildir. Örneğin, http://www.example.com/users?arg1=7&arg2=28 gerekli yol parametresi sağlanmadığı için yukarıdaki kalıpla eşleşmez.
    • Gereksiz sorgu parametreleri, derin bağlantı URI'si eşleşmesini etkilemez. Örneğin, http://www.example.com/users/{id}, URI kalıbında extraneousParam tanımlanmamış olsa bile http://www.example.com/users/4?extraneousParam=7 ile eşleşir.

  4. (İsteğe bağlı) Google'ın URI'nin sahibi olduğunuzu doğrulamasını zorunlu kılmak için Otomatik Doğrulama'yı işaretleyin. Daha fazla bilgi için Android App Links'i doğrulama başlıklı makaleyi inceleyin.

  5. Ekle'yi tıklayın. Seçilen hedefin üzerinde, bu hedefin derin bağlantısı olduğunu belirten bir bağlantı simgesi görünür.

  6. XML görünümüne geçmek için Kod sekmesini tıklayın. Hedefe yerleştirilmiş bir <deepLink> öğesi eklendi:

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

XML tabanlı grafiklerde örtülü derin bağlantıyı etkinleştirmek için uygulamanızın manifest.xml dosyasına da eklemeler yapmanız gerekir. Aşağıdaki örnekte gösterildiği gibi, mevcut bir gezinme grafiğine işaret eden bir etkinliğe tek bir <nav-graph> öğesi ekleyin:

<?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>

Projenizi oluştururken Navigation bileşeni, gezinme grafiğindeki tüm derin bağlantılarla eşleşmesi için <nav-graph> öğesini oluşturulan <intent-filter> öğeleriyle değiştirir.

Kapalı derin bağlantılar ve geri yığını

Kapalı derin bağlantı tetiklenirken geri yığınının durumu, kapalı Intent öğesinin Intent.FLAG_ACTIVITY_NEW_TASK işaretiyle başlatılıp başlatılmadığına bağlıdır:

  • Bu işaret ayarlanırsa görev geri yığını temizlenir ve derin bağlantı hedefiyle değiştirilir. Açık derin bağlantıda olduğu gibi, grafikler iç içe yerleştirildiğinde, iç içe yerleştirmenin her seviyesindeki başlangıç hedefi (yani hiyerarşideki her <navigation> öğesinin başlangıç hedefi) de yığına eklenir. Bu, kullanıcının derin bağlantı hedefinden Geri düğmesine bastığında, uygulamanıza giriş noktasından girmiş gibi gezinme yığınında geriye doğru gezinmesi anlamına gelir.
  • İşaret ayarlanmazsa, kapalı derin bağlantının tetiklendiği önceki uygulamanın görev yığınında kalırsınız. Bu durumda, Geri düğmesi sizi önceki uygulamaya geri götürürken Yukarı düğmesi, uygulamanızın görevini gezinme grafiğinizdeki hiyerarşik üst hedefte başlatır.

Derin bağlantıları işleme

Navigasyonu kullanırken her zaman standard'ün varsayılan launchMode değerini kullanmanız önemle tavsiye edilir. standard başlangıç modu kullanılırken Navigation, handleDeepLink()'ı çağırarak derin bağlantıları otomatik olarak işler. Bu sayede, Intent içindeki tüm açık veya kapalı derin bağlantılar işlenir. Ancak, Activity, singleTop gibi alternatif bir launchMode kullanılırken yeniden kullanılıyorsa bu işlem otomatik olarak gerçekleşmez. Bu durumda, aşağıdaki örnekte gösterildiği gibi onNewIntent() içinde handleDeepLink() işlevini manuel olarak çağırmak gerekir:

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);
}