Aracılığıyla paylaş

Apple evrensel bağlantıları

  • Makale

Web sitesindeki bağlantıların mobil uygulamayı başlatması ve içeriği mobil uygulamada görüntülemesi için bir web sitesi ve mobil uygulama arasında bağlantı kurmak genellikle tercih edilir. Derin bağlama olarak da bilinen uygulama bağlama, mobil cihazın URL'ye yanıt vermesini ve URL ile temsil edilen bir mobil uygulamada içerik başlatmasını sağlayan bir tekniktir.

Apple platformlarında, derin bağlantılar evrensel bağlantılar olarak bilinir. Kullanıcı evrensel bir bağlantıya dokunduğunda, sistem safari veya web siteniz üzerinden yönlendirme yapmadan bağlantıyı doğrudan uygulamanıza yönlendirir. Bu bağlantılar gibi myappname://özel bir düzeni temel alabilir veya HTTP veya HTTPS düzenini kullanabilir. Örneğin, tarif web sitesindeki bir bağlantıya tıklanması, bu web sitesiyle ilişkili bir mobil uygulama açar ve kullanıcıya belirli bir tarif görüntüler. Uygulamanızın yüklü olmadığı kullanıcılar web sitenizdeki içeriğe yönlendirilir. Bu makale, HTTPS düzenini kullanan evrensel bağlantılara odaklanır.

.NET MAUI iOS uygulamaları evrensel bağlantıları destekler. Bunun için etki alanında bir dijital varlık bağlantıları JSON dosyası barındırmanız gerekir. Bu dosya, uygulamanızla olan ilişkiyi açıklar. Bu, Apple'ın kötü amaçlı uygulamaların uygulama bağlantılarınızı kesmesini önlemek için URL'yi işlemeye çalışan uygulamanın URL etki alanının sahipliğine sahip olduğunu doğrulamasını sağlar.

.NET MAUI iOS veya Mac Catalyst uygulamasında Apple evrensel bağlantılarını işleme işlemi aşağıdaki gibidir:

  • web sitenizde ilişkili bir etki alanı dosyası oluşturun ve barındırabilirsiniz. Daha fazla bilgi için bkz . İlişkili etki alanları dosyası oluşturma ve barındırma.
  • uygulamanıza ilişkili etki alanı yetkilendirmesini ekleyin. Daha fazla bilgi için bkz . Uygulamanıza ilişkili etki alanı yetkilendirmesini ekleme.
  • İlişkili etki alanları özelliğini Uygulamanızın Uygulama Kimliği'ne Apple Geliştirici Hesabınızda ekleyin. Daha fazla bilgi için bkz . Uygulama kimliğinize ilişkili etki alanları özelliğini ekleme.
  • Evrensel bir bağlantı uygulamanıza yönlendirildiğinde sistemin sağladığı kullanıcı etkinliği nesnesine yanıt vermek için uygulamanızı güncelleştirin. Daha fazla bilgi için bkz . Evrensel bağlantıya yanıt verme.

Daha fazla bilgi için bkz . uygulamaların ve web sitelerinin developer.apple.com içeriğinize bağlanmasına izin verme. Uygulamanız için özel URL düzeni tanımlama hakkında bilgi için bkz . developer.apple.com'da uygulamanız için özel URL düzeni tanımlama.

İlişkili etki alanları dosyası oluşturma ve barındırma

Bir web sitesini uygulamanızla ilişkilendirmek için, ilişkili bir etki alanı dosyasını web sitenizde barındırmanız gerekir. İlişkili etki alanı dosyası, etki alanınızda şu konumda barındırılması gereken bir JSON dosyasıdır: https://domain.name/.well-known/apple-app-site-association.

Aşağıdaki JSON, tipik bir ilişkili etki alanları dosyasının içeriğini gösterir:

{
    "activitycontinuation": {
        "apps": [ "85HMA3YHJX.com.companyname.myrecipeapp" ]
    },
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "85HMA3YHJX.com.companyname.myrecipeapp",
                "paths": [ "*", "/*" ]
            }
        ]
    }
}

