[Doc Feature] [4106071 & 4106072] [Android & iOS] Self-Serve Lightweight Audit Tool]

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/14/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.| <ul><li/> **If your app uses `notifySuccess()`**: In this section, the app latency is calculated and displayed at the top. A timeline subsequently displays the end time for each API call during app load. <br> :::image type="content" source="../assets/images/tabs/lightweight-audit-tool/notify-success-called.jpg" alt-text="Screenshot shows the notification for apps calling notifySuccess()" lightbox="../assets/images/tabs/lightweight-audit-tool/notify-success-called.jpg"::: <br> <li/> **If your app doesn't use `notifySuccess()`**: Latency can’t be calculated. Use the link in the message that appears to implement `notifySuccess()`API for your app. :::image type="content" source="../assets/images/tabs/lightweight-audit-tool/latency-not-calculated.png" alt-text="Screenshot shows the error message for apps not calling notifySuccess()" lightbox="../assets/images/tabs/lightweight-audit-tool/latency-not-calculated.png":::</ul>|
+|**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. <br> When service worker is **Not Available**, use the **Learn more** link to proceed with implementation.<br> :::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. <br> :::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"::: <br> The files affecting bundle size appear in descending order of file size.<br> :::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"::: <br> <br> 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)