Uygulama bağlantıları için intent filtreleri ekleme

Uygulama Bağlantıları, HTTP veya HTTPS şemasını kullanan ve Android tarafından web sitenizle ilişkili olduğu doğrulanan derin bağlantılardır. Uygulama Bağlantıları'nı işlemek için kaydolmak üzere aşağıdaki adımları uygulayın:

1. Uygulama manifestinize web sitenizin alan adını veya URL'lerini belirten bir ya da daha fazla intent filtresi ekleyin.
2. autoVerify="true"attribute öğesini intent filtresi öğelerine ekleyin. Bu, sisteme, şemayı ve barındırılan alan adlarını web sitenizin assetlinks.json yapılandırmasına göre doğrulamaya çalışması gerektiğini bildirir.
3. Web sitesi ilişkilendirmelerini bildirin.

Aşağıda, şemalar ve ana makinelerin yanı sıra autoVerify="true" içeren bir Uygulama Bağlantısı beyanı örneği verilmiştir:

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <!-- Make sure you explicitly set android:autoVerify to "true". -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- If a user clicks on a link that uses the "http" scheme, your
             app should be able to delegate that traffic to "https". -->
        <!-- Do not include other schemes, as this will prevent verification. -->
        <data android:scheme="http" />
        <data android:scheme="https" />

        <!-- Include one or more domains that should be verified. -->
        <data android:host="www.example.com" />
        <data android:host="*.example.com" />
    </intent-filter>
</activity>

Kodla ilgili önemli noktalar

• AutoVerify: Uygulama Bağlantıları için android:autoVerify="true" özelliği gereklidir. Sisteme, uygulamanız ile <data> etiketlerinde belirtilen şemalar ve alanlar arasındaki ilişkilendirmeyi doğrulamaya çalışması gerektiğini bildirir. Doğrulanabilir olmasını istediğiniz her intent filtresine autoVerify="true" eklemeniz önerilir.
• Veri öğeleri: Her Uygulama Bağlantıları intent filtresi, doğrulanabilir web sitesi alanınızla eşleşen şemaları ve ana makine biçimlerini belirten bir veya daha fazla <data> öğesi içermelidir.
• Şemalar: Intent filtresi, hem http hem de https şemaları için <data> öğeleri içermelidir.

• Hosts: İsteğe bağlı olarak bir veya daha fazla ana makineyle eşleşecek <data> öğeleri ekleyebilirsiniz. Birden fazla alt alan adını (ör. *.example.com) eşleştirmek için joker karakter (*) kullanın. Sistem, her ana makineyi web sitenizdeki assetlinks.json dosyanızla doğrulamaya çalışır. Yol düzeyindeki yönlendirmelerin assetlinks.json dosyası tarafından işlenmesi gerektiğini unutmayın (aşağıdaki en iyi uygulamalar bölümüne bakın).

• Birden fazla barındırılan alan adı: Birden fazla barındırılan alan adı bildirirseniz sistem (Android 12 ve sonraki sürümlerde) her birini doğrulamaya çalışır. Herhangi bir ana makine doğrulanırsa uygulama, doğrulanmış ana makineden gelen bağlantılar için varsayılan işleyici olur. Android 11 ve önceki sürümlerde, tek bir ana makine bile doğrulanamazsa doğrulama başarısız olur.

• Birden fazla intent filtresi: Amacınız benzersiz URL'ler (ör. şema ve ana makinenin belirli bir kombinasyonu) bildirmek olduğunda ayrı filtreler oluşturmanız önemlidir. Bunun nedeni, aynı intent filtresindeki birden fazla <data> öğesinin, birleştirilmiş özelliklerinin tüm varyasyonlarını hesaba katmak için birleştirilmesidir.

Dikkat: Birden fazla etkinlik, aynı doğrulanmış App Link'e çözümlenen intent filtreleri içeriyorsa bağlantıyı hangi etkinliğin işleyeceği garanti edilmez.

Manifest filtre kurallarıyla ilgili dikkat edilmesi gereken noktalar

Android 15 ve sonraki sürümlerde Dinamik Uygulama Bağlantıları ile kullanılacak filtreler ayarlıyorsanız sunucu tarafındaki assetlinks.json dosyasında tanımlanan dinamik kuralların, uygulama manifestinizde statik olarak tanımladığınız URL kurallarının kapsamını genişletemeyeceğini unutmamanız önemlidir.

Bu nedenle, aşağıdaki yaklaşımı kullanmanızı öneririz:

• Uygulama manifestinizde, yalnızca şema ve alan adını beyan ederek mümkün olan en geniş kapsamı ayarlayın.
• Yol düzeyinde yönlendirme gibi daha ayrıntılı düzenlemeler için sunucu tarafındaki assetlinks.json kurallarını kullanın.

Bu ideal yapılandırmayla, uygulama manifestinde ayarladığınız geniş kapsama uyacağını bilerek assetlinks.json dosyasına gerektiğinde dinamik olarak yeni Uygulama Bağlantıları yolları ekleyebilirsiniz.

