پیکربندی ارتباط‌های وب‌سایت و قوانین پویا

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

برای «پیوندهای برنامه» پویا در Android نسخه ۱۵ و بالاتر، فایل assetlinks.json همچنین جایی است که پیکربندی قوانین پویای خود را تعریف می‌کنید، مانند تطبیق‌دهنده‌های الگو برای پارامترهای مسیر، قطعه، و پُرسمان. دستگاه‌های Android دارای Android 15 (سطح API‏ ۳۵) یا بالاتر که سرویس‌های Google در آن‌ها نصب شده است، به‌طور دوره‌ای فایل را بازیابی می‌کنند و پیکربندی پویای شما را با پیکربندی ثابت در مانیفست برنامه ادغام می‌کنند.

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

اعلام کردن ارتباط‌های وب‌سایت

باید فایل JSON پیوندهای دارایی دیجیتال را در وب‌سایتتان منتشر کنید تا برنامه‌های Android مرتبط با وب‌سایت را نشان دهید و هدف‌های نشانی وب برنامه را به‌تأیید برسانید. فایل JSON از فیلدهای زیر برای شناسایی برنامه‌های مرتبط استفاده می‌کند:

• package_name: شناسه برنامه اعلام‌شده در فایل build.gradle برنامه.
• sha256_cert_fingerprints: اثر انگشت‌های SHA256 گواهی امضای برنامه شما. می‌توانید از فرمان زیر برای تولید اثر انگشت بااستفاده از Java keytool استفاده کنید:

keytool -list -v -keystore my-release-key.keystore

• این فیلد از چندین اثر انگشت پشتیبانی می‌کند که می‌توان از آن‌ها برای پشتیبانی از نسخه‌های مختلف برنامه‌تان، مثل نسخه‌های ساخت اشکال‌زدایی و تولید، استفاده کرد. اگر از امضای برنامه Play برای برنامه‌تان استفاده می‌کنید، اثر انگشت گواهینامه تولیدشده با اجرای keytool به‌صورت محلی معمولاً با اثر انگشت موجود در دستگاه‌های کاربران مطابقت نخواهد داشت. می‌توانید بررسی کنید که آیا از «امضای برنامه» Play برای برنامه‌تان در حساب توسعه‌دهنده کنسول Play خود در بخش Release > Setup > App signing استفاده می‌کنید یا نه؛ اگر استفاده می‌کنید، گزیده JSON «پیوندهای دارایی دیجیتال» صحیح را نیز برای برنامه‌تان در همان صفحه پیدا خواهید کرد.

فایل assetlinks.json نمونه زیر حقوق باز کردن پیوند را به برنامه Android com.example اعطا می‌کند:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

مرتبط کردن وب‌سایت با چند برنامه

وب‌سایت می‌تواند ارتباط با چند برنامه را در یک فایل assetlinks.json اعلام کند. فهرست فایل زیر نمونه‌ای از فایل بیانیه را نشان می‌دهد که ارتباط با دو برنامه را به‌طور جداگانه اعلام می‌کند و در https://www.example.com/.well-known/assetlinks.json قرار دارد:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

برنامه‌های مختلف ممکن است پیوندهای مربوط به منابع مختلف را تحت یک میزبان وب مدیریت کنند. برای مثال، app1 ممکن است فیلتر قصدی برای https://example.com/articles اعلام کند و app2 ممکن است فیلتر قصدی برای https://example.com/videos اعلام کند.

مرتبط کردن چند وب‌سایت با یک برنامه

چندین وب‌سایت می‌توانند در فایل‌های assetlinks.json مربوطه خود، ارتباط با یک برنامه را اعلام کنند. فهرست‌های فایل زیر نمونه‌ای از نحوه اعلام ارتباط example.com و example.net با app1 را نشان می‌دهد. اولین فهرست، ارتباط example.com با app1 را نشان می‌دهد:

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

