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

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

برای پیوندهای برنامه پویا در Android 15 و بالاتر، فایل assetlinks.json همچنین جایی است که پیکربندی قوانین پویا خود را تعریف می‌کنید ، مانند تطبیق‌کنندگان الگو برای پارامترهای مسیر، قطعه، و پرس و جو. دستگاه‌های Android دارای Android 15 (سطح API 35) یا جدیدتر که سرویس‌های Google را نصب کرده‌اند، به‌طور دوره‌ای فایل را بازیابی می‌کنند و پیکربندی پویا شما را با پیکربندی استاتیک در مانیفست برنامه ادغام می‌کنند.

این راهنما نحوه تهیه فایل assetlinks.json و انتشار آن را در وب سایت خود شرح می دهد. اگر ترجیح می دهید، می توانید یک فایل assetlinks.json را از ابزار Play Deep Links یا دستیار پیوندهای برنامه Android Studio ایجاد کنید. برای اطلاعات بیشتر، به ابزارهای توسعه دهنده App Links مراجعه کنید.

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

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

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

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

  • این فیلد از چندین اثر انگشت پشتیبانی می کند که می تواند برای پشتیبانی از نسخه های مختلف برنامه شما مانند اشکال زدایی و ساخت های تولیدی استفاده شود. اگر از Play App Signing برای برنامه خود استفاده می‌کنید، اثرانگشت گواهی که با اجرای keytool به صورت محلی تولید می‌شود، معمولاً با نمونه موجود در دستگاه‌های کاربران مطابقت ندارد. می‌توانید تأیید کنید که آیا از Play App Signing برای برنامه خود در حساب برنامه‌نویس Play Console خود در بخش 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 15 و بالاتر به شما امکان می دهد از قوانین تطبیق پیوند عمیق سمت سرور استفاده کنید که با قوانینی که به صورت ایستا در مانیفست برنامه خود تعریف کرده اید، کار می کنند. فایل assetlinks.json جایی است که قوانین پویا را تعریف می کنید. این اختیاری است که شامل شود.

دستگاه‌های Android دارای Android 15 (سطح API 35) یا جدیدتر که سرویس‌های 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 Links یک پسوند جدید مرتبط با پیوند دارایی دیجیتال به نام dynamic_app_link_components اضافه می‌کند، جایی که قوانین پویا خود را پیکربندی می‌کنید.
  • قوانین پویا می توانند شامل تطبیق دهنده های الگو برای پارامترهای مسیر، قطعه و پرس و جو باشند.
  • همچنین می‌توانید هر تطبیق الگو را به‌عنوان مستثنی علامت‌گذاری کنید تا نشانی‌های اینترنتی منطبق برنامه شما را باز نکنند.
  • این مثال نمونه‌هایی از تطبیق‌کننده‌ها برای مسیر ( "/" )، قطعه ( "#" )، و پارامترهای پرس و جو ( "?" )، و همچنین تطبیق‌کنندگان حذف شده ( "exclude" ) را نشان می‌دهد.
  • اگر هر یک از فیلدهای فایل نادرست یا خالی باشد، Android قوانین پویا را کنار می‌گذارد و دستگاه به قوانینی بازمی‌گردد که به صورت ایستا در مانیفست برنامه تعریف شده‌اند.

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

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

Dynamic App Links از یک پسوند رابطه جدید dynamic_app_link_components پشتیبانی می کند که آرایه ای از اشیاء قوانین را در خود نگه می دارد. هر قانون با استفاده از تطبیق‌کننده‌های الگو برای مسیرها، قطعات و پارامترهای پرس و جو که برنامه شما را باز می‌کند، تعریف می‌شود. Match ها همچنین می توانند به صورت جداگانه حذف شوند تا برنامه شما را باز نکنند. همه اینها اختیاری هستند.

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

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

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

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

قوانین پویا را سفارش دهید

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

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

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

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

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

قوانین پویا خود را به درستی در نظر بگیرید

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

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

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

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

با این پیکربندی ایده‌آل، می‌توانید به صورت پویا مسیرهای App Links جدید را در صورت نیاز به فایل assetlinks.json اضافه کنید، و بدانید که آنها در محدوده وسیعی که در مانیفست برنامه تنظیم کرده‌اید، قرار می‌گیرند.

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

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

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

سازگاری قوانین پویا با پیکربندی های قبلی App Links

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

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

فایل تأیید JSON را منتشر کنید

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

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

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

  • فایل assetlinks.json با content-type application/json ارائه می شود.
  • فایل assetlinks.json باید از طریق اتصال HTTPS قابل دسترسی باشد، صرف نظر از اینکه فیلترهای هدف برنامه شما HTTPS را به عنوان طرح داده اعلام می‌کنند یا خیر.
  • فایل assetlinks.json باید بدون هیچ تغییر مسیری قابل دسترسی باشد (بدون تغییر مسیر 301 یا 302).
  • اگر پیوندهای برنامه شما از چندین دامنه میزبان پشتیبانی می کند، باید فایل assetlinks.json را در هر دامنه منتشر کنید. به پشتیبانی از پیوند برنامه برای چندین میزبان مراجعه کنید.
  • برنامه خود را با URL های آزمایشی در فایل مانیفست منتشر نکنید که ممکن است برای عموم قابل دسترسی نباشد (مانند مواردی که فقط با VPN قابل دسترسی هستند). راه حل در چنین مواردی، پیکربندی انواع ساخت برای ایجاد یک فایل مانیفست متفاوت برای ساخت‌های توسعه‌دهنده است.

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