ایجاد پیوندهای عمیق به محتوای برنامه

هنگامی که یک پیوند کلیک شده یا درخواست برنامه‌ای یک URI وب را فراخوانی می‌کند، سیستم Android هر یک از اقدامات زیر را به ترتیب متوالی انجام می‌دهد تا زمانی که درخواست موفق شود:

1. اگر برنامه مورد نظر کاربر را که می‌تواند URI را مدیریت کند، باز کنید.
2. تنها برنامه موجودی را که می‌تواند URI را مدیریت کند باز کنید.
3. به کاربر اجازه دهید یک برنامه را از یک گفتگو انتخاب کند.

مراحل زیر را برای ایجاد و آزمایش پیوندهای محتوای خود دنبال کنید. همچنین می‌توانید از App Links Assistant در Android Studio برای افزودن پیوندهای برنامه Android استفاده کنید.

توجه: با شروع در Android 12 (سطح API 31)، یک هدف وب عمومی تنها در صورتی به فعالیتی در برنامه شما تبدیل می‌شود که برنامه شما برای دامنه خاص موجود در آن هدف وب تأیید شده باشد. اگر برنامه شما برای دامنه تأیید نشده باشد، هدف وب به برنامه مرورگر پیش‌فرض کاربر حل می‌شود.

فیلترهای هدف را برای پیوندهای ورودی اضافه کنید

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

<action>

عمل قصد ACTION_VIEW را مشخص کنید تا بتوان از جستجوی Google به فیلتر قصد دسترسی داشت.

<data>

یک یا چند تگ <data> اضافه کنید، که هر کدام نشان دهنده یک فرمت URI است که به فعالیت حل می شود. حداقل، تگ <data> باید دارای ویژگی android:scheme باشد.

می‌توانید برای اصلاح بیشتر نوع URI که فعالیت می‌پذیرد، ویژگی‌های بیشتری اضافه کنید. به عنوان مثال، ممکن است چندین فعالیت داشته باشید که URI های مشابهی را می پذیرند، اما به سادگی بر اساس نام مسیر متفاوت هستند. در این مورد، از ویژگی android:path یا pathPattern یا pathPrefix انواع آن استفاده کنید تا مشخص کنید که سیستم باید کدام فعالیت را برای مسیرهای URI مختلف باز کند.

<category>

شامل دسته بندی BROWSABLE . برای اینکه فیلتر قصد از طریق مرورگر وب قابل دسترسی باشد، لازم است. بدون آن، کلیک کردن روی پیوند در مرورگر نمی‌تواند به برنامه شما حل شود.

همچنین شامل دسته DEFAULT . این به برنامه شما اجازه می دهد تا به مقاصد ضمنی پاسخ دهد. بدون این، فعالیت فقط در صورتی می تواند شروع شود که هدف نام مؤلفه برنامه شما را مشخص کند.

قطعه XML زیر نشان می دهد که چگونه می توانید یک فیلتر قصد در مانیفست خود برای پیوند عمیق مشخص کنید. URI های “example://gizmos” و “http://www.example.com/gizmos” هر دو به این فعالیت پاسخ می دهند.

<activity
    android:name="com.example.android.GizmosActivity"
    android:label="@string/title_gizmos" >
    <intent-filter android:label="@string/filter_view_http_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "http://www.example.com/gizmos” -->
        <data android:scheme="http"
              android:host="www.example.com"
              android:pathPrefix="/gizmos" />
        <!-- note that the leading "/" is required for pathPrefix-->
    </intent-filter>
    <intent-filter android:label="@string/filter_view_example_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "example://gizmos” -->
        <data android:scheme="example"
              android:host="gizmos" />
    </intent-filter>
</activity>

توجه داشته باشید که دو فیلتر intent فقط بر اساس عنصر <data> متفاوت هستند. اگرچه ممکن است چندین عنصر <data> را در یک فیلتر قرار دهید، مهم است که فیلترهای جداگانه ایجاد کنید زمانی که قصد دارید URL های منحصر به فرد را اعلام کنید (مانند ترکیب خاصی از scheme و host )، زیرا چندین عنصر <data> در فیلتر قصد یکسان در واقع با هم ادغام می شوند تا تمام تغییرات ویژگی های ترکیبی آنها را در نظر بگیرند. برای مثال موارد زیر را در نظر بگیرید:

