درستی‌سنجی پیوندهای برنامه

وقتی android:autoVerify="true" در حداقل یکی از فیلترهای قصد برنامه‌تان وجود داشته باشد، نصب برنامه‌تان در دستگاهی که Android نسخه ۶.۰ (سطح میانای برنامه‌سازی کاربردی ۲۳) یا بالاتر را اجرا می‌کند باعث می‌شود سیستم به‌طور خودکار میزبان‌های مرتبط با نشانی‌های وب را در فیلترهای قصد برنامه‌تان درستی‌سنجی کند. در Android 12 و نسخه‌های بالاتر، می‌توانید فرایند درستی‌سنجی را به‌صورت دستی فراخوانی کنید تا منطق درستی‌سنجی را آزمایش کنید.

درستی‌سنجی خودکار

درستی‌سنجی خودکار سیستم شامل موارد زیر است:

1. سیستم همه فیلترهای قصدی را که شامل هریک از موارد زیر باشد بازرسی می‌کند:
   • کنش: android.intent.action.VIEW
   • دسته‌ها: android.intent.category.BROWSABLE و android.intent.category.DEFAULT
   • طرح داده: http یا https
2. برای هر نام میزبان منحصربه‌فردی که در فیلترهای قصد پیدا می‌شود، Android وب‌سایت‌های مربوطه را برای فایل «پیوندهای دارایی دیجیتال» در https://hostname/.well-known/assetlinks.json پُرسمان می‌کند.

پس‌از اینکه فهرست وب‌سایت‌های مرتبط با برنامه‌تان را تأیید کردید و مطمئن شدید فایل JSON میزبانی‌شده معتبر است، برنامه را در دستگاهتان نصب کنید. حداقل ۲۰ ثانیه صبر کنید تا فرایند درستی‌سنجی ناهمگام تکمیل شود. از فرمان زیر استفاده کنید تا بررسی کنید آیا سیستم برنامه‌تان را درستی‌سنجی کرده است و خط‌مشی‌های صحیح مدیریت پیوند را تنظیم کرده است یا نه:

adb shell am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "http://domain.name:optional_port"

درستی‌سنجی دستی

از Android نسخه ۱۲ به بعد، می‌توانید درستی‌سنجی دامنه را برای برنامه‌ای که در دستگاه نصب شده است به‌صورت دستی فراخوانی کنید. صرف‌نظر از اینکه برنامه‌تان Android 12 را هدف قرار می‌دهد یا نه، می‌توانید این فرایند را انجام دهید.

برقراری اتصال اینترنت

برای انجام درستی‌سنجی دامنه، دستگاه آزمایشی شما باید به اینترنت متصل باشد.

پشتیبانی از فرایند به‌روزشده درستی‌سنجی دامنه

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

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

adb shell am compat enable 175408749 PACKAGE_NAME

بازنشانی کردن وضعیت «پیوندهای برنامه Android» در دستگاه

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

adb shell pm set-app-links --package PACKAGE_NAME 0 all

این فرمان دستگاه را در همان وضعیتی قرار می‌دهد که قبل‌از انتخاب برنامه‌های پیش‌فرض برای هر دامنه‌ای توسط کاربر در آن قرار دارد.

فراخوانی فرایند درستی‌سنجی دامنه

پس‌از بازنشانی کردن وضعیت «پیوندهای برنامه Android» در دستگاه، می‌توانید خود درستی‌سنجی را انجام دهید. برای انجام این کار، فرمان زیر را در پنجره پایانه اجرا کنید:

adb shell pm verify-app-links --re-verify PACKAGE_NAME

بررسی نتایج درستی‌سنجی

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

adb shell pm get-app-links PACKAGE_NAME

برونداد این فرمان شبیه به مورد زیر است:

com.example.pkg:
    ID: 01234567-89ab-cdef-0123-456789abcdef
    Signatures: [***]
    Domain verification state:
      example.com: verified
      sub.example.com: legacy_failure
      example.net: verified
      example.org: 1026