apps ve appID anahtarları, web sitesinde kullanılabilen uygulamaların uygulama tanımlayıcılarını belirtmelidir. Bu anahtarların değerleri, uygulama tanımlayıcısı ön ekini ve paket tanımlayıcısını oluşturur.

Önemli

İlişkili etki alanı dosyasının geçerli bir sertifikayla ve yeniden yönlendirme olmadan kullanılarak https barındırılması gerekir.

Daha fazla bilgi için bkz . developer.apple.com'da ilişkili etki alanlarını destekleme.

Uygulamanıza ilişkili etki alanı yetkilendirmesini ekleme

Etki alanınızda ilişkili bir etki alanı dosyasını barındırdıktan sonra, ilişkili etki alanı yetkilendirmesini uygulamanıza eklemeniz gerekir. Bir kullanıcı uygulamanızı yüklediğinde, iOS ilişkili etki alanı dosyasını indirmeyi ve yetkilendirmenizdeki etki alanlarını doğrulamayı dener.

İlişkili etki alanları yetkilendirmesi, uygulamanın ilişkili olduğu etki alanlarının listesini belirtir. Bu yetkilendirme, uygulamanızdaki Entitlements.plist dosyasına eklenmelidir. iOS'ta yetkilendirme ekleme hakkında daha fazla bilgi için bkz . Yetkilendirmeler. Mac Catalyst'e yetkilendirme ekleme hakkında daha fazla bilgi için bkz . Yetkilendirmeler.

Yetkilendirme, türündeki com.apple.developer.associated-domainsArrayStringanahtarı kullanılarak tanımlanır:

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:recipe-app.com</string>
</array>

Bu yetkilendirme hakkında daha fazla bilgi için bkz . developer.apple.com'da ilişkili etki alanları yetkilendirmesi .

Alternatif olarak, proje dosyanızı (.csproj) değiştirerek yetkilendirmeyi bir <ItemGroup> öğeye ekleyebilirsiniz:

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios' Or $([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">

    <!-- For debugging, use '?mode=developer' for debug to bypass apple's CDN cache -->
    <CustomEntitlements
        Condition="$(Configuration) == 'Debug'"
        Include="com.apple.developer.associated-domains"
        Type="StringArray"
        Value="applinks:recipe-app.com?mode=developer" />

    <!-- Non-debugging, use normal applinks:url value -->
    <CustomEntitlements
        Condition="$(Configuration) != 'Debug'"
        Include="com.apple.developer.associated-domains"
        Type="StringArray"
        Value="applinks:recipe-app.com" />

</ItemGroup>

Bu örnekte, değerini etki alanınız için doğru değerle değiştirin applinks:recipe-app.com . Yalnızca istenen alt etki alanını ve en üst düzey etki alanını eklediğinizden emin olun. Yol ve sorgu bileşenlerini veya sondaki eğik çizgiyi (/ ) eklemeyin.

Not

iOS 14+ ve macOS 11+'da, uygulamalar artık dosyalar için apple-app-site-association doğrudan web sunucunuza istek göndermez. Bunun yerine, apple tarafından yönetilen içerik teslim ağına (CDN) ilişkili etki alanlarına ayrılmış istekler gönderir.

uygulama kimliğinize ilişkili etki alanları özelliğini ekleme

Uygulamanıza ilişkili etki alanı yetkilendirmesini ekledikten sonra, Apple Geliştirici Hesabınızdaki uygulamanızın Uygulama Kimliğine ilişkili etki alanları özelliğini eklemeniz gerekir. Uygulamanızda tanımlanan tüm yetkilendirmelerin, Apple Geliştirici Hesabınızdaki uygulamanızın Uygulama Kimliğine yetenek olarak eklenmesi gerektiğinden bu gereklidir.

uygulama kimliğinize ilişkili etki alanları özelliğini eklemek için:

  1. Web tarayıcısında Apple Geliştirici Hesabınızda oturum açın ve Sertifikalar, Kimlikler ve Profiller sayfasına gidin.

  2. Sertifikalar, Tanımlayıcılar ve Profiller sayfasında Tanımlayıcılar sekmesini seçin.

  3. Tanımlayıcılar sayfasında, uygulamanıza karşılık gelen Uygulama Kimliğini seçin.

  4. Uygulama Kimliği Yapılandırmanızı düzenleyin sayfasında İlişkili Etki Alanları özelliğini etkinleştirin ve kaydet düğmesini seçin:

    Screenshot of enabling the associated domains capability in the Apple Developer Portal.

  5. Uygulama Özelliklerini Değiştir iletişim kutusunda Onayla düğmesini seçin.