فهرستگان بعدی ارتباط example.net با app1 را نشان می‌دهد. فقط مکان میزبانی این فایل‌ها متفاوت است (‎.com و ‎ .net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

پیکربندی قوانین پویا

«پیوندهای پویای برنامه» در Android نسخه ۱۵ و بالاتر به شما امکان می‌دهد از قوانین تطابق پیوند عمیق سمت سرور استفاده کنید که با قوانینی که به‌صورت ایستا در مانیفست برنامه‌تان تعریف کرده‌اید کار می‌کنند. فایل assetlinks.json جایی است که قوانین پویا را تعریف می‌کنید. این اختیاری است.

دستگاه‌های Android دارای Android نسخه ۱۵ (سطح میانای برنامه‌سازی کاربردی ۳۵) یا جدیدتر که سرویس‌های Google در آن‌ها نصب شده است، به‌طور دوره‌ای این فایل را از سرور شما بازیابی می‌کنند و پیکربندی قوانین پویای شما را با پیکربندی ثابت در مانیفست برنامه ادغام می‌کنند. در زیر نمونه‌ای از فایل assetlinks.json با قوانین پویا آورده شده است:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

نکات کلیدی درباره کد

• «پیوندهای پویا برنامه» افزونه رابطه جدیدی برای «پیوندهای دارایی دیجیتال» اضافه می‌کند که dynamic_app_link_components نام دارد و در آنجا می‌توانید قوانین پویای خود را پیکربندی کنید.
• قوانین پویا می‌توانند شامل تطبیق‌دهنده‌های الگو برای مسیر، قطعه، و پارامترهای پُرسمان باشند.
• همچنین می‌توانید هر تطبیق‌دهنده الگویی را به‌عنوان مستثنی‌شده علامت‌گذاری کنید تا نشانی‌های وب منطبق، برنامه‌تان را باز نکنند.
• این مثال نمونه‌هایی از مطابقت‌دهنده‌ها را برای مسیر ("/")، قطعه ("#")، و پارامترهای پُرسمان ("?")، و همچنین مطابقت‌دهنده‌های مستثنی‌شده ("exclude") نشان می‌دهد
• اگر هرکدام از فیلدهای فایل ناقص یا خالی باشد، Android قوانین پویا را کنار می‌گذارد و دستگاه به قوانینی که به‌صورت ایستا در مانیفست برنامه تعریف شده‌اند برمی‌گردد.

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

اعلام کردن قوانین پویا

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

• تطبیق مسیر
  • کلید: «/»
  • مقدار: رشته تکی، عبارت منطبق برای مسیر نشانی وب
• تطبیق قطعه
  • کلید: «#»
  • مقدار: رشته تکی، عبارت منطبق برای قطعه نشانی وب
• تطبیق پارامتر پُرسمان
  • کلید: «؟»
  • مقدار: واژه‌نامه برای مطابقت دادن جفت‌های کلید/مقدار در پارامترهای پُرسمان نشانی وب.
  • برای مثال، واژه‌نامه {«?", {"dl": "*", "in_app":"true»} با رشته پُرسمان «?in_app=true&dl=abc» مطابقت خواهد داشت.
  • ترتیب جفت‌های کلید/مقدار در واژه‌نامه لازم نیست با ترتیب جفت‌ها در رشته پُرسمان مطابقت داشته باشد. علاوه‌براین، لازم نیست واژه‌نامه با همه جفت‌های کلید/مقدار در رشته پُرسمان مطابقت داشته باشد، اما باید برای هر ورودی واژه‌نامه مطابقت پیدا شود.
  • برای مثال، واژه‌نامه با رشته پُرسمان «?lang=en&in_app=true&tz=pst&dl=abc» نیز مطابقت دارد، اما با رشته پُرسمان «?lang=en&tz=pst&dl=abc» مطابقت ندارد
• مستثنی‌شده
  • کلید: «exclude»
  • مقدار: مقدار اختیاری درست/غلط برای هر قانون تعریف‌شده در dynamic_app_link_components (مثال را ببینید).

می‌توانید از این نویسه‌های خاص در تطبیق‌دهنده‌های الگو استفاده کنید:

• «*» با صفر یا چند نویسه مطابقت دارد تا زمانی که نویسه بعداز نویسه عام در الگو در رشته منطبق پیدا شود
• «؟» با هر نویسه تکی مطابقت دارد
• «?*» با ۱ نویسه یا بیشتر مطابقت دارد

هیچ محدودیت نویسه دیگری برای مقادیر وجود ندارد.

مرتب کردن قوانین پویا

ترتیب اعلام قوانین مهم است. Android هر قانون را به‌ترتیب ارزیابی می‌کند تا مورد منطبقی پیدا کند.

مثال زیر نشان می‌دهد که چگونه ترتیب می‌تواند بر رسیدگی تأثیر بگذارد. قانون اول با همه مسیرها («*») مطابقت دارد اما موارد منطبق را مستثنی می‌کند (مستثنی کردن: درست)، یعنی همه نشانی‌های وب را از باز کردن برنامه مستثنی می‌کند. در این حالت، قانون دوم که «/path1» را مجاز می‌کند هرگز ارزیابی نخواهد شد.

dynamic_app_link_components: [
  {"/": "*", "exclude": true},
  {"/": "/path1"}
]

اما در مثال بعدی، قانون «/path1» ابتدا اعلام شده است، بنابراین ابتدا ارزیابی می‌شود و برنامه را برای نشانی وب منطبق با «/path1» باز می‌کند. قانون دوم که همه نشانی‌های وب را از باز کردن برنامه مستثنی می‌کند، در مرحله دوم ارزیابی می‌شود، اما فقط درصورتی‌که قانون اول مطابقت نداشته باشد.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "*", "exclude": true}
]

اگر هیچ موردی در فهرست مؤلفه‌های اعلام‌شده مطابقت نداشته باشد، نشانی وب برنامه را باز نخواهد کرد. در مثال زیر، هیچ‌کدام از مسیرها با «‎/path3» مطابقت ندارند، بنابراین دستگاه این مسیر را به‌عنوان مستثنی‌شده درنظر می‌گیرد.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

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

