Update dev portal doc for the new LoB app analytics

msteams-platform/concepts/build-and-test/analyze-your-apps-usage-in-developer-portal.md

@@ -5,7 +5,7 @@ ms.localizationpriority: medium
 ms.topic: overview
 ms.author: surbhigupta
 ms.owner: luywang
-ms.date: 12/15/2022
+ms.date: 04/30/2025
 ---
 
 # Analyze app usage in Developer Portal
@@ -16,7 +16,174 @@ Whether you're tracking active users, retention rates, or usage patterns across
 
 The app usage for a given day is reflected within 24 to 48 hours, and usage data for the new apps can take up to three to five days to reflect in the charts.
 
-# [Custom apps built for your org (LOB apps)](#tab/custom-apps-built-for-your-org)
+# [Custom apps (New)](#tab/custom-apps-built-for-your-org)
+
+### Prerequisite
+
+Your tenant admin must allow app usage for custom apps to show in Developer Portal. For more information, see [enable developers to use app analytics](/microsoft-365/admin/manage/enable-dev-analytics). A global admin or a Teams admin can enable it in the [Microsoft 365 admin center](https://admin.microsoft.com) by navigating to **Settings** > **Org settings** > **Services** > **Developer Portal for Teams**.
+
+   :::image type="content" source="../../assets/images/tdp/mac-setting.png" alt-text="Screenshot shows where admin can allow custom app analytics in Microsoft 365 admin center." lightbox="../../assets/images/tdp/mac-setting.png":::
+
+### Metric definitions
+
+| Metric | Definition |
+| :-----------------------| :------------------------------------------------------------------------------------------------------|
+| **Monthly active users (MAU)** | Number of unique users who performed an intentional activity with your app within that rolling 28 days window in UTC. |
+| **Weekly active users (WAU)** | Number of unique users who performed an intentional activity with your app within that rolling seven days window in UTC. |
+| **Daily active users (DAU)** | Number of unique users who performed an intentional activity with your app in a given day in UTC. |
+| **Monthly active tenants** | Number of unique tenants who performed an intentional activity with your app within that rolling 28 days window in UTC. |
+| **Weekly active tenants** | Number of unique tenants who performed an intentional activity with your app within that rolling seven days window in UTC. |
+| **Daily active tenants** | Number of unique tenants who performed an intentional activity with your app in a given day in UTC. |
+
+As you explore individual metrics on this page, you can use the **Filter** button to analyze your app's usage from the following filter options:
+
+* **Aggregation type**: This filter allows you to view active users or active tenants.
+* **Platform**: This filter allows you to group the metrics by the platform on which users performed intentional activities with your app. The platform can be **Desktop**, **Mobile**, or **Web**.
+* **Operating system**: This filter allows you to group the metrics by the operating system on which users performed intentional activities with your app. The operating system can be **Windows**, **Mac**, **iOS**, or **Android**, etc.
+* **Area**: This filter allows you to group the metrics by the geo location of the active usage.
+
+ :::image type="content" source="../../assets/images/tdp/filter-tdp-analytics.png" alt-text="Screenshot shows the app analytics page filter in Developer Portal." lightbox="../../assets/images/tdp/filter-tdp-analytics.png":::
+
+> [!TIP]
+> To know more about each metric definition, select **See metric definitions**. A pop-up help window appears on the right-side of the window with the required definitions.
+
+As you explore the app usage metrics on this page, you can see the following three sections:
+
+* [App usage](#app-usage)
+* [Host product](#host-product)
+* [App capability](#app-capability)
+
+### App usage
+
+ The **App usage** tab shows the following metrics:
+
+* [Usage over time](#usage-over-time)
+* [Usage by retention state](#usage-by-retention-state)
+* [Usage by country or region](#usage-by-country-or-region)
+* [Usage intensity](#usage-intensity)
+
+   :::image type="content" source="../../assets/images/tdp/tdp-app-usage.png" alt-text="Screenshot shows app usage chart of your published app in Developer Portal." lightbox="../../assets/images/tdp/tdp-app-usage.png":::
+
+#### Usage over time
+
+   Use the **Usage over time** chart to see how many users are using your app on a monthly, weekly, or daily basis.
+
+   :::image type="content" source="../../assets/images/tdp/tdp-usage-over-time.png" alt-text="Screenshot shows app usage over time of your published app in Developer Portal.":::
+
+#### Usage by retention state
+
+   Use the **Usage by retention state** chart to see how many users are new, returning, or disengaging with your app on a monthly, weekly, or daily basis.
+
+   :::image type="content" source="../../assets/images/tdp/tdp-retention.png" alt-text="Screenshot shows app usage by retention state of your published app in Developer Portal.":::
+
+   | Retention state | Definition |
+   | :-----------------------| :------------------------------------------------------------------------------------------------------|
+   | New users or tenants | Active users or tenants who used your app for the first time in the current time period. |
+   | Returning users or tenants | Active users or tenants who used your app during the current period and in the immediately preceding period. |
+   | Resurrected users or tenants | Active users or tenants who started using your app again in the current period, after a previous period of inactivity. |
+   | Lapsed users or tenants | Active users or tenants who stopped using your app in the current period, after a previous period of activity. |
+
+#### Usage by country or region
+
+   Use the **Usage by country/region** chart to understand global usage for the selected period. Each user is mapped to a single area or geography. You can select **View details** for more information on active users in different countries or regions.
+
+   :::image type="content" source="../../assets/images/tdp/tdp-country.png" alt-text="Screenshot shows app usage by country or region of your published app in Developer Portal." lightbox="../../assets/images/tdp/tdp-region.png":::
+
+#### Usage intensity
+
+   The **Usage intensity** chart shows frequency and depth of use. They're one indicator that users are finding value in continuing to use your app.
+
+   :::image type="content" source="../../assets/images/tdp/tdp-usage-intensity.png" alt-text="Screenshot shows app usage intensity of your published app in Developer Portal.":::
+
+   | Metric | Definition |
+   | :-----------------------| :------------------------------------------------------------------------------------------------------|
+   | **Median days used per month** | Median number of days in which your app was opened in the last month. |
+   | **% of 5+ Days usage** | Percentage of active users who opened or used your app more than five days in the last month. |
+   | **DAU/MAU** | Average number of daily active users (DAU) divided by monthly active users (MAU) for a rolling 30-day time period. |
+
+#### My app dashboard
+
+   The **My App Dashboard** table shows the latest R30 (Rolling 30 days) data for each of the metrics under the previous four categories, and the Month over Month change. Use the time picker on the upper left side and select the desired date to view the following:
+
+   * Select any day in the last 75 days to view daily R30 data.
+   * Select any end of month in the last 12 months to view R30 data.
+
+   You can select each of these metric names to see trends over time.
+
+   :::image type="content" source="../../assets/images/tdp/tdp-app-dashboard-view.png" alt-text="Screenshot shows app capability usage of your published app in Developer Portal." lightbox="../../assets/images/tdp/tdp-app-dashboard-view.png":::
+
+### Host product
+
+   The **Host product** tab shows the following app usage analytics:
+
+   * Usage by host product
+   * Usage by operating system
+   * Usage by platform
+
+   The first two scorecards display metrics such as the host with the most active users and the operating system (OS) with the most active users, based on monthly, weekly, and daily data.
+
+   :::image type="content" source="../../assets/images/tdp/tdp-host-product.png" alt-text="Screenshot shows app usage in different host products of your published app in Developer Portal." lightbox="../../assets/images/tdp/tdp-host-product-full.png":::
+
+#### Usage by host product
+
+   The **Usage by host product** chart shows your app's active usage across various host products, including **Microsoft 365 Copilot**, **Teams**, **Outlook**, and the **Microsoft 365 app**.
+
+   :::image type="content" source="../../assets/images/tdp/tdp-host-usage.png" alt-text="Screenshot shows app usage in different host product of your published app in Developer Portal.":::
+
+#### Usage by platform
+
+   The **Usage by platform** chart shows your app's active usage across various platforms, such as **Desktop**, **Mobile**, and **Web**.
+
+   :::image type="content" source="../../assets/images/tdp/tdp-usage-platform.png" alt-text="Screenshot shows app usage in different platforms of your published app in Developer Portal.":::
+
+   > [!NOTE]
+   >
+   > * The `Preview` tag indicates that the metric **Usage by host product** is in its initial phase and might undergo modifications as we collect feedback and continue to improve the experience.
+   > * The **Microsoft 365 Copilot Agent** includes usage of declarative agents only. The usage of the custom engine agent isn't available in the Developer Portal.
+
+#### Usage by operating system
+
+   The **Usage by operating system** chart shows your app's active usage across various operating systems, such as **Windows**, **Mac**, **iOS**, and **Android**.
+
+   :::image type="content" source="../../assets/images/tdp/tdp-operating-system.png" alt-text="Screenshot shows app usage in different OS of your published app in Developer Portal.":::
+
+### Capability
+
+  The **Capability** tab shows the usage of individual app capabilities that you've configured within your app.
+
+  This page summarizes the overall usage of the following app capabilities in different host products.
+
+   * Copilot Agent
+   * Bot
+   * Tab
+   * Message extension
+   * Personal app
+   * Connector
+   * Personal tab
+
+   :::image type="content" source="../../assets/images/tdp/tdp-app-capability.png" alt-text="Screenshot shows app capability usage in different host products of your published app in Developer Portal." lightbox="../../assets/images/tdp/tdp-app-capability.png":::
+
+   > [!NOTE]
+   >
+   > * The `Preview` tag indicates that the metric is in its initial phase and might undergo modifications as we collect feedback and continue to improve the experience.
+   > * The **Microsoft 365 Copilot Agent** includes usage of declarative agents only. The usage of the custom engine agent isn't available in the Developer Portal.
+
+### Known limitations
+
+* The usage data for message extension in Outlook and Outlook Add-in isn't available.
+* The usage data of the Outlook personal tab includes both personal tab and tab (meeting scenario) data.
+* The usage data for consumer apps isn't available.
+* The usage data for Android in Outlook, which doesn't have a tenant ID, isn't available.
+
+# [Custom apps (Deprecating)](#tab/custom-apps-deprecating)
+
+   > [!NOTE]
+   >
+   > * The current custom app analytics is being deprecated soon.
+   > * You can opt in to the new custom app analytics in Developer Portal by selecting the banner on the Analytics page.
+   > * Learn more about the new custom app analytics [here](/microsoftteams/platform/concepts/build-and-test/analyze-your-apps-usage-in-developer-portal?tabs=custom-apps-built-for-your-org).
+
+### Get Started
 
 You can view your custom app's usage and other insights from the **Analytics** page. To access the page:
 
@@ -116,6 +283,8 @@ You can view usage for your [third-party app](../../promote-app-adoption.md#acce
 
 To learn how to import your published app into Developer Portal, see [import an existing app](~/concepts/build-and-test/teams-developer-portal.md#import-an-existing-app).
 
+### Metric definitions
+
 | Metric | Definition |
 | :-----------------------| :------------------------------------------------------------------------------------------------------|
 | **Monthly R28 active users (MAU)** | The default usage metric. It shows the count of unique active users who used your app within that rolling 28 days window in UTC. |
@@ -219,7 +388,7 @@ As you explore the app usage metrics on this page, you can see the following thr
 
 #### Usage by host product
 
-   The **Usage by host product** chart shows your app's active usage across various host products, including **Teams**, **Outlook**, and the **Microsoft 365 app** of monthly, weekly, and daily data.
+   The **Usage by host product** chart shows your app's active usage across various host products, including **Microsoft 365 Copilot**, **Teams**, **Outlook**, and the **Microsoft 365 app** of monthly, weekly, and daily data.
 
    :::image type="content" source="../../assets/images/tdp/tdp-host-usage.png" alt-text="Screenshot shows the app usage in different host product of your published app in Developer Portal.":::
 
@@ -230,7 +399,9 @@ As you explore the app usage metrics on this page, you can see the following thr
    :::image type="content" source="../../assets/images/tdp/tdp-usage-platform.png" alt-text="Screenshot shows the app usage in different platforms of your published app in Developer Portal.":::
 
    > [!NOTE]
-   > The `Preview` tag indicates that the metric **Usage by host product** is in its initial phase and might undergo modifications as we collect feedback and continue to improve the experience.
+   >
+   > * The `Preview` tag indicates that the metric **Usage by host product** is in its initial phase and might undergo modifications as we collect feedback and continue to improve the experience.
+   > * The **Microsoft 365 Copilot Agent** includes usage of declarative agents only. The usage of the custom engine agent isn't available in the Developer Portal.
 
 #### Usage by operating system
 
@@ -244,17 +415,19 @@ As you explore the app usage metrics on this page, you can see the following thr
 
   This page summarizes the overall usage of the following app capabilities in different host products.
 
+* Copilot Agent
 * Bot
 * Tab
 * Message extension
 * Personal app
 * Connector
 * Personal tab
 
-   :::image type="content" source="../../assets/images/tdp/tdp-app-capability.png" alt-text="Screenshot shows the app capability usage in different host products of your published app in Developer Portal." lightbox="../../assets/images/tdp/tdp-app-capability.png":::
+   :::image type="content" source="../../assets/images/tdp/tdp-app-capability.png" alt-text="Screenshot shows the app capability usage in different host products of your published app in Developer Portal." lightbox="../../assets/images/tdp/tdp-app-capability-full.png":::
 
    > [!NOTE]
-   > The `Preview` tag indicates that the metric is in its initial phase and might undergo modifications as we collect feedback and continue to improve the experience.
+   > * The `Preview` tag indicates that the metric is in its initial phase and might undergo modifications as we collect feedback and continue to improve the experience.
+   > * The **Microsoft 365 Copilot Agent** includes usage of declarative agents only. The usage of the custom engine agent isn't available in the Developer Portal.
 
 ### Known limitations