Web intent resolution در اندروید

شروع Android 12، در صورتی که برنامه برای دامنه خاصی در web intent resolves عمومی تایید شود، به فعالیتی در برنامه شما تبدیل می شود. اگر برنامه شما برای دامنه تأیید نشده باشد، web intent resolves در برنامه مرورگر پیش فرض کاربر برطرف می شود.

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

• دامنه را با استفاده از ویژگی Android App Links تأیید کنید.

توجه: در برنامه هایی که از Android 12 استفاده می کنند، سیستم فرآیند تأیید صحت لینک برنامه Android را انجام می دهد.

• از کاربر بخواهید در تنظیمات سیستم به صورت دستی برنامه شما را با دامنه مرتبط کند.

اگر برنامه شما به اهداف وب استناد می کند، در نظر بگیرید که یک اعلان یا گفتگویی اضافه کنید که از کاربر می خواهد اقدام را تأیید کند.

Web intent attributes

web intent هدفی است که شامل مشخصات زیر است:

• اقدام: ACTION_VIEW
• دسته: CATEGORY_DEFAULT (برنامه های تماس می توانند به جای آن MATCH_DEFAULT_ONLY را مشخص کنند)
• طرح: http یا https
• میزبان: قالب معتبر tld که با الگوی مشخص شده در DOMAIN_NAME مطابقت دارد.

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

با اندروید 12 شروع کنید، فیلترهای قصد وب نیز باید دسته CATEGORY BROWSABSLE را اعلام کنند تا هدف وب مشخص شده به فعالیت در برنامه شما برسد.

دامنه ها را با استفاده از پیوندهای برنامه Android تأیید کنید

Android App Links ، موجود در Android 8.0 (سطح API 26) و بالاتر، از Digital Asset Links API برای مرتبط کردن یک برنامه خاص با دامنه وب استفاده می کنند. این ارتباط به سیستم این امکان را می دهد تا سیستم اطمینان یابد که برنامه توسط وب سایت تأیید شده است تا پیوندها را برای آن دامنه به طور خودکار باز کند.

با Android 12 شروع کنید، برای ارزیابی نحوه حل سیستم پیوندهای برنامه Android شما می توانید به صورت دستی تأیید دامنه را فرا بگیرید.

تغییرات تأیید پیوندهای برنامه Android

در برنامه هایی که Android 12 را هدف قرار می دهند، سیستم چندین تغییر در نحوه تأیید پیوندهای برنامه Android ایجاد می کند. این تغییرات قابلیت اطمینان تجربه اتصال برنامه را بهبود می بخشد و کنترل بیشتری به توسعه دهندگان برنامه و کاربران نهایی می دهد. می توانید به صورت دستی تأیید دامنه را فرا بگیرید تا قابلیت اطمینان اعلام خود را تست کنید.

اگراز Android 12 استفاده می کنید و برای باز کردن پیوندهای وب در برنامه خود به تأیید صحت پیوند برنامه Android متکی هستید، اعلامیه های پیوندهای برنامه Android خود را به روز کنید تا روند تأیید تغییرات را حمایت کند.

اعلامیه های پیوندهای برنامه Android را به روز کنید

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

<!-- Make sure you explicitly set android:autoVerify to "true". -->
<intent-filter android: autoVerify="true">
    <action android: name="android. intent. action. VIEW" />
    <category android: name="android.intent.category.BROWSABLE" />
    <category android: name="android.intent.category.DEFAULT" />

    <!-- If a user clicks on a shared link that uses the "http" scheme, your
         app should be able to delegate that traffic to "https". -->
    <data android: scheme="http" />
    <data android: scheme="https" />

    <!-- Include one or more domains that should be verified. -->
    <data android: host="..." />
</intent-filter>

توجه:  در حالی که تنها کافی است یک AutoVerify را فقط در یک <intent-filter> اعلانات برای هر میزبان وارد کنید ، حتی اگر از این میزبان در سایر اعلانهای بدون علامت استفاده شود ، توصیه می شود که برای ثبات به هر <intent-filter> AutoVerify اضافه کنید. این امر همچنین تضمین می کند که حذف یا تغییر شکل اظهارنامه ها به طور تصادفی دامنه ای را از برنامه حذف نکند.

به صورت دستی تأیید دامنه را فراخوانی کنید.

با شروع Android 12، می توانید به صورت دستی تأیید دامنه را برای برنامه ای که روی دستگاه نصب شده فراخوانی کنید. بدون توجه به اینکه برنامه شما Android 12 را هدف قرار دهد، می توانید این فرآیند را انجام دهید.

Establish an internet connection

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

از روند تأیید صحت دامنه پشتیبانی کنید

اگر برنامه شما از 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

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

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

لیست زیر مقادیر بازگشتی احتمالی را که تأیید دامنه می تواند برای یک دامنه مشخص برگرداند نشان می دهد:

• none

هیچ چیزی برای این دامنه ثبت نشده است. چند دقیقه دیگر منتظر بمانید تا تأیید درخواست های مربوط به تأیید دامنه را به پایان برسد، (invoke the domain verification process  )سپس فرآیند تأیید دامنه را دوباره فراخوانی کنید.

• verified

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

• approved

دامنه مورد تأیید قرار می گیرد، معمولاً با اجرای یک دستور shell.

• denied

دامنه، با اجرای یک دستور shell ، force-denied می شد.