<intent-filter>
  ...
  <data android:scheme="https" android:host="www.example.com" />
  <data android:scheme="app" android:host="open.my.app" />
</intent-filter>

ممکن است به نظر برسد که این فقط از https://www.example.com و app://open.my.app پشتیبانی می کند. با این حال، در واقع از این دو پشتیبانی می کند، به علاوه این موارد: app://www.example.com و https://open.my.app .

احتیاط: اگر چندین فعالیت حاوی فیلترهای هدف هستند که به همان پیوند برنامه Android تأیید شده حل می‌شوند، هیچ تضمینی وجود ندارد که کدام فعالیت پیوند را مدیریت می‌کند.

هنگامی که فیلترهای هدف را با URI برای محتوای فعالیت به مانیفست برنامه خود اضافه کردید، Android می‌تواند هر Intent که دارای URI منطبق است به برنامه شما در زمان اجرا هدایت کند.

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

خواندن داده ها از مقاصد ورودی

هنگامی که سیستم فعالیت شما را از طریق فیلتر قصد شروع می کند، می توانید از داده های ارائه شده توسط Intent برای تعیین آنچه باید ارائه دهید استفاده کنید. متدهای getData() و getAction() را فراخوانی کنید تا داده ها و اقدامات مرتبط با Intent ورودی را بازیابی کنید. شما می‌توانید این روش‌ها را در هر زمانی در طول چرخه حیات فعالیت فراخوانی کنید، اما معمولاً باید این روش‌ها را در هنگام تماس‌های اولیه مانند onCreate() یا onStart() انجام دهید.

در اینجا یک قطعه وجود دارد که نحوه بازیابی داده ها از یک Intent را نشان می دهد:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    val action: String? = intent?.action
    val data: Uri? = intent?.data
}

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent = getIntent();
    String action = intent.getAction();
    Uri data = intent.getData();
}

این بهترین شیوه ها را برای بهبود تجربه کاربر دنبال کنید:

• پیوند عمیق باید کاربران را مستقیماً بدون هیچ گونه درخواست، صفحات بینابینی یا لاگین به محتوا هدایت کند. اطمینان حاصل کنید که کاربران می توانند محتوای برنامه را ببینند حتی اگر قبلاً برنامه را باز نکرده باشند. اشکالی ندارد که کاربران را در مورد تعاملات بعدی یا زمانی که برنامه را از راه‌انداز باز می‌کنند، راهنمایی کنید.
• دستورالعمل طراحی شرح داده شده در Navigation with Back and Up را دنبال کنید تا برنامه شما با انتظارات کاربران برای پیمایش به عقب پس از ورود به برنامه شما از طریق پیوند عمیق مطابقت داشته باشد.

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

می‌توانید از پل اشکال‌زدایی Android با ابزار مدیریت فعالیت (am) استفاده کنید تا آزمایش کنید که URIهای فیلتر قصدی که برای پیوند عمیق مشخص کرده‌اید، به فعالیت برنامه صحیح پاسخ می‌دهند. می توانید دستور adb را بر روی یک دستگاه یا شبیه ساز اجرا کنید.

نحو کلی برای آزمایش URI فیلتر قصد با adb به این صورت است:

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d <URI> <PACKAGE>

به عنوان مثال، دستور زیر سعی می کند یک فعالیت برنامه هدف را که با URI مشخص شده مرتبط است، مشاهده کند.

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d "example://gizmos" com.example.android

بیانیه مانیفست و کنترل‌کننده قصدی که در بالا تنظیم کرده‌اید، ارتباط بین برنامه شما و یک وب‌سایت و آنچه را که باید با پیوندهای ورودی انجام دهید را مشخص می‌کند. با این حال، برای اینکه سیستم برنامه شما را به‌عنوان کنترل‌کننده پیش‌فرض مجموعه‌ای از URI ها در نظر بگیرد، باید از سیستم نیز درخواست کنید که این اتصال را تأیید کند. درس بعدی نحوه اجرای این تأیید را توضیح می دهد.

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

• Intents و Intent Filters
• به برنامه های دیگر اجازه دهید تا فعالیت شما را شروع کنند
• پیوندهای برنامه Android را با Android Studio اضافه کنید