آیا برنامه شما نصب شده است؟ Get Installed Related Apps API به شما خواهد گفت!

Pete LePage

Alexey Rodionov

API مربوط به Get Installed Related Apps امکان دریافت لیست برنامه‌های مرتبط نصب شده به همراه جزئیات مربوط به آنها را فراهم می‌کند.

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

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

برای مثال:

• اگر برنامه‌ی PWA شما از قبل نصب شده است، نصب آن را تبلیغ نکنید.
• هدایت کاربر از یک وب‌سایت بازاریابی محصول به طور مستقیم به برنامه شما.
• متمرکز کردن برخی قابلیت‌ها مانند اعلان‌ها در برنامه دیگر برای جلوگیری از اعلان‌های تکراری.

API مربوط به Get Installed Related Apps چیست؟

فراخوانی ناهمزمان متد navigator.getInstalledRelatedApps() یک promise را برمی‌گرداند که با آرایه‌ای از اشیاء حاوی جزئیاتی در مورد برنامه‌هایی که عبارتند از:

• روی دستگاه فعلی نصب شده باشد،
• در فیلد related_applications از مانیفست برنامه وب تعریف شده است،
• یک رابطه‌ی تأیید شده با صفحه‌ای داشته باشید که در آن متد navigator.getInstalledRelatedApps() فراخوانی می‌شود (برای جزئیات بیشتر به بخش‌های بعدی مراجعه کنید).

const installedRelatedApps = await navigator.getInstalledRelatedApps?.();

فراخوانی console.log(installedRelatedApps) چیزی شبیه به این را برمی‌گرداند:

[
  {
    platform: "webapp",
    id: "https://example.com/?utm_source=home_screen",
    url: "https://example.com/manifest.json"
  },
  {
    platform: "play",
    id: "com.example.twa",
    url: "https://play.google.com/store/apps/details?id=com.example.twa",
    version: "0.1.0"
  }
]

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

const hasInstalledRelatedApps = !!(await navigator.getInstalledRelatedApps?.())?.length;

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

const installedRelatedAndroidAppVersion = (await navigator.getInstalledRelatedApps?.())?.find(app => app.id === 'com.example.twa')?.version;

انواع برنامه‌های پشتیبانی‌شده که می‌توانید بررسی کنید

بررسی کنید که آیا برنامه اندروید شما نصب شده است یا خیر

وب‌سایت شما می‌تواند بررسی کند که آیا برنامه اندروید شما نصب شده است یا خیر.

پشتیبانی شده در:

• فقط اندروید: کروم ۸۰ یا بالاتر

به اپلیکیشن اندروید خود درباره وب‌سایتتان بگویید

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

در فایل AndroidManifest.xml برنامه اندروید خود، یک ورودی asset_statements اضافه کنید:

<manifest>
  <application>
   …
    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
   …
  </application>
</manifest>

سپس، در strings.xml ، عبارت asset زیر را اضافه کنید و site با دامنه خود به‌روزرسانی کنید. حتماً کاراکترهای escape را نیز وارد کنید.

<string name="asset_statements">
  [
    {
      \"relation\": [\"delegate_permission/common.handle_all_urls\"],
      \"target\": {
        \"namespace\": \"web\",
        \"site\": \"https://example.com\"
      }
    }
  ]
</string>

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

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

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

در مرحله بعد، با اضافه کردن یک مانیفست برنامه وب به صفحه خود، در مورد برنامه اندروید خود به وب‌سایت اطلاع دهید. مانیفست باید شامل ویژگی related_applications باشد، آرایه‌ای که جزئیات مربوط به برنامه شما، از جمله platform و id را ارائه می‌دهد.

• platform باید قابل play باشد
• id شناسه بسته اندروید است.

{
  ...
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.twa"
    }
  ]
  ...
}

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

بررسی کنید که آیا برنامه شما نصب شده است یا خیر

در نهایت، تابع غیرهمزمان navigator.getInstalledRelatedApps() را فراخوانی کنید تا بررسی شود که آیا برنامه اندروید شما نصب شده است یا خیر.

بررسی کنید که آیا برنامه ویندوز (UWP) شما نصب شده است یا خیر

وب‌سایت شما می‌تواند بررسی کند که آیا برنامه ویندوز شما (که با استفاده از UWP ساخته شده است) نصب شده است یا خیر.

پشتیبانی شده در:

