آزمایش پیوندهای برنامه

هنگام پیاده‌سازی ویژگی پیونددهی برنامه، باید عملکرد پیونددهی را آزمایش کنید تا مطمئن شوید سیستم می‌تواند برنامه‌تان را با وب‌سایت‌هایتان مرتبط کند و درخواست‌های نشانی وب را همان‌طور که انتظار دارید مدیریت کند.

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

بخش‌های زیر نحوه آزمایش کردن درستی‌سنجی «پیوندهای برنامه» را به‌صورت دستی شرح می‌دهد. اگر ترجیح می‌دهید، می‌توانید درستی‌سنجی را از ابزار «پیوندهای عمیق Play» یا «دستیار پیوندهای برنامه Android Studio» آزمایش کنید.

تأیید فهرست میزبان‌ها برای درستی‌سنجی

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

• مشخصه android:scheme با مقدار http یا https
• مشخصه android:host با الگوی نشانی وب دامنه
• ‫android.intent.action.VIEW عنصر کنش
• عنصر دسته android.intent.category.BROWSABLE

از این فهرست برای بررسی اینکه فایل JSON «پیوندهای دارایی دیجیتال» در هر میزبان و زیردامنه نام‌گذاری‌شده ارائه شده است استفاده کنید.

تأیید فایل‌های «پیوندهای دارایی دیجیتال»

برای هر وب‌سایت، از Digital Asset Links API استفاده کنید تا مطمئن شوید که فایل JSON «پیوندهای دارایی دیجیتال» به‌درستی میزبانی و تعریف شده است:

https://digitalassetlinks.googleapis.com/v1/statements:list?
   source.web.site=https://<var>domain.name</var>:<var>optional_port</var>&amp;
   relation=delegate_permission/common.handle_all_urls

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

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://www.example.com&relation=delegate_permission/common.handle_all_urls&return_relation_extensions=true

بررسی خط‌مشی‌های پیوند

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

adb shell dumpsys package domain-preferred-apps

فرمان زیر نیز همین کار را انجام می‌دهد:

adb shell dumpsys package d

این فرمان فهرستی از هر کاربر یا نمایه تعریف‌شده در دستگاه را برمی‌گرداند، که قبل‌از آن سرایندی با قالب زیر قرار دارد:

App linkages for user 0:

پس‌از این سرصفحه، خروجی از قالب زیر برای فهرست کردن تنظیمات مدیریت پیوند برای آن کاربر استفاده می‌کند:

Package: com.android.vending
Domains: play.google.com market.android.com
Status: always : 200000002

این فهرست نشان می‌دهد کدام برنامه‌ها با کدام دامنه‌ها برای آن کاربر مرتبط هستند:

• Package - برنامه‌ای را با نام بسته‌اش، همان‌طور که در مانیفست آن اعلام شده است، شناسایی می‌کند.
• Domains - فهرست کامل میزبان‌هایی را که این برنامه پیوندهای وب آن‌ها را مدیریت می‌کند نشان می‌دهد، و از فاصله‌های خالی به‌عنوان جداکننده استفاده می‌کند.
• Status - تنظیم فعلی مدیریت پیوند را برای این برنامه نشان می‌دهد. برنامه‌ای که درستی‌سنجی را گذرانده باشد و مانیفست آن حاوی android:autoVerify="true" باشد، وضعیت always را نشان می‌دهد. عدد شانزده‌شانزدهی بعداز این وضعیت به سابقه سیستم Android از اولویت‌های پیوند برنامه کاربر مربوط است. این مقدار نشان نمی‌دهد که درستی‌سنجی موفقیت‌آمیز بوده است یا نه.

نمونه آزمایشی

برای اینکه درستی‌سنجی پیوند برنامه موفقیت‌آمیز باشد، سیستم باید بتواند برنامه‌تان را با هریک از وب‌سایت‌هایی که در فیلتر قصد مشخصی که معیارهای پیوندهای برنامه را برآورده می‌کند درستی‌سنجی کند. نمونه زیر پیکربندی مانیفست را با چند پیوند برنامه تعریف‌شده نشان می‌دهد:

<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>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
            <data android:host="www.example2.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="account.example.com" />
        </intent-filter>
    </activity>

      <activity android:name="ThirdActivity">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <data android:scheme="https" />
            <data android:host="map.example.com" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="market" />
            <data android:host="example.com" />
        </intent-filter>
      </activity>

</application>

فهرست میزبان‌هایی که پلاتفرم تلاش می‌کند از مانیفست قبلی درستی‌سنجی کند:

www.example.com
mobile.example.com
www.example2.com
account.example.com

فهرست میزبان‌هایی که پلاتفرم تلاش نمی‌کند از مانیفست قبلی درستی‌سنجی کند:

map.example.com (it does not have android.intent.category.BROWSABLE)
market://example.com (it does not have either an "http" or "https" scheme)

برای کسب اطلاعات بیشتر درباره فهرست‌های عبارت، ایجاد فهرست عبارت را ببینید.

تشخیص وضوح پیوند با پرچم debug-link

از Android 17 به بعد، می‌توانید از پرچم --debug-link با فرمان مدیر فعالیت (am start) برای تشخیص نحوه حل‌وفصل یک نشانی وب خاص توسط سیستم استفاده کنید. این ابزار تفکیک دقیقی از برنامه‌های نامزد که با هدف مطابقت داشتند، به‌همراه قوانین خاص از مانیفست برنامه و فایل assetlinks.json (برای «پیوندهای پویای برنامه») که درطول حل‌وفصل ارزیابی شده‌اند ارائه می‌دهد.

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