Birden fazla ana makine için uygulama bağlantılarını destekleme

Sistem, uygulamanın URL intent filtrelerinin veri öğelerinde belirtilen ana makineyi, söz konusu intent filtresindeki ilgili web alan adlarında barındırılan Digital Asset Links dosyalarına göre doğrulayabilmelidir. Doğrulama başarısız olursa sistem, Uygulama İçeriğine Derin Bağlantılar Oluşturma bölümünde açıklandığı gibi intent'i çözmek için varsayılan olarak standart davranışına döner. Ancak uygulama, uygulamanın diğer intent filtrelerinde tanımlanan URL kalıplarından herhangi biri için varsayılan işleyici olarak doğrulanabilir.

Not: Android 11 (API düzeyi 30) ve önceki sürümlerde sistem, manifest dosyasında tanımladığınız tüm ana makineler için eşleşen bir Digital Asset Links dosyası bulmadığı sürece uygulamanızı varsayılan işleyici olarak doğrulamaz.

Örneğin, aşağıdaki intent filtrelerine sahip bir uygulama, https://www.example.com için doğrulama adımını yalnızca https://www.example.com/.well-known/assetlinks.json konumunda assetlinks.json dosyası bulunursa ancak https://www.example.net/.well-known/assetlinks.json konumunda bulunmazsa geçer.

<application>

  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="http" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
    </intent-filter>
  </activity>
  <activity android:name="SecondActivity">
    <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
     <data android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

Not: Aynı intent filtresindeki tüm <data> öğeleri, birleştirilmiş özelliklerinin tüm varyasyonlarını hesaba katmak için birleştirilir. Örneğin, ilk intent filtresi yalnızca HTTPS şemasını bildiren bir <data> öğesi içerir. Ancak, intent filtresinin hem http://www.example.com hem de https://www.example.com'u desteklemesi için diğer <data> öğesiyle birleştirilir. Bu nedenle, belirli URI şemaları ve alan kombinasyonlarını tanımlamak istediğinizde ayrı intent filtreleri oluşturmanız gerekir.

Birden fazla alt alan adı için uygulama bağlantısı desteği

Digital Asset Links protokolü, intent filtrelerinizdeki alt alan adlarını benzersiz ve ayrı ana makineler olarak değerlendirir. Bu nedenle, intent filtreniz farklı alt alan adlarına sahip birden fazla ana makineyi listeliyorsa her alan adında geçerli bir assetlinks.json yayınlamanız gerekir. Örneğin, aşağıdaki intent filtresi, kabul edilen intent URL'si ana makineleri olarak www.example.com ve mobile.example.com'u içerir. Bu nedenle, geçerli bir assetlinks.json hem https://www.example.com/.well-known/assetlinks.json hem de https://mobile.example.com/.well-known/assetlinks.json adresinde yayınlanmalıdır.

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
      <data android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

Alternatif olarak, ana makine adınızı joker karakterle (ör. *.example.com) bildirirseniz assetlinks.json dosyanızı kök ana makine adında (example.com) yayınlamanız gerekir. Örneğin, aşağıdaki intent filtresine sahip bir uygulama, assetlinks.json dosyası https://example.com/.well-known/assetlinks.json konumunda yayınlandığı sürece example.com'un herhangi bir alt adı (ör. foo.example.com) için doğrulama adımını geçer:

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

Aynı alanla ilişkili birden fazla uygulama olup olmadığını kontrol etme

Her biri aynı alanla ilişkili birden fazla uygulama yayınlarsanız her bir uygulama başarıyla doğrulanabilir. Ancak uygulamalar, bir uygulamanın lite ve tam sürümlerinde olduğu gibi tam olarak aynı alan ana makinesini ve yolu çözebiliyorsa yalnızca en son yüklenen uygulama, bu alan için web intent'lerini çözebilir.

Böyle bir durumda, gerekli paket görünürlüğüne sahipseniz kullanıcının cihazında çakışan uygulamalar olup olmadığını kontrol edin. Ardından, uygulamanızda queryIntentActivities çağrısından elde edilen sonuçları içeren özel bir seçici iletişim kutusu gösterin. Kullanıcı, iletişim kutusunda görünen eşleşen uygulamalar listesinden tercih ettiği uygulamayı seçebilir.

Not: Kullanıcının daha sonra benzer bir web intent'i başlatıldığında yeniden seçim yapmak zorunda kalmaması için eşleşen yolu depolayabilirsiniz.

Android 14 ve önceki sürümler için Dinamik Uygulama Bağlantıları'nın geriye dönük uyumluluğu

assetlinks.json içindeki gelişmiş eşleşme kuralları ve <uri-relative-filter-group> kullanımı dahil olmak üzere dinamik uygulama bağlantısı özellikleri yalnızca Android 15 (API düzeyi 35) ve sonraki sürümlerde tam olarak desteklenir.

Android 14 (API düzeyi 34) ve önceki sürümlerde sistem, Uygulama Bağlantısı doğrulaması için yalnızca manifest dosyanızın <data> öğelerinde tanımlanan scheme ve host öğelerini dikkate alır. Yola özgü kurallar, hariç tutmalar ve assetlinks.json dosyasındaki dinamik güncellemeler uygulanmaz.

