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

msteams-platform/resources/teams-mobile-best-practices.md

@@ -60,6 +60,87 @@ To run a performance audit, follow these steps:
 
         :::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
+
+Identifying new or existing apps with low performance for compliance with best practices is crucial for operational effectiveness. The **Performance Report tool** (or Perf Report tool) not only allows you to assess performance of your mobile apps in absolute terms; but also helps you compare performance across different apps by benchmarking against recommended values. It's a self-serve, lightweight tool that can be run directly on your mobile (Android and iOS).
+
+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 via **Performance Report tool** for your mobile app, 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. Navigate to **Apps** section.
+
+1. Select the app you want to audit. The app home page appears.
+
+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.
+
+    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.
+
+    :::image type="content" source="../assets/images/tabs/lightweight-audit-tool/performance-report.png" alt-text="Screenshot shows the static html performance report" lightbox="../assets/images/tabs/lightweight-audit-tool/performance-report.png":::
+
+> [!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, a **Performance metrics could not be calculated. Please refresh or try again.** error message appears.
+
+### Access performance metrics report
+
+The report provides insights using browser and operating system-level 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.
+* **Forward in Teams**: Opens the device’s share menu for sharing in Teams.
+* **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.
+
+Section name | Description | Action |
+|----------- |-------------| ------ |
+| **Latency** | Measures the (approximate) time taken by your Teams mobile app to load.| <ul><li/> **If your app uses `notifySuccess()`**: Overall latency is shown at the top. A timeline displays the end time for each API call during app load. :::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. A dash or question mark replaces the latency value, and an error message prompts you to use the `notifySuccess()`API . :::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)** | Shows if [service worker](#use-service-workers-to-cache-static-assets) (SW) is enabled as a local caching mechanism. Available values are indicated in green and unavailable values are indicated in red.| If SW is not enabled, the report provides a link to relevant documentation to help you implement it in your app. <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** | Indicates the total size occupied by the bundle of JS files on your Teams mobile app. Ideal value is 1 MB.|   Click on **Check bundle files**. <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> A detailed list of files affecting bundle size appears.<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 reduce bundle size.|
+| **Content Paint Metrics** | 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" lightbox="../assets/images/tabs/lightweight-audit-tool/app-audit-report-content-paint-metrics.png":::|
+|**Disk Size**| Indicates the app size on your mobile device. If an app is larger than 20 MB, the metric is displayed in red else in green.| If the disk size can’t be calculated, an error message with the reason shows up in place of expected value. |
+
+> [!NOTE]
+>
+> * Latency is not calculated if `notifySuccess()` API isn't called from code.
+> * Using [service worker](#use-service-workers-to-cache-static-assets) optimizes app performance.
+> * Service worker is applicable only for reports generated from Android.
+
 ## See also
 
 * [Build tabs for Teams](../tabs/what-are-tabs.md)