• فقط ویندوز: کروم ۸۵ یا بالاتر، اج ۸۵ یا بالاتر

به برنامه ویندوز خود در مورد وب‌سایتتان بگویید

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

ثبت افزونه Windows.appUriHandler را به فایل مانیفست برنامه خود AppxManifest.xml یا Package.appxmanifest اضافه کنید. برای مثال، اگر آدرس وب‌سایت شما example.com است، باید ورودی زیر را در مانیفست برنامه خود اضافه کنید:

<Applications>
  <Application Id="App" ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="example.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

توجه داشته باشید، ممکن است لازم باشد فضای نام uap3 را به ویژگی <Package> خود اضافه کنید.

اگر وب‌سایت شما چندین آدرس دارد، برای هر آدرس، یک ورودی <uap3:Host Name=... /> جداگانه داخل <uap3:AppUriHandler> اضافه کنید.

سپس، یک فایل JSON (بدون پسوند فایل .json ) با نام windows-app-web-link ایجاد کنید و نام خانوادگی بسته برنامه خود را در آن وارد کنید. آن فایل را یا در دایرکتوری /.well-known/ یا در ریشه سرور خود قرار دهید.

[
  {
    "packageFamilyName": "MyApp_9jmtgj1pbbz6e",
    "paths": [ "*" ]
  }
]

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

برای فهمیدن نام خانوادگی بسته (Package Family Name)، می‌توانید برنامه را نصب کنید، دستور زیر را در PowerShell اجرا کنید و برنامه خود را در لیست پیدا کنید:

Get-AppxPackage | Select-Object PackageFamilyName

برای جزئیات کامل در مورد تنظیم کنترل‌کننده‌های URI، به بخش «فعال کردن برنامه‌ها برای وب‌سایت‌ها با استفاده از کنترل‌کننده‌های URI برنامه» مراجعه کنید.

به وب‌سایت خود در مورد اپلیکیشن ویندوزتان بگویید

در مرحله بعد، با اضافه کردن یک مانیفست برنامه وب به صفحه خود، در مورد برنامه ویندوز خود به وب‌سایت خود اطلاع دهید. مانیفست باید شامل ویژگی related_applications باشد، آرایه‌ای که جزئیات مربوط به برنامه شما، از جمله platform و id را ارائه می‌دهد.

• platform باید windows باشد
• id نام خانوادگی پکیج برنامه شماست که !App به عنوان پسوند به انتهای آن اضافه شده است.

{
  ...
  "related_applications": [
    {
      "platform": "windows",
      "id": "MyApp_9jmtgj1pbbz6e!App"
    }
  ]
  ...
}

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

بررسی کنید که آیا برنامه شما نصب شده است یا خیر

در نهایت، تابع غیرهمزمان navigator.getInstalledRelatedApps() را فراخوانی کنید تا بررسی شود که آیا برنامه ویندوز شما نصب شده است یا خیر.

این نسخه آزمایشی (دمو) را بررسی کنید.

بررسی کنید که آیا برنامه وب پیش‌رونده شما از قبل نصب شده است یا خیر (در محدوده)

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

پشتیبانی شده در:

• اندروید: کروم ۸۴ یا بالاتر
• دسکتاپ (ویندوز، macOS، لینوکس، ChromeOS): کروم ۱۴۰ یا بالاتر، اج ۱۴۰ یا بالاتر

درباره PWA خود به او بگویید

با اضافه کردن ورودی related_applications در مانیفست برنامه وب PWA خود، درباره آن به PWA خود بگویید.

• platform باید webapp باشد
• url مسیر (می‌تواند نسبی باشد) به مانیفست برنامه وب PWA شما است.
• id شناسه برنامه وب است که در فیلد شناسه id برنامه وب اعلام شده یا توسط مرورگر محاسبه می‌شود (برای دسکتاپ مورد نیاز است، برای اندروید لازم نیست)

{
  ...
  "scope": "/",
  "start_url": "/?utm_source=home_screen",
  "related_applications": [
    {
      "platform": "webapp",
      "url": "/manifest.json",
      "id": "https://example.com/?utm_source=home_screen"
    }
  ],
  ...
}

بررسی کنید که آیا PWA شما نصب شده است یا خیر