دامنه‌هایی که درستی‌سنجی را با موفقیت پشت سر می‌گذارند، وضعیت درستی‌سنجی دامنه verified را دارند. هر وضعیت دیگری نشان می‌دهد که درستی‌سنجی دامنه انجام نشده است. به‌ویژه، وضعیت none نشان می‌دهد که ممکن است نماینده درستی‌سنجی هنوز فرایند درستی‌سنجی را تکمیل نکرده باشد.

فهرست زیر مقادیر برگشتی احتمالی را نشان می‌دهد که درستی‌سنجی دامنه می‌تواند برای دامنه موردنظر برگرداند:

none

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

verified

دامنه باموفقیت برای برنامه اعلام‌کننده تأیید شده است.

approved

دامنه به‌اجبار تأیید شد، معمولاً با اجرای فرمان پوسته.

denied

دامنه به‌اجبار رد شده است، معمولاً با اجرای فرمان پوسته.

migrated

سیستم نتیجه فرایند قبلی را که از درستی‌سنجی دامنه قدیمی استفاده می‌کرد حفظ کرد.

restored

دامنه پس‌از اینکه کاربر بازیابی داده را انجام داد تأیید شد. فرض بر این است که دامنه قبلاً تأیید شده است.

legacy_failure

دامنه توسط درستی‌سنج قدیمی رد شد. دلیل دقیق ناموفق بودن مشخص نیست.

system_configured

دامنه به‌طور خودکار توسط پیکربندی دستگاه تأیید شد.

کد خطا 1024 یا بیشتر

کد خطای سفارشی که مختص درستی‌سنج دستگاه است.

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

از کاربر بخواهید برنامه‌تان را با دامنه‌ای مرتبط کند

راه دیگر برای تأیید شدن برنامه‌تان برای یک دامنه این است که از کاربر بخواهید برنامه‌تان را با آن دامنه مرتبط کند.

بررسی کنید که آیا برنامه‌تان قبلاً برای دامنه تأیید شده است یا نه

قبل‌از درخواست از کاربر، بررسی کنید که آیا برنامه‌تان کنترل‌کننده پیش‌فرض برای دامنه‌هایی است که در عناصر <intent-filter> تعریف می‌کنید یا نه. می‌توانید بااستفاده از یکی از روش‌های زیر، وضعیت تأیید را جستجو کنید:

• DomainVerificationManager میانای برنامه‌سازی کاربردی (در زمان اجرا).
• برنامه خط فرمان (درطول آزمایش).

DomainVerificationManager

تکه‌کد زیر نحوه استفاده از DomainVerificationManager API را نشان می‌دهد:

val context: Context = TODO("Your activity or fragment's Context")
val manager = context.getSystemService(DomainVerificationManager::class.java)
val userState = manager.getDomainVerificationUserState(context.packageName)

// Domains that have passed Android App Links verification.
val verifiedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_VERIFIED }

// Domains that haven't passed Android App Links verification but that the
// user has associated with an app.
val selectedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_SELECTED }

// All other domains.
val unapprovedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_NONE }

Context context = TODO("Your activity or fragment's Context");
DomainVerificationManager manager =
        context.getSystemService(DomainVerificationManager.class);
DomainVerificationUserState userState =
        manager.getDomainVerificationUserState(context.getPackageName());

Map<String, Integer> hostToStateMap = userState.getHostToStateMap();
List<String> verifiedDomains = new ArrayList<>();
List<String> selectedDomains = new ArrayList<>();
List<String> unapprovedDomains = new ArrayList<>();
for (String key : hostToStateMap.keySet()) {
    Integer stateValue = hostToStateMap.get(key);
    if (stateValue == DomainVerificationUserState.DOMAIN_STATE_VERIFIED) {
        // Domain has passed Android App Links verification.
        verifiedDomains.add(key);
    } else if (stateValue == DomainVerificationUserState.DOMAIN_STATE_SELECTED) {
        // Domain hasn't passed Android App Links verification, but the user
        // has associated it with an app.
        selectedDomains.add(key);
    } else {
        // All other domains.
        unapprovedDomains.add(key);
    }
}

برنامه خط فرمان

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