Yani manifestinizde yalnızca scheme ve host belirtiliyorsa uygulamanız, Android 15 ve sonraki sürümler için assetlinks.json dosyanızda tanımlanan yola özel kurallardan bağımsız olarak Android 14 ve önceki sürümlerde doğrulanmış alanın tüm yollarını beklenmedik bir şekilde yakalayabilir.

Daha eski Android sürümleri için derin bağlantı olmadan yapılandırılacak yedek strateji

Android 15 ve sonraki sürümlerde daha spesifik yollar için Dinamik Uygulama Bağlantıları'nı kullanmak istediğinizde uygulamanızın Android 14 ve önceki sürümlerde bir alanın tüm bağlantılarını işlemesini önlemek için manifest dosyanızın intent filtresine eşleşmeyen bir yol ekleyin. Bağlantılarınız için hiçbir zaman geçerli bir yol olmayacak bir android:path özelliğine sahip <data> öğesi ekleyin. Bu sayede intent filtresi, alt sürümlerdeki tüm yollarla eşleşmez.

Örnek:

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="http" />
        <data android:scheme="https" />
        <data android:host="www.example.com" />

        <!-- Add a non-matching path for backward compatibility -->
        <data android:path="/no_match_for_older_android_versions" />

        <uri-relative-filter-group android:allow="true">
          <data android:pathPattern="/.*"/>
        </uri-relative-filter-group>
    </intent-filter>
</activity>

<data android:path="/no_match_for_older_android_versions" /> özelliğini ekleyerek bu intent filtresinin Android 14 ve önceki sürümlerde gelen bağlantılarla eşleşmemesini sağlarsınız. Aynı zamanda, assetlinks.json kurallarınızdaki gelişmiş eşleşme kurallarına göre Android 15 ve sonraki sürümlerde Dinamik Uygulama Bağlantıları ile kullanılmak üzere alanın doğrulanmasına izin verirsiniz.

Uyarı: Android 15 ve sonraki sürümler için manifest dosyanızda <uri-relative-filter-group> yapılandırıyorsanız belirtilen ana makinede geçerli bir assetlinks.json dosyasına erişilebildiğinden emin olun. assetlinks.json dosyası eksik veya geçersizse Android 15 ve sonraki sürümlerde Uygulama Bağlantıları doğrulaması başarısız olur ve uygulamanız bu alan için hiçbir bağlantıyı işlemez. assetlinks.json dosyasının geçerli olduğu ancak dinamik yapılandırmanın eksik olduğu diğer durumlarda, uygulama, statik manifest beyanına göre Android 15 ve sonraki sürümlerde tüm yollar için açılabilir.

Mevcut uygulama bağlantılarının taşınması

Manifestinizde belirli yol kuralları (ör. android:pathPrefix) içeren Uygulama Bağlantılarınız varsa ve Android 15 ve sonraki sürümlerde Dinamik Uygulama Bağlantıları'nı kullanmaya başlamak istiyorsanız <uri-relative-filter-group> öğesini doğrudan mevcut intent filtrelerinize güvenle ekleyebilirsiniz.

Android 14 ve önceki sürümler <uri-relative-filter-group> öğesini yoksaydığı için mevcut Uygulama Bağlantılarınız, Android'in önceki sürümlerini çalıştıran cihazlarda şu anda olduğu gibi çalışmaya devam eder.

Ancak Android 15 ve sonraki sürümlerin "karma" yapılandırmayı nasıl değerlendirdiğini dikkatlice incelemeniz gerekir:

• İki katmanlı filtreleme: Android 15 ve sonraki sürümlerde sistem, intent filtrelerini bir bütün olarak değerlendirir. Bir URL, eski statik <data> etiketlerinizi veya <uri-relative-filter-group> dosyanızdaki geniş kuralları karşılıyorsa manifest kontrolünü geçer. URL bu ilk manifest kontrolünü geçtikten sonra sistem, ikinci bir ayrıntılı filtreleme katmanı olarak assetlinks.json dosyanızda tanımlanan dinamik kuralları uygular. Bu, sunucu tarafı JSON kurallarının, eşleşen URL'lerden hangilerinin uygulamayı açacağını belirlediği anlamına gelir.

Karma yapılandırma örneği:

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="https" />
    <data android:host="www.example.com" />

    <!-- Legacy rule: Android 14 and lower use this. Android 15 and higher
         also use this. -->
    <data android:pathPrefix="/store" />

    <!--
      Dynamic rule: Android 14 and lower ignore this. Android 15 and higher
      evaluate this as a union between all paths and the configuration
      specified in the assetlinks.json file. Make sure to apply further
      refinements in the assetlinks.json file to prevent all URL paths from
      opening in the app.
    -->
    <uri-relative-filter-group android:allow="true">
        <data android:pathPrefix="/" />
    </uri-relative-filter-group>
</intent-filter>