• migrated

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

• restored

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

• legacy_failure

دامنه توسط  legacy verifier رد شد. دلیل خاص شکست مشخص نیست.

• system_configured

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

• Error code of 1024 or greater

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

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

از کاربر بخواهید برنامه شما را با یک دامنه associate کند

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

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

بررسی کنید آیا برنامه شما از قبل برای دامنه تأیید شده است یا خیر؟

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

• The DomainVerificationManagerAPI (at runtime)
• A command-line program (during testing)

DomainVerificationManager

قطعه کد زیر نحوه استفاده از APIDomainVerificationManager را نشان می دهد:

val context: Context = TODO("Your activity or fragment's Context")
val manager = context.getSystemService(DomainVerificationManager::class)
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);
    }
}

Command-line program

هنگام تست برنامه خود در حین توسعه، می توانید برای پیگیری از وضعیت تأیید دامنه هایی که سازمان شما متعلق به آن است، دستور زیر را اجرا کنید:

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

در خروجی مثال زیر، حتی اگر برنامه برای دامنه “example.org” تأیید نشد، کاربر 0 برنامه را به صورت دستی در تنظیمات سیستم تأیید کرده است و هیچ بسته دیگری برای آن دامنه تأیید نشده است.

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

زمینه درخواست را فراهم کنید

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

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

بعد از اینکه کاربر متوجه شد برنامه شما از او چه می خواهد انجام دهد، این درخواست را انجام دهید. برای این کار، نیتی را فراخوانی کنید که شامل ACTION_APP_OPEN_BY_DEFAULT_SETTINGS و یک بسته تطبیق رشته داده باشد: 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);

هنگامی که این هدف مورد استناد قرار می گیرد، کاربران یک صفحه تنظیمات را به نام Open by default به طور پیش فرض مشاهده می کنند. همانطور که در شکل 1 نشان داده شده است، این صفحه شامل یک دکمه رادیویی به نام Open supported links است.

وقتی کاربر  Open supported linksرا روشن می کند، مجموعه ای از کادرهای تأیید در زیر بخشی به نام  Links to open in this app ظاهر می شوند. از اینجا، کاربران می توانند دامنه هایی را که می خواهند با برنامه شما مرتبط شوند انتخاب کنند. همانطور که در شکل 2 نشان داده شده است ، آنها همچنین می توانند Add link را برای افزودن دامنه انتخاب کنند. وقتی کاربران بعداً هر پیوندی را در دامنه هایی که اضافه می کنند انتخاب می کنند، پیوند به طور خودکار در برنامه شما باز می شود.

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

شکل 2. گفتگویی که در آن کاربران می توانند دامنه های دیگری را برای ارتباط با برنامه شما انتخاب کنند.

تأیید دامنه را به صورت دستی تغییر دهید

تأیید دامنه و انتخاب کاربر را می توان با استفاده از دستورات پوسته ای که به یک توسعه دهنده اجازه می دهد به طور دستی وضعیت مناسب را برای اشکال زدایی، انجام تست یا مواردی مانند عدم اتصال به اینترنت تنظیم کند، تغییر دهید.

توضیح کامل این دستورات از خروجی adb shell pm در دسترس است.

توجه داشته باشید که همه اولویت های تأیید شده یکسان و محدودیت های تایید حتی در صورت تأیید از طریق shell commands اعمال می شوند، بنابراین برخی از موارد خاص مانند نصب دو نوع برنامه به طور همزمان به باز کردن یک پیوند وب داده شده در برنامه مورد نظر نیاز به دستکاری ویژه دارند.

تایید چند برنامه

اگر چندین برنامه را منتشر کنید که هر کدام با یک دامنه مرتبط هستند، می توان آنها را با موفقیت تأیید کرد. با این حال، اگر برنامه ها بتوانند میزبان و مسیر دامنه دقیقاً یکسانی را حل کنند، همانطور که ممکن است در نسخه های ساده و کامل برنامه رخ دهد، فقط برنامه ای که اخیراً نصب شده است می تواند اهداف وب را برای آن دامنه حل کند.

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

توجه: ذخیره مسیر تطبیق را در نظر داشته باشید تا اگر بعداً هدف مشابه وب راه اندازی شد، کاربر مجبور به انتخاب مجدد آن نباشد.

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

عملکرد اصلی برنامه شما ممکن است باز کردن پیوندها به عنوان شخص ثالث، بدون امکان تأیید دامنه های تحت کنترل آن باشد. در این صورت، به کاربران توضیح دهید که در آن زمان که پیوند وب را انتخاب می کنند، نمی توانند بین برنامه شخص اول و برنامه (شخص ثالث) شما یکی را انتخاب کنند. کاربران باید دامنه ها را به صورت دستی با برنامه شخص ثالث شما مرتبط کنند.

علاوه بر این، معرفی یک گفتگوی یا trampoline activity را در نظر بگیرید که به کاربر اجازه می دهد در صورت ترجیح کاربر، پیوند را در برنامه شخص اول باز کند و به عنوان یک proxy عمل کند. قبل از تنظیم چنین فعالیت گفتگویی یا  trampoline activity، برنامه خود را طوری تنظیم کنید که قابلیت package visibility در برنامه های شخص اول را داشته باشد که با فیلتر برنامه وب برنامه شما مطابقت دارد.