adb shell pm get-app-links --user cur PACKAGE_NAME

در خروجی نمونه زیر، با اینکه برنامه درستی‌سنجی دامنه «example.org» را با موفقیت نگذرانده است، کاربر ۰ به‌طور دستی برنامه را در تنظیمات سیستم تأیید کرده است، و هیچ بسته دیگری برای آن دامنه درستی‌سنجی نشده است.

com.example.pkg:
ID: ***
Signatures: [***]
Domain verification state:
  example.com: verified
  example.net: verified
  example.org: 1026
User 0:
  Verification link handling allowed: true
  Selection state:
    Enabled:
      example.org
    Disabled:
      example.com
      example.net

همچنین می‌توانید از فرمان‌های پوسته برای شبیه‌سازی فرایندی استفاده کنید که در آن کاربر انتخاب می‌کند کدام برنامه با دامنه مشخصی مرتبط شود. توضیح کامل این فرمان‌ها در خروجی adb shell pm دردسترس است.

ارائه بافتار برای درخواست

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

درخواست دادن

پس‌از اینکه کاربر متوجه شد برنامه‌تان از او چه می‌خواهد، درخواست را ارائه دهید. برای انجام این کار، قصدی را فراخوانی کنید که شامل ACTION_APP_OPEN_BY_DEFAULT_SETTINGS کنش قصد و رشته داده منطبق با package:com.example.pkg برای برنامه هدف باشد، همان‌طور که در تکه‌کد زیر نشان داده شده است:

val context: Context = TODO("Your activity or fragment's Context")
val intent = Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:${context.packageName}"))
context.startActivity(intent)

Context context = TODO("Your activity or fragment's Context");
Intent intent = new Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:" + context.getPackageName()));
context.startActivity(intent);

وقتی هدف فراخوانی می‌شود، کاربران صفحه تنظیماتی به‌نام باز کردن به‌طور پیش‌فرض را می‌بینند. این صفحه حاوی دکمه رادیویی به‌نام باز کردن پیوندهای پشتیبانی‌شده است، همان‌طور که در شکل ۱ نشان داده شده است.

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

باز کردن دامنه‌هایی در برنامه شما که برنامه‌تان نمی‌تواند آن‌ها را تأیید کند

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

علاوه‌براین، معرفی یک فعالیت ترامپولین یا کادر گفتگویی را درنظر بگیرید که به کاربر اجازه می‌دهد پیوند را در برنامه طرف اول باز کند (اگر کاربر ترجیح می‌دهد این کار را انجام دهد)، و به‌عنوان پراکسی عمل کند. قبل‌از راه‌اندازی چنین فعالیت ترامپولین یا کادر گفتگویی، برنامه‌تان را طوری راه‌اندازی کنید که رؤیت‌پذیری بسته در برنامه‌های شخص اولی که با فیلتر قصد وب برنامه‌تان مطابقت دارند داشته باشد.

تأخیر به‌روزرسانی «پیوندهای دارایی دیجیتال»

وقتی فایل assetlinks.json را در سرور وب به‌روز می‌کنید، مدت زمانی که طول می‌کشد تا این تغییرات در دستگاه‌های کاربر نهایی منعکس شود به نسخه سیستم‌عامل بستگی دارد:

• Android 15 (سطح API‏ ۳۵) و بالاتر: سیستم به‌طور دوره‌ای دامنه‌ها را در پس‌زمینه دوباره درستی‌سنجی می‌کند. به‌دلیل ذخیره در حافظه نهان سیستم و بازدرستی‌سنجی زمان‌بندی‌شده، ممکن است تا هفت روز طول بکشد تا تغییرات در همه دستگاه‌های کاربر نهایی اعمال شود.
• ‫Android 14 (سطح API‏ ۳۴) و پایین‌تر: سیستم درستی‌سنجی مجدد دوره‌ای در پس‌زمینه انجام نمی‌دهد. به‌روزرسانی‌های فایل معمولاً فقط هنگام نصب یا به‌روزرسانی برنامه دریافت می‌شود.

به‌روزرسانی‌های آزمایش

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