diff --git a/msteams-platform/assets/icons/generate-report-icon.png b/msteams-platform/assets/icons/generate-report-icon.png new file mode 100644 index 00000000000..78d37db2ad9 Binary files /dev/null and b/msteams-platform/assets/icons/generate-report-icon.png differ diff --git a/msteams-platform/assets/icons/kebab-icon.jpg b/msteams-platform/assets/icons/kebab-icon.jpg new file mode 100644 index 00000000000..e1eaa7c050d Binary files /dev/null and b/msteams-platform/assets/icons/kebab-icon.jpg differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/android-entry-point.jpg b/msteams-platform/assets/images/tabs/lightweight-audit-tool/android-entry-point.jpg new file mode 100644 index 00000000000..85c19bf7471 Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/android-entry-point.jpg differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-app-package.png b/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-app-package.png new file mode 100644 index 00000000000..9c04126bbd0 Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-app-package.png differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-caching.png b/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-caching.png new file mode 100644 index 00000000000..fa9eaa1e9e0 Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-caching.png differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-content-paint-metrics.png b/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-content-paint-metrics.png new file mode 100644 index 00000000000..3a2f1319d35 Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-content-paint-metrics.png differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-disk-size.png b/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-disk-size.png new file mode 100644 index 00000000000..7cb794e07db Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/app-audit-report-disk-size.png differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/calculating-metrics.jpg b/msteams-platform/assets/images/tabs/lightweight-audit-tool/calculating-metrics.jpg new file mode 100644 index 00000000000..8c2c7920009 Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/calculating-metrics.jpg differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/files-affecting-bundle-size.png b/msteams-platform/assets/images/tabs/lightweight-audit-tool/files-affecting-bundle-size.png new file mode 100644 index 00000000000..fdd890a1ad1 Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/files-affecting-bundle-size.png differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/latency-not-calculated.png b/msteams-platform/assets/images/tabs/lightweight-audit-tool/latency-not-calculated.png new file mode 100644 index 00000000000..3b1d73cfccb Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/latency-not-calculated.png differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/notify-success-called.jpg b/msteams-platform/assets/images/tabs/lightweight-audit-tool/notify-success-called.jpg new file mode 100644 index 00000000000..e1d18be0d8a Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/notify-success-called.jpg differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/performance-report-success-bottom-sheet.png b/msteams-platform/assets/images/tabs/lightweight-audit-tool/performance-report-success-bottom-sheet.png new file mode 100644 index 00000000000..951c3b4b5cd Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/performance-report-success-bottom-sheet.png differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/performance-report.png b/msteams-platform/assets/images/tabs/lightweight-audit-tool/performance-report.png new file mode 100644 index 00000000000..0c36fb0f514 Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/performance-report.png differ diff --git a/msteams-platform/assets/images/tabs/lightweight-audit-tool/self-serve-lightweight-developer-preview-toggle.jpg b/msteams-platform/assets/images/tabs/lightweight-audit-tool/self-serve-lightweight-developer-preview-toggle.jpg new file mode 100644 index 00000000000..6b0deeeb352 Binary files /dev/null and b/msteams-platform/assets/images/tabs/lightweight-audit-tool/self-serve-lightweight-developer-preview-toggle.jpg differ diff --git a/msteams-platform/resources/teams-mobile-best-practices.md b/msteams-platform/resources/teams-mobile-best-practices.md index 9c1247e62c7..31f7f6d2cd5 100644 --- a/msteams-platform/resources/teams-mobile-best-practices.md +++ b/msteams-platform/resources/teams-mobile-best-practices.md @@ -5,12 +5,12 @@ ms.author: surbhigupta description: Learn how to optimize your tab app performance on Teams mobile with best practices such as using service workers and performance audits. ms.localizationpriority: high ms.topic: conceptual -ms.date: 03/27/2025 +ms.date: 11/21/2025 --- # Best practices for Teams mobile apps - Mobile devices have limited processing power, network connectivity, and battery compared to desktops and laptops. If you want to increase the adoption of your Teams tab app on mobile devices, you must ensure a fast and responsive web experience on the Teams Android and iOS clients. This article outlines the best practices to optimize your Teams tab's webpages for the Teams mobile client. + Mobile devices have limited processing power, network connectivity, and battery compared to desktops and laptops. To increase the adoption of your Teams tab app on mobile devices, you must ensure a fast and responsive web experience on the Teams Android and iOS clients. This article outlines the best practices to optimize your Teams tab's webpages for the Teams mobile client. ## Use service workers to cache static assets @@ -20,7 +20,7 @@ ms.date: 03/27/2025 ### Sample app -Check out this [sample app](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/tab-support-offline/nodejs) that makes use of a service worker to cache data and provide offline functionality. +Check out this [sample app](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/tab-support-offline/nodejs) that uses a service worker to cache data and provide offline functionality. ## Minimize webpage size @@ -42,24 +42,102 @@ To run a performance audit, follow these steps: 1. Select the **Lighthouse** tab. This tab provides insights into the app size and performance metrics. - 1. Under **Device**, ensure that you select **Mobile**. + 1. Under **Device**, select **Mobile**. 1. Select **Analyze page load**. :::image type="content" source="../assets/images/tabs/dev-tools-lighthouse.png" alt-text="Screenshot shows the lighthouse tab under dev tools." lightbox="../assets/images/tabs/dev-tools-lighthouse.png"::: - The report shows various diagnostics for your app's webpage and a set of actionable insights to decrease page load. Ensure that you take the required steps to reduce the latencies flagged in this report. + The report shows various diagnostics for your app's webpage and a set of actionable insights to decrease page load. Take the required steps to reduce the latencies flagged in this report. -1. Select the **Coverage** tab. Your webpage might contain unused resources that don't provide any value to the functionality of the app. This tab allows you to see actual size and usage percentage of the resources on the webpage. +1. Select the **Coverage** tab. Your webpage might contain unused resources that don't provide any value to the functionality of the app. This tab allows you to see the actual size and usage percentage of the resources on the webpage. 1. If you can't find it in the home page of dev tools, go to **More tools** > **Coverage**. :::image type="content" source="../assets/images/tabs/enable-coverage-tools.png" alt-text="Screenshot shows how to enable coverage tools in dev tools." lightbox="../assets/images/tabs/enable-coverage-tools.png"::: - 1. You can use the report to remove unused code or resources. + 1. Use the report to remove unused code or resources. :::image type="content" source="../assets/images/tabs/coverage-tool-report.png" alt-text="Screenshot shows the report generated by the coverage tool." lightbox="../assets/images/tabs/coverage-tool-report.png"::: +## Calculate performance metrics for apps + +Use the self-serve, lightweight **Performance Report tool** (or Perf tool) to evaluate the efficiency of your web and tab apps on mobile. This tool runs seamlessly on both Android and iOS, and provides real-time performance metrics mapped against industry benchmarks, ensuring a superior user experience. It also enables you to implement Teams-specific best practices into your app directly from your mobile device. + +The steps involved are: + +1. [Generate performance metrics report](#generate-performance-metrics-report) +1. [Access performance metrics report](#access-performance-metrics-report) +1. [Analyze performance metrics report](#analyze-performance-metrics-report) + +> [!NOTE] +> +> For accurate latency calculation, ensure that your app calls the `notifySuccess()` API after it's fully loaded. + +### Generate performance metrics report + +To generate performance metrics report for your mobile app with the **Performance Report tool**, follow these steps: + +1. On your Teams mobile app, go to **Settings** > **About** > **Developer preview** and toggle the switch to enable **Developer preview**. + + :::image type="content" source="../assets/images/tabs/lightweight-audit-tool/self-serve-lightweight-developer-preview-toggle.jpg" alt-text="screenshot shows the Developer Preview toggle in Teams settings" lightbox="../assets/images/tabs/lightweight-audit-tool/self-serve-lightweight-developer-preview-toggle.jpg"::: + +1. Go to the **Apps** section. + +1. Open the app you want to audit, wait for it to load. + +1. To generate the report + * On Android app: + + 1. Select the kebab :::image type="icon" source="../assets/icons/kebab-icon.jpg" border="false"::: menu. + + 1. Select **Generate Performance Report**. + + :::image type="content" source="../assets/images/tabs/lightweight-audit-tool/android-entry-point.jpg" alt-text="Screenshot shows the entry point for Android audit tool" lightbox="../assets/images/tabs/lightweight-audit-tool/android-entry-point.jpg"::: + + * On iOS app, select the audit app performance :::image type="icon" source="../assets/icons/generate-report-icon.png" border="false"::: icon that appears on the title bar. + + An interim page appears while the report is being generated for both Android and iOS. + +1. After the report is generated, access it from the bottom sheet that appears with the html performance report. + +> [!NOTE] +> +> * There's no restriction on the number of times that a report can be generated for an app. +> * The generated report is a static html page whose contents remain unchanged throughout the journey. A new report is generated only when you repeat the report generation process. +> * Refreshing or navigating away interrupts the process. +> * If the report isn't generated, an error message appears. + +### Access performance metrics report + +The report provides insights using JavaScript SDK and WebView APIs, along with Teams-specific performance markers. + +You can access the report from the following options on the bottom sheet: + +* **Open Report**: Opens the report in a new browser window. +* **Share report**: Opens the device’s options for sharing outside Teams on Android. On iOS, this option opens the device’s share menu. +* **Forward in Teams**: Opens the device’s share menu for sharing in Teams. This option is available only on Android. +* **Download**: Downloads the report in the device’s local storage. + + :::image type="content" source="../assets/images/tabs/lightweight-audit-tool/performance-report-success-bottom-sheet.png" alt-text="report-success-bottom-sheet" lightbox="../assets/images/tabs/lightweight-audit-tool/performance-report-success-bottom-sheet.png"::: + +### Analyze performance metrics report + +The performance metrics report contains the following metrics. + +| Metric | Description | System response/Action required | +|----------- |-------------| ------ | +|**Latency** | This metric measures the (approximate) time taken by your Teams mobile app to load.| | +|**Caching (Service Worker)** | This metric shows if [service worker](#use-service-workers-to-cache-static-assets) is implemented as a local caching mechanism. Service worker is available only on Android.| If service worker is implemented, **Available** is displayed in green, else **Not Available** is displayed in red.
When service worker is **Not Available**, use the **Learn more** link to proceed with implementation.
:::image type="content" source="../assets/images/tabs/lightweight-audit-tool/app-audit-report-caching.png" alt-text="screenshot shows caching status for Android" lightbox="../assets/images/tabs/lightweight-audit-tool/app-audit-report-caching.png"::: | +| **App Package** | This metric indicates the total size occupied by platform app's JavaScript file bundle.| Ideal package size is up to 1 MB. If package size exceeds the ideal size, the size is displayed in red. Select **Check bundle files** to get a detailed list of files affecting bundle size.
:::image type="content" source="../assets/images/tabs/lightweight-audit-tool/app-audit-report-app-package.png" alt-text="Screenshot shows ideal app package size with link to relevant documentation" lightbox="../assets/images/tabs/lightweight-audit-tool/app-audit-report-app-package.png":::
The files affecting bundle size appear in descending order of file size.
:::image type="content" source="../assets/images/tabs/lightweight-audit-tool/files-affecting-bundle-size.png" alt-text="Screenshot shows the files affecting bundle size" lightbox="../assets/images/tabs/lightweight-audit-tool/files-affecting-bundle-size.png":::