adb shell am start --debug-link -a android.intent.action.VIEW -d "https://xyz.com/foo"

خروجی عیب‌یابی زیر عنوان App Link Resolution Debug چاپ می‌شود و شامل بخش‌های زیر است تا به شما در درک فرایند حل‌وفصل کمک کند:

• جزئیات هدف: هر برنامه نامزد منطبق را براساس نام بسته و فعالیت هدف آن شناسایی می‌کند.
• تطابق فیلتر قصد (AndroidManifest.xml): نشان می‌دهد کدام مشخصه‌های ایستا در فیلتر قصد مانیفست (مانند scheme، host، path، pathPrefix، یا pathPattern) با URI مطابقت دارد.
• درستی‌سنجی پیوند برنامه: وضعیت فعلی درستی‌سنجی دامنه را نشان می‌دهد (مانند STATE_SUCCESS).
• پیوندهای پویای برنامه: اگر برنامه از قوانین مطابقت «پیوندهای پویای برنامه» در فایل assetlinks.json خود استفاده کند، این بخش همه قوانینی را که درمقابل شناسه منبع یکسان ارزیابی شده‌اند فهرست می‌کند. هر قانون نشان‌دهنده فیلترهای URI منطبق (مانند پیشوندها یا الگوهای مسیر) و یک فیلد allow است:
  • allow = 0: قانون مجاز/گنجاندن (allow: true). اگر این قانون مطابقت داشته باشد، برنامه مجاز است URI را باز کند.
  • allow = 1: قانون مسدود کردن/مستثنی کردن (allow: false / exclude: true). اگر این قانون مطابقت داشته باشد، برنامه از باز کردن URI منع می‌شود.
  • توجه: رشته فیلتر خالی (filter =) نشان‌دهنده پیشوند مسیر خالی است که با همه مسیرهای تحت دامنه مطابقت دارد (به‌عنوان نویسه عام یا همه‌گیر عمل می‌کند).

برونداد اشکال‌زدایی نمونه

برنامه‌ای (com.example.xyzapp) را درنظر بگیرید که با دامنه https://xyz.com مرتبط است و قوانین پویایی را در فایل assetlinks.json خود تعریف می‌کند تا /foo* را مستثنی کند و درعین‌حال به همه مسیرهای دیگر اجازه دهد:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.xyzapp",
      "sha256_cert_fingerprints": ["..."]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"/": "/foo*", "exclude": true},
          {"/": "*"}
        ]
      }
    }
  }
]

هنگام تشخیص خرابی نشانی وب https://xyz.com/foo بااستفاده از --debug-link:

adb shell am start --debug-link -a android.intent.action.VIEW -d "https://xyz.com/foo"

فرمان، تفکیک عیب‌یابی زیر را برونداد می‌کند:

--- App Link Resolution Debug ---

URI: https://xyz.com/foo
Resolution: Ambiguous (Multiple apps or Browser fallback)
This usually happens when multiple apps can handle the link and no default is set.

All Matching Candidates:

Target:
  Package: com.example.xyzapp
  Activity: com.example.xyzapp.MainActivity

  Intent Filter Match (AndroidManifest.xml)
    Scheme: 'https' matched android:scheme="https"
    Host: 'xyz.com' matched android:host="xyz.com"

App Link Verification:
  Verification status: STATE_SUCCESS
  Dynamic App Links:
    -> Matched Rule 0: UriRelativeFilterGroup { allow = 1, uri_filters = {UriRelativeFilter { uriPart = PATH, patternType = PREFIX, filter = /foo }},  }
    -> Matched Rule 1: UriRelativeFilterGroup { allow = 0, uri_filters = {UriRelativeFilter { uriPart = PATH, patternType = PREFIX, filter =  }},  }

Target:
  Package: org.chromium.webview_shell
  Activity: org.chromium.webview_shell.WebViewBrowserActivity

  Intent Filter Match (AndroidManifest.xml)
    Scheme: 'https' matched android:scheme="https"

---------------------------------

Starting: Intent { act=android.intent.action.VIEW dat=https://xyz.com/foo }

در این مثال، سیستم دو قانون «پیوند برنامه پویا» را از assetlinks.json ارزیابی کرد:

• قانون ۰ (allow = 1، filter = /foo): تولیدشده از {"/": "/foo*", "exclude": true}، این قانون مستثنی‌سازی است (allow: false) که نشانی‌های وب را که با پیشوند مسیر /foo شروع می‌شوند مسدود می‌کند.
• قانون ۱ (allow = 0، filter =): این قانون که از {"/": "*"} تولید شده است، یک قانون گنجاندن (allow: true) با پیشوند مسیر خالی (filter =) است که با همه مسیرهای تحت xyz.com مطابقت دارد (همه را شامل می‌شود).

نحوه حل‌وفصل در این سناریو:

1. هر دو قانون ۰ و قانون ۱ با نشانی وب https://xyz.com/foo مطابقت دارند.
2. قوانین «پیوند برنامه پویا» به‌ترتیب متوالی از بالا به پایین ارزیابی می‌شوند (اولین قانون منطبق برنده می‌شود).
3. چون قانون ۰ ابتدا در فهرست عبارت‌ها نشان داده می‌شود و قانون استثناسازی (allow = 1) است، بر قانون مجاز عمومی (قانون ۱) اولویت دارد.
4. بنابراین، برنامه از رسیدگی به https://xyz.com/foo مستثنی می‌شود و باعث می‌شود سیستم به مرورگر برگردد یا کادر گفتگوی ابهام‌زدایی نمایش دهد.