یک پیوند عمیق برای یک مقصد ایجاد کنید

در اندروید، پیوند عمیق پیوندی است که شما را مستقیماً به یک مقصد خاص در یک برنامه می برد.

مؤلفه Navigation به شما امکان می دهد دو نوع مختلف پیوند عمیق ایجاد کنید: صریح و ضمنی .

یک پیوند عمیق صریح ایجاد کنید

پیوند عمیق صریح یک نمونه واحد از یک پیوند عمیق است که از PendingIntent برای بردن کاربران به مکان خاصی در برنامه شما استفاده می کند. برای مثال، ممکن است یک پیوند عمیق صریح را به عنوان بخشی از یک اعلان یا یک ویجت برنامه نشان دهید.

هنگامی که کاربر برنامه شما را از طریق یک پیوند عمیق صریح باز می کند، پشته کار پاک می شود و با مقصد پیوند عمیق جایگزین می شود. هنگام تودرتو کردن نمودارها ، مقصد شروع از هر سطح از تودرتو - یعنی مقصد شروع از هر عنصر <navigation> در سلسله مراتب - نیز به پشته اضافه می شود. این به این معنی است که وقتی کاربر دکمه بازگشت را از مقصد پیوند عمیق فشار می‌دهد، از پشته ناوبری پشتیبان می‌گیرد، درست مثل اینکه از نقطه ورودی برنامه شما را وارد کرده است.

همانطور که در مثال زیر نشان داده شده است می توانید از کلاس NavDeepLinkBuilder برای ساخت PendingIntent استفاده کنید. توجه داشته باشید که اگر زمینه ارائه شده یک Activity نباشد، سازنده از PackageManager.getLaunchIntentForPackage() به عنوان فعالیت پیش‌فرض برای راه‌اندازی، در صورت موجود بودن، استفاده می‌کند.

کاتلین 

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

جاوا

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

به طور پیش‌فرض، NavDeepLinkBuilder پیوند عمیق صریح شما را به Activity راه‌اندازی پیش‌فرض که در مانیفست برنامه شما اعلام شده است، راه‌اندازی می‌کند. اگر NavHost شما در فعالیت دیگری است، باید نام مؤلفه آن را هنگام ایجاد لینک سازنده عمیق مشخص کنید:

کاتلین 

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

جاوا

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

اگر یک ComponentName دارید، می‌توانید آن را مستقیماً به سازنده ارسال کنید:

کاتلین 

val componentName = ...

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

جاوا

ComponentName componentName = ...;

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

اگر یک NavController موجود دارید، می‌توانید با استفاده از NavController.createDeepLink() یک پیوند عمیق نیز ایجاد کنید.

یک پیوند عمیق ضمنی ایجاد کنید

پیوند عمیق ضمنی به یک مقصد خاص در یک برنامه اشاره دارد. هنگامی که پیوند عمیق فراخوانی می شود - به عنوان مثال، وقتی کاربر روی یک پیوند کلیک می کند - Android می تواند برنامه شما را به مقصد مربوطه باز کند.

پیوندهای عمیق را می توان با URI، اقدامات قصد، و انواع MIME مطابقت داد. شما می توانید چندین نوع تطابق را برای یک پیوند عمیق مشخص کنید، اما توجه داشته باشید که تطبیق آرگومان URI ابتدا اولویت بندی می شود، سپس اقدام، و سپس نوع MIME.

در اینجا یک نمونه پیوند عمیق است که حاوی یک URI، یک اقدام و یک نوع 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>