Use [service worker](#use-service-workers-to-cache-static-assets) and other [best practices](#best-practices-for-teams-mobile-apps) to optimize your app's performance.| +| **Content Paint Metrics** | This metric indicates all relevant content paint metrics (and their values) for your mobile app. | Content paint metrics show how fast visual elements appear while your app page loads. Use this data to identify and fix delays in visual content rendering.:::image type="content" source="../assets/images/tabs/lightweight-audit-tool/app-audit-report-content-paint-metrics.png" alt-text="screenshot shows content paint metrics"::: +|**Disk Size**| Indicates the app size on your mobile device. | Ideal limit is 20 MB. If an app is larger than the ideal limit, the metric is displayed in red else in green. If your app's disk size can’t be calculated, an error message shows up. :::image type="content" source="../assets/images/tabs/lightweight-audit-tool/app-audit-report-disk-size.png" alt-text="perf report disk size metric":::| + +> [!NOTE] +> +> * Latency isn't calculated if `notifySuccess()` API isn't called from code. +> * Use [service worker](#use-service-workers-to-cache-static-assets) caching mechanism as one way to optimize app performance. + ## See also * [Build tabs for Teams](../tabs/what-are-tabs.md) diff --git a/msteams-platform/whats-new.md b/msteams-platform/whats-new.md index 263f5191b7f..86df4f8029d 100644 --- a/msteams-platform/whats-new.md +++ b/msteams-platform/whats-new.md @@ -38,6 +38,8 @@ Teams platform features that are available to all app developers.
**2025 November** +* ***November 21, 2025***: [Use the Performance Report tool to evaluate the efficiency of your web and tab apps on mobile.](resources/teams-mobile-best-practices.md#calculate-performance-metrics-for-apps) + * ***November 19, 2025***: [Create and manage agent identities for your agent.](concepts/build-and-test/manage-your-apps-in-developer-portal.md#agent-identity-blueprint) * ***November 19, 2025***: [Microsoft Entra ID authentication for bots is now available in group scope.](bots/how-to/authentication/bot-sso-overview.md)