dynamic_app_link_components: [
  {"/": "/path1", "exclude": true},
  {"/": "*"}
]

قوانین پویای خود را به‌درستی تعریف کنید

هنگام تعریف کردن قوانین سمت سرور برای استفاده با «پیوندهای پویای برنامه» در Android نسخه ۱۵ و بالاتر، مهم است که آن‌ها را به‌درستی محدود کنید تا با فیلترهای قصد ثابتی که در مانیفست برنامه‌تان اعلام شده‌اند کار کنند و آن‌ها را تکمیل کنند.

قوانین پویای اعلام‌شده در فایل assetlinks.json فقط می‌توانند قوانینی را برای میزبان‌هایی که در فایل AndroidManifest.xml برنامه‌تان اعلام می‌کنید مشخص کنند. قوانین پویا نمی‌توانند دامنه قوانین نشانی وبی را که به‌صورت ایستا در مانیفست برنامه‌تان اعلام می‌کنید گسترش دهند.

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

• در مانیفست برنامه‌تان، قوانینی با گسترده‌ترین دامنه ممکن تنظیم کنید، مثلاً با اعلام کردن فقط طرح و دامنه
• برای پالایش بیشتر، به قوانین پویای سمت سرور، مانند مسیریابی سطح مسیر، تکیه کنید.

با این پیکربندی ایده‌آل، می‌توانید به‌طور پویا مسیرهای جدید «پیوندهای برنامه» را در فایل assetlinks.json اضافه کنید، با این اطمینان که این مسیرها در محدوده وسیعی که در مانیفست برنامه تنظیم کرده‌اید قرار خواهند گرفت.

dynamic_app_link_components را فقط یک‌بار اعلام کنید

برای رسیدگی مناسب به قوانینتان، فقط یک شیء dynamic_app_link_components در سراسر بیانیه‌ها برای سایت، رابطه، و برنامه موردنظر اعلام کنید.

• به‌دنبال چندین عبارت برای یک سایت، رابطه، و برنامه بگردید که شیء dynamic_app_link_components را اعلام می‌کنند.
• به‌دنبال چندین شیء dynamic_app_link_components باشید که در یک عبارت واحد اعلام شده‌اند

در چنین مواردی، Android تضمین نمی‌کند که از کدام پیکربندی قوانین پویا استفاده خواهد شد.

سازگاری قوانین پویا با پیکربندی‌های قبلی «پیوندهای برنامه»

اگر ازقبل از «پیوندهای برنامه» پشتیبانی می‌کنید، می‌توانید پشتیبانی از «پیوندهای برنامه پویا» را مستقیماً در فایل assetlinks.json موجود اضافه کنید. فیلدهای رابطه برای تأیید «پیوندهای برنامه» شما یکسان باقی می‌مانند و می‌توانید فیلدهای افزونه رابطه جدید را برای قوانین پویا بدون هیچ تغییر دیگری اضافه کنید.

دستگاه‌های Android که Android 14 (میانای برنامه‌سازی کاربردی سطح ۳۴ یا قدیمی‌تر) را اجرا می‌کنند، فیلدهای افزونه رابطه جدید را برای قوانین پویا نادیده می‌گیرند، درحالی‌که دستگاه‌هایی که Android 15 و نسخه‌های جدیدتر را اجرا می‌کنند، این قوانین را با قوانین تعریف‌شده در مانیفست شما ادغام خواهند کرد.

منتشر کردن فایل درستی‌سنجی JSON

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

https://domain.name/.well-known/assetlinks.json

از موارد زیر مطمئن شوید:

• فایل assetlinks.json با نوع محتوای application/json ارائه می‌شود.
• فایل assetlinks.json باید ازطریق اتصال HTTPS دردسترس باشد، صرف‌نظر از اینکه فیلترهای هدف برنامه‌تان HTTPS را به‌عنوان طرح داده اعلام کنند یا نه.
• فایل assetlinks.json باید بدون هیچ‌گونه هدایت کردنی (بدون هدایت کردن ۳۰۱ یا ۳۰۲) قابل‌دسترسی باشد.
• اگر پیوندهای برنامه‌تان از چند دامنه میزبان پشتیبانی می‌کند، باید فایل assetlinks.json را در هر دامنه منتشر کنید. پشتیبانی از پیونددهی برنامه برای چند میزبان را ببینید.
• برنامه‌تان را با نشانی‌های وب آزمایشی در فایل مانیفست که ممکن است برای عموم دردسترس نباشد (مثل نشانی‌های وبی که فقط با VPN دردسترس هستند) منتشر نکنید. راه‌حل جایگزین در چنین مواردی پیکربندی تنوع‌های ساخت برای تولید فایل مانیفست متفاوت برای ساخت‌های توسعه است.

راهنماهای مرتبط زیر را ببینید:

• ایجاد فهرست عبارت
• دستیار پیوندهای برنامه در «استودیو Android»
• ابزارهای توسعه‌دهنده «پیوندهای برنامه»