همچنین می توانید از ویرایشگر ناوبری برای ایجاد یک پیوند عمیق ضمنی به یک مقصد به شرح زیر استفاده کنید:

  1. در برگه طراحی ویرایشگر ناوبری، مقصد پیوند عمیق را انتخاب کنید.
  2. در قسمت Deep Links پانل Attributes روی + کلیک کنید.

  3. در گفتگوی افزودن پیوند عمیق که ظاهر می شود، اطلاعات پیوند عمیق خود را وارد کنید.

    به موارد زیر توجه کنید:

    • URI های بدون طرح به عنوان http یا https در نظر گرفته می شوند. برای مثال، www.google.com با هر دو http://www.google.com و https://www.google.com مطابقت دارد.
    • متغیرهای پارامتر مسیر به شکل {placeholder_name} با یک یا چند کاراکتر مطابقت دارند. برای مثال، http://www.example.com/users/{id} با http://www.example.com/users/4 مطابقت دارد. مؤلفه Navigation با تطبیق نام مکان‌نماها با آرگومان‌های تعریف‌شده که برای مقصد پیوند عمیق تعریف شده‌اند، تلاش می‌کند مقادیر مکان‌نما را به انواع مناسب تجزیه کند. اگر هیچ آرگومانی با همان نام تعریف نشده باشد، یک نوع String پیش فرض برای مقدار آرگومان استفاده می شود. می توانید از علامت .* برای مطابقت دادن 0 یا بیشتر کاراکتر استفاده کنید.
    • متغیرهای پارامتر Query را می توان به جای یا همراه با پارامترهای مسیر استفاده کرد. برای مثال، http://www.example.com/users/{id}?myarg={myarg} با http://www.example.com/users/4?myarg=28 مطابقت دارد.
    • متغیرهای پارامتر پرس و جو برای متغیرهایی که با مقادیر پیش‌فرض یا تهی تعریف شده‌اند نیازی به مطابقت ندارند. برای مثال، http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2} با http://www.example.com/users/4?arg2=28 یا http://www.example.com/users/4?arg1=7 . این مورد در مورد پارامترهای مسیر صادق نیست. برای مثال، http://www.example.com/users?arg1=7&arg2=28 با الگوی بالا مطابقت ندارد زیرا پارامتر مسیر مورد نیاز ارائه نشده است.
    • پارامترهای پرس و جو خارجی بر تطابق URI پیوند عمیق تأثیر نمی گذارد. برای مثال، http://www.example.com/users/{id} با http://www.example.com/users/4?extraneousParam=7 مطابقت دارد، حتی اگر extraneousParam در الگوی URI تعریف نشده باشد.

  4. (اختیاری) تأیید خودکار را علامت بزنید تا از Google بخواهید تأیید کند که شما مالک URI هستید. برای اطلاعات بیشتر، به تأیید پیوندهای برنامه Android مراجعه کنید.

  5. روی افزودن کلیک کنید. یک نماد پیوند بالای مقصد انتخاب شده ظاهر می شود تا نشان دهد مقصد دارای پیوند عمیق است.

  6. روی تب Code کلیک کنید تا به نمای XML بروید. یک عنصر <deepLink> تودرتو به مقصد اضافه شده است:

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

برای فعال کردن پیوند عمیق ضمنی، باید به فایل manifest.xml برنامه خود نیز اضافه کنید. همانطور که در مثال زیر نشان داده شده است، یک عنصر <nav-graph> را به فعالیتی که به یک نمودار ناوبری موجود اشاره می کند، اضافه کنید:

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

هنگام ساخت پروژه، مؤلفه Navigation عنصر <nav-graph> را با عناصر <intent-filter> ایجاد شده جایگزین می‌کند تا با تمام پیوندهای عمیق در نمودار ناوبری مطابقت داشته باشد.

هنگام راه‌اندازی یک پیوند عمیق ضمنی، وضعیت پشته به این بستگی دارد که آیا Intent ضمنی با پرچم Intent.FLAG_ACTIVITY_NEW_TASK راه‌اندازی شده است یا خیر:

  • اگر پرچم تنظیم شده باشد، پشته کار پاک می شود و با مقصد پیوند عمیق جایگزین می شود. مانند پیوند عمیق صریح ، هنگام تودرتو کردن نمودارها ، مقصد شروع از هر سطح تودرتو - یعنی مقصد شروع از هر عنصر <navigation> در سلسله مراتب - نیز به پشته اضافه می شود. این به این معنی است که وقتی کاربر دکمه بازگشت را از مقصد پیوند عمیق فشار می‌دهد، از پشته ناوبری پشتیبان می‌گیرد، درست مثل اینکه از نقطه ورودی برنامه شما را وارد کرده است.
  • اگر پرچم تنظیم نشده باشد، در پشته وظیفه برنامه قبلی که پیوند عمیق ضمنی فعال شده است، می‌مانید. در این حالت، دکمه برگشت شما را به برنامه قبلی برمی گرداند، در حالی که دکمه بالا کار برنامه شما را در مقصد والد سلسله مراتبی در نمودار ناوبری شما شروع می کند.

مدیریت لینک های عمیق

اکیداً توصیه می شود هنگام استفاده از Navigation همیشه از launchMode پیش فرض standard استفاده کنید. هنگام استفاده از حالت راه اندازی standard ، Navigation به طور خودکار پیوندهای عمیق را با فراخوانی handleDeepLink() برای پردازش هر پیوند عمیق صریح یا ضمنی در Intent کنترل می کند. با این حال، اگر هنگام استفاده از یک launchMode جایگزین مانند singleTop از Activity دوباره استفاده شود، این به‌طور خودکار اتفاق نمی‌افتد. در این مورد، لازم است که handleDeepLink() به صورت دستی در onNewIntent() فراخوانی کنید، همانطور که در مثال زیر نشان داده شده است:

کاتلین 

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

جاوا 

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

منابع اضافی

برای کسب اطلاعات بیشتر در مورد ناوبری، به منابع زیر مراجعه کنید.

نمونه ها

Codelabs

ویدیوها