Uygulamanızın Uygulama Kimliğini güncelleştirdikten sonra güncelleştirilmiş bir sağlama profili oluşturup indirmeniz gerekir.

Not

Daha sonra ilişkili etki alanı yetkilendirmesini uygulamanızdan kaldırırsanız, Apple Geliştirici Hesabınızda Uygulama Kimliğinizin yapılandırmasını güncelleştirmeniz gerekir.

Bir kullanıcı evrensel bağlantıyı etkinleştirdiğinde, iOS ve Mac Catalyst uygulamanızı başlatır ve bir NSUserActivity nesne gönderir. Bu nesne, uygulamanızın nasıl başlatıldığını belirlemek ve hangi eylemin gerçekleştirileceğini belirlemek için sorgulanabilir. Bu, ve ContinueUserActivity yaşam döngüsü temsilcilerinde FinishedLaunching gerçekleştirilmelidir. Uygulama FinishedLaunching başlatıldığında temsilci çağrılır ve ContinueUserActivity uygulama çalışırken veya askıya alınırken temsilci çağrılır. Yaşam döngüsü temsilcileri hakkında daha fazla bilgi için bkz . Platform yaşam döngüsü olayları.

Çağrılan bir iOS yaşam döngüsü temsilcisine yanıt vermek için sınıfınızın yöntemindeki MauiAppBuilder nesnede CreateMauiapp yöntemini çağırınConfigureLifecycleEvents.MauiProgram Ardından nesnesinde ILifecycleBuilder yöntemini çağırın AddiOS ve gerekli temsilci için bir işleyici kaydeden öğesini belirtin Action :

using Microsoft.Maui.LifecycleEvents;
using Microsoft.Extensions.Logging;

namespace MyNamespace;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            })
            .ConfigureLifecycleEvents(lifecycle =>
            {
#if IOS || MACCATALYST
                lifecycle.AddiOS(ios =>
                {
                    // Universal link delivered to FinishedLaunching after app launch.
                    ios.FinishedLaunching((app, data) => HandleAppLink(app.UserActivity));

                    // Universal link delivered to ContinueUserActivity when the app is running or suspended.
                    ios.ContinueUserActivity((app, userActivity, handler) => HandleAppLink(userActivity));

                    // Only required if using Scenes for multi-window support.
                    if (OperatingSystem.IsIOSVersionAtLeast(13) || OperatingSystem.IsMacCatalystVersionAtLeast(13))
                    {
                        // Universal link delivered to SceneWillConnect after app launch
                        ios.SceneWillConnect((scene, sceneSession, sceneConnectionOptions)
                            => HandleAppLink(sceneConnectionOptions.UserActivities.ToArray()
                                .FirstOrDefault(a => a.ActivityType == Foundation.NSUserActivityType.BrowsingWeb)));

                        // Universal link delivered to SceneContinueUserActivity when the app is running or suspended
                        ios.SceneContinueUserActivity((scene, userActivity) => HandleAppLink(userActivity));
                    }
                });
#endif
            });

#if DEBUG
        builder.Logging.AddDebug();
#endif

        return builder.Build();
    }

#if IOS || MACCATALYST
    static bool HandleAppLink(Foundation.NSUserActivity? userActivity)
    {
        if (userActivity is not null && userActivity.ActivityType == Foundation.NSUserActivityType.BrowsingWeb && userActivity.WebPageUrl is not null)
        {
            HandleAppLink(userActivity.WebPageUrl.ToString());
            return true;
        }
        return false;
    }
#endif

    static void HandleAppLink(string url)
    {
        if (Uri.TryCreate(url, UriKind.RelativeOrAbsolute, out var uri))
            App.Current?.SendOnAppLinkRequestReceived(uri);
    }
}