در نهایت، تابع غیرهمزمان navigator.getInstalledRelatedApps() را از داخل محدوده PWA خود فراخوانی کنید تا بررسی شود که آیا نصب شده است یا خیر. اگر navigator.getInstalledRelatedApps() خارج از محدوده PWA شما فراخوانی شود، مقدار [] را برمی‌گرداند. برای جزئیات بیشتر به بخش بعدی مراجعه کنید.

بررسی کنید که آیا برنامه وب پیش‌رونده شما نصب شده است یا خیر (خارج از محدوده)

وب‌سایت شما می‌تواند بررسی کند که آیا PWA شما نصب شده است یا خیر، حتی اگر صفحه خارج از محدوده PWA شما باشد. به عنوان مثال، یک صفحه فرود که از /landing/ ارائه می‌شود می‌تواند بررسی کند که آیا PWA ارائه شده از /pwa/ نصب شده است یا خیر، یا اینکه آیا صفحه فرود شما از www.example.com ارائه می‌شود و PWA شما از app.example.com ارائه می‌شود.

پشتیبانی شده در:

• فقط اندروید: کروم ۸۴ یا بالاتر

درباره وب‌سایت خود به PWA خود بگویید

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

یک فایل assetlinks.json به دایرکتوری /.well-known/ دامنه‌ای که PWA در آن قرار دارد، مثلاً app.example.com ، اضافه کنید. در ویژگی site ، مسیر کامل مانیفست برنامه وب که بررسی را انجام می‌دهد (نه مانیفست برنامه وب PWA شما) را ارائه دهید.

// Served from https://app.example.com/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.query_webapk"],
    "target": {
      "namespace": "web",
      "site": "https://www.example.com/manifest.json"
    }
  }
]

نکته حرفه‌ای: این یک آرایه است. این بدان معناست که می‌توانید یک رابطه تأیید شده بین PWA خود و بیش از یکی از وب‌سایت‌هایتان تعریف کنید.

در مورد PWA خود به وب‌سایتتان بگویید

در مرحله بعد، با اضافه کردن یک مانیفست برنامه وب به صفحه خود، در مورد برنامه PWA خود به وب‌سایت اطلاع دهید. مانیفست باید شامل ویژگی related_applications باشد، آرایه‌ای که جزئیات مربوط به PWA شما، از جمله platform و url را ارائه می‌دهد.

• platform باید webapp باشد
• url مسیر کامل به مانیفست برنامه وب PWA شما است.

{
  ...
  "related_applications": [
    {
      "platform": "webapp",
      "url": "https://app.example.com/manifest.json"
    }
  ]
  ...
}

نکته حرفه‌ای: این یک آرایه است. این بدان معناست که می‌توانید یک رابطه تأیید شده بین وب‌سایت خود و بیش از یکی از PWA های خود تعریف کنید.

بررسی کنید که آیا PWA شما نصب شده است یا خیر

در نهایت، تابع غیرهمزمان navigator.getInstalledRelatedApps() را فراخوانی کنید تا بررسی شود که آیا PWA شما نصب شده است یا خیر.

هنوز سوالی دارید؟

هنوز سوالی دارید؟ برچسب getInstalledRelatedApps را در StackOverflow بررسی کنید تا ببینید آیا کس دیگری سوالات مشابهی داشته است یا خیر. اگر نه، سوال خود را آنجا بپرسید و حتماً آن را با برچسب progressive-web-apps برچسب گذاری کنید. تیم ما مرتباً آن برچسب را رصد می‌کند و سعی می‌کند به سوالات شما پاسخ دهد.

بازخورد

آیا در پیاده‌سازی کروم اشکالی پیدا کردید؟ یا پیاده‌سازی با مشخصات متفاوت است؟

• یک اشکال را در https://new.crbug.com ثبت کنید. تا جایی که می‌توانید جزئیات را ذکر کنید، دستورالعمل‌هایی برای ایجاد مجدد اشکال ارائه دهید و در کادر Components عبارت Mobile>WebAPKs را وارد کنید.

لینک‌های مفید

• توضیح عمومی برای API برنامه‌های مرتبط با نصب
• پیش نویس مشخصات
• اشکال ردیابی
• ورودی ChromeStatus.com
• کامپوننت چشمک زن: Mobile>WebAPKs

ممنون

تشکر ویژه از سونگوک چو در مایکروسافت برای کمک در جزئیات آزمایش برنامه‌های ویندوز، و رایان کانسو برای کمک در جزئیات کروم.