iOS evrensel bir bağlantının sonucu olarak uygulamanızı açtığında, nesnenin NSUserActivity değerine BrowsingWebsahip bir ActivityType özelliği olur. Etkinlik nesnesinin WebPageUrl özelliği, kullanıcının erişmek istediği URL'yi içerir. URL, yöntemiyle SendOnAppLinkRequestReceived sınıfınıza App geçirilebilir.

Not

Uygulamanızda çok pencereli destek için Sahneler kullanmıyorsanız, Sahne yöntemleri için yaşam döngüsü işleyicilerini atlayabilirsiniz.

Sınıfınızda App URL'yi OnAppLinkRequestReceived almak ve işlemek için yöntemini geçersiz kılın:

namespace MyNamespace;

public partial class App : Application
{
    public App()
    {
        InitializeComponent();

        MainPage = new AppShell();
    }

    protected override async void OnAppLinkRequestReceived(Uri uri)
    {
        base.OnAppLinkRequestReceived(uri);

        // Show an alert to test that the app link was received.
        await Dispatcher.DispatchAsync(async () =>
        {
            await Windows[0].Page!.DisplayAlert("App link received", uri.ToString(), "OK");
        });

        Console.WriteLine("App link: " + uri.ToString());
    }
}

Yukarıdaki örnekte geçersiz kılma, OnAppLinkRequestReceived uygulama bağlantısı URL'sini görüntüler. Uygulamada, uygulama bağlantısı herhangi bir istem, oturum açma veya diğer kesintiler olmadan kullanıcıları DOĞRUDAN URL ile temsil edilen içeriğe götürmelidir. Bu nedenle geçersiz kılma, OnAppLinkRequestReceived URL tarafından temsil edilen içeriğe gezintinin çağrıldığı konumdur.

Uyarı

Evrensel bağlantılar uygulamanıza olası bir saldırı vektörünü sunar, bu nedenle tüm URL parametrelerini doğruladığınızdan ve hatalı biçimlendirilmiş URL'leri attığınızdan emin olun.

Daha fazla bilgi için bkz . developer.apple.com'da uygulamanızda Evrensel Bağlantıları Destekleme.

Önemli

iOS'ta evrensel bağlantılar Simülatör yerine bir cihazda test edilmelidir.

Evrensel bağlantıyı test etmek için Notlar uygulamanıza bir bağlantı yapıştırın ve bağlantıyı takip etme seçeneklerinizi keşfetmek için uzun basın (iOS'ta) veya control tuşuna (macOS'ta) tıklayın. Evrensel bağlantıların doğru yapılandırılması koşuluyla, uygulamada ve Safari'de açma seçeneği görüntülenir. Seçiminiz, bu etki alanından evrensel bağlantıları takip ederken cihazınızdaki varsayılan davranışı ayarlar. Bu varsayılan seçimi değiştirmek için adımları yineleyin ve farklı bir seçim yapın.

Not

SAFARI'ye URL girildiğinde uygulama hiçbir zaman açılmaz. Bunun yerine Safari bu eylemi doğrudan gezinti olarak kabul eder. Doğrudan oraya gittikten sonra bir kullanıcının etki alanınızda olması koşuluyla, sitenizde uygulamanızı açmak için bir başlık gösterilir.

iOS'ta, evrensel bağlantılarınızı geliştirici ayarlarında ilişkili etki alanları tanılama testleriyle test edebilirsiniz:

  1. Ayarlar'da geliştirici modunu etkinleştirin. Daha fazla bilgi için bkz . developer.apple.com bir cihazda Geliştirici Modunu Etkinleştirme.
  2. Ayarlar Geliştirici'de Evrensel Bağlantılar'a gidin ve İlişkili Etki Alanları Geliştirme'yi etkinleştirin. >
  3. Tanılama'yı açın ve URL'nizi yazın. Ardından, bağlantının yüklü bir uygulama için geçerli olup olmadığına ilişkin geri bildirim alırsınız.

Genellikle geçersiz evrensel bağlantılar, yanlış yapılandırılmanızın applinks bir sonucudur.

Sorun giderme önerileri için bkz . developer.apple.com evrensel bağlantılarda hata ayıklama.