+ Title: Enable app caching for your tab app

+description: Learn how to enable app caching to your tab app in Teams meeting and how it improves the launch time of the app.

+ms.localizationpriority: high

+# Enable app caching for your tab app

+> [!NOTE]

+> App caching is available only in [public developer preview](~/resources/dev-preview/developer-preview-intro.md).

+You can configure your tab app (app) to enable app caching to reduce the reload time of your app during a meeting. You can store your app data in the meeting by enabling app caching. The app reloads from the cache, which improves the app relaunch time within the meeting. App caching is supported only for tabs loaded in the meeting side panel in Teams desktop client.

+Here's what you'll learn in this section:

+1. App caching user experience

+1. App caching at runtime

+1. Enable app caching

+## App caching user experience

+App caching improves subsequent launch time of the apps that are loaded in the meeting side panel. Consider the following use case for app caching:

+Your app is enabled to be installed in a Teams meeting. The meeting organizer or participants can install and use your app.

+ :::column span="":::

+ :::image type="content" source="../assets/images/app-caching/without-app-caching.png" alt-text="The screenshot shows you the app in meeting without app caching enabled." lightbox="../assets/images/app-caching/without-app-caching.png":::

+ :::column-end:::

+ :::column span="":::

+ During the meeting, the participants may change the view from your app to another view on the meeting stage. When they want to open your app again, the app must go through the launch process again before it can be opened in the meeting window. This takes up time in the meeting as participants are kept waiting while the app reloads.

+ :::column-end:::

+ :::column span="":::

+ :::image type="content" source="../assets/images/app-caching/with-app-caching.png" alt-text="The Screenshot shows you the app in meeting with app caching enabled." lightbox="../assets/images/app-caching/with-app-caching.png":::

+ :::column-end:::

+ :::column span="":::

+ With **app caching**, you can now reduce the reload time significantly. An app cache is a data storage layer that stores your app data in the meeting side panel. When the participants move away from the app and come back to it, the app is loaded from the app cache rather than being relaunched. It enhances the meeting experience of the participants, saves time and resources.

+ :::column-end:::

+## App caching at runtime

+When you enable app caching in your app, you can add it to a meeting and the app opens in a webview. The app data is stored in the meeting side panel. If the participants move away from the app within the meeting window, the webview that is used to host the embedded app is reused. The webview that hosts the app is hidden when the participants move away from the app and shown when they come back to the app. At this time, the app is reloaded from the cache.

+This process consists of two stages for an app that is enabled for app caching:

+1. [First launch of the app](#first-launch-of-the-app)

+1. [Reload app from cache](#reload-app-from-cache)

+### First launch of the app

+The following flow diagram shows how the app loads for the first time it's launched in the meeting. The app registers the `load` or `beforeUnload`:

+| # | Interaction | What's going on |

+| | | |

+| 1. | Teams client → App | Teams client launches the app to the meeting side panel. |

+| 2. | App → Teams client | The app initializes the flow. |

+| 3. | App → Teams client | The app registers `Load` or `beforeUnload` handler with Teams clients and caches the app data in the meeting side panel. |

+| 4. | App → Teams client | The app invokes SDK `notifySuccess` to notify Teams client that the initialization flow is complete. |

+| 5. | Teams client → App | When the participants move away from the app, Teams client disposes resources and performs any cleanup needed in the `beforeUnload` handler. |

+| 6. | App → Teams client | The app invokes the `readyToUnload` callback to notify Teams client that the app unload flow is complete. |

+### Reload app from cache

+The following flow diagram shows how a cached app is reloaded:

+| # | Interaction | What's going on |

+| | | |

+| 1. | Teams client → App | Teams client loads the app and invokes `Load` callback. |

+| 2. | App → Teams client | The app uses `contentUrl` and `entityId` to route to the desired page, and then invokes SDK `notifySuccess` to notify Teams client that the initialization flow is complete. |

+| 3. | Teams client → App | When the participants move away from the app, Teams client disposes resources and performs any cleanup needed in the `beforeUnload` handler. |

+| 4. | App → Teams client | The app invokes the `readyToUnload` callback to notify Teams client that the app unload flow is complete. |

+## Enable app caching

+Before you enable app caching for your app, you must [enable your app for Teams meeting](build-tabs-for-meeting.md).

+To enable app caching for your app, follow the steps:

+1. In the `configure.jsx` file (or the equivalent file in your app), pass `contentUrl` and `entityId` into the load handler to route to the correct page within your app. It also invokes `notifySuccess` or `notifyFailure` to notify Teams client when the app initialization flow is complete.

+ * [contentUrl](../tabs/how-to/create-tab-pages/configuration-page.md#modify-or-remove-a-tab): Add content page URL.

+ * [entityId](../tabs/how-to/create-tab-pages/configuration-page.md#modify-or-remove-a-tab): Add a unique identifier.

+1. In the `app-cache-tab.tsx` file (or the equivalent file in your app), configure the following:

+ * Call `teamsCore.registerBeforeUnloadHandler` and `teamsCore.registerOnLoadHandler` APIs.

+ * Dispose resources and perform any cleanup needed in the `beforeUnload` handler.

+ * Invoke the `readyToUnload` callback to notify Teams client that the app unload flow is complete.

+After you configure your app code for app caching, your code must be as shown in the following example:

+```javascript

+/// </summary>

+/// In beforeUnloadHandler using setItems and readyToUnload callback function

+/// </summary>

+const beforeUnloadHandler = (

+ setItems: React.Dispatch<React.SetStateAction<string[]>>,

+ readyToUnload: () => void) => {

+ setItems((Items) => [...Items, logItem("OnBeforeUnload", "purple", "Started")]);

+ // Dispose resources and cleanup

+ // Write your custom code to perform resource cleanup.

+ setItems((Items) => [...Items, logItem("OnBeforeUnload", "purple", "Dispose resources and cleanup")]);

+ setItems((Items) => [...Items, logItem("OnBeforeUnload", "purple", "Completed")]);

+ console.log("sending readyToUnload to TEAMS");

+ readyToUnload();

+ return true;

+};

+/// </summary>

+/// loadHandler using setItems to set values

+/// </summary>

+const loadHandler = (

+ setItems: React.Dispatch<React.SetStateAction<string[]>>,

+ data: microsoftTeams.LoadContext) => {

+ setItems((Items) => [...Items, logItem("OnLoad", "blue", "Started for " + data.entityId)]);

+ // Use the entityId, contentUrl to route to the correct page within your App and then invoke notifySuccess

+ setItems((Items) => [...Items, logItem("OnLoad", "blue", "Route to specific page")]);

+ setItems((Items) => [...Items, logItem("OnLoad", "blue", "Completed for " + data.entityId)]);

+ microsoftTeams.app.notifySuccess();

+};

+const AppCacheTab = () => {

+ const [items, setItems] = useState<string[]>([]);

+ const [title, setTitle] = useState("App Caching Sample");

+

+ React.useEffect(() => {

+ let app = microsoftTeams.app;

+ app.initialize().then(app.getContext).then((context: any) => {

+ app.notifySuccess();

+ // Check if the framecontext is set to sidepanel

+ if (context.page.frameContext === "sidePanel") {

+ const loadContext = logItem("Success", "green", "Loaded Teams context");

+ setItems((Items) => [...Items, loadContext]);

+ const newLogItem = logItem("FrameContext", "orange", "Frame context is " + context.page.frameContext);

+ setItems((Items) => [...Items, newLogItem]);

+ microsoftTeams.teamsCore.registerBeforeUnloadHandler((readyToUnload: any) => {

+ const result = beforeUnloadHandler(setItems, readyToUnload);

+

+ return result;

+ });

+ microsoftTeams.teamsCore.registerOnLoadHandler((data: any) => {

+ loadHandler(setItems, data);

+ setTitle("Entity Id : " + data.entityId);

+ console.log(data.contentUrl, data.entityId);

+ });

+ const newItem = logItem("Handlers", "orange", "Registered load and before unload handlers. Ready for app caching.");

+ setItems((Items) => [...Items, newItem]);

+ }

+ }).catch(function (error: any) {

+ console.log(error, "Could not register handlers.");

+ });

+ return () => {

+ console.log("useEffect cleanup - Tab");

+ };

+ }, []);

+ return (

+ <div>

+ <h3>{title}</h3>

+ {items.map((item) => {

+ return <div dangerouslySetInnerHTML={{ __html: item }} />;

+ })}

+ </div>

+ );

+};

+export default AppCacheTab;

+```

+## Best practices

+* Single-page apps that use client-side routing for page navigation can benefit from app caching. It's recommended that you use the same domain across all contexts of your app launch.

+* Register the `load` and `beforeUnload` handlers early in your launch sequence. If the handlers aren't registered with the Teams client before the participants move away from the app, the app isn't cached.

+* To enable app caching support in Teams meetings, register the `load` or `beforeUnload` handlers only if the context is `sidePanel`.

+* Register only the `beforeUnload` handler if your app doesn't require app caching but needs time to safely save state (as leaving the app can cause the app content to be abruptly removed from the Document Object Model (DOM)). If the app hasn't registered for the `load` event, it's removed from the DOM after the unload flow completes.

+## Limitations

+* App caching is disabled if the system memory is less than 4 GB or if the available memory is less than 1 GB on Windows or 512 MB on Mac.

+* App caching isn't supported for meetings where the invited participant count is more than 20.

+* When the app is cached, any audio that is playing within the cached app is muted.

+* Apps need to re-register for events in the load handler, such as `themeChange`, `focusEnter`, and so on. Teams client won't send any notifications to the app when it's cached. If your app requires notifications even when cached, caching might not be the right solution.

+* App caching is supported only in Teams desktop client. In Teams web client, even if the app registers load handlers, the app is removed from the cache after the unload sequence is completed.

+* The Teams client invokes the `loadHandler` only after the `unload` sequence of the app is completed. For example, if a participant launches tab A of your app and then launches tab B of the same app, tab B won't get the `Load` callback for caching until tab A invokes the `readyToUnload` callback.

+* Apps are cached on a per-window basis. An app cached in a meeting window can't be reused in a channel in the Teams client.

+* App caching happens on a per app (not on a per tab) basis within the same meeting window. The same meeting webview gets reused as participants launch your app from various contexts (such as channels, chat, personal app).

+* App caching isn't supported for the meeting stage or task module contexts because these can be opened on top of the app. The same webview can't be used to render the content in the tab and the task module.

+* The `sidePanel` is the only supported `FrameContext` for app caching.

+* Apps are expected to sleep when cached (use minimal compute or network resources and minimizes SDK requests). All the register handlers and the following SDK requests are allowed when the app is cached:

+ * `initialize`

+ * `notifyAppLoaded`

+ * `notifySuccess`

+ * `notifyFailure`

+ * `notifyExpectedFailure`

+ * `getContext`

+ * `getAuthToken`

+ * `readyToUnload`

+ * `getConfig` or `getSettings`

+* The app isn't cached if Teams client doesn't receive the `readyToUnload` callback from the app within 30 seconds after sending the `beforeUnload` notification.

+## Troubleshooting

+**Why isn't my app getting cached?**

+Apps aren't cached if the load handler isn't invoked on subsequent navigation. To resolve this issue, ensure the following:

+* App caching requires minimum of 4 GB system memory. Ensure there's sufficient system memory for app caching.

+* Reduce your memory footprint by using the `beforeUnload` handlers to dispose resources that aren't needed when your app is cached.

+**Why are apps removed from cache?**

+* If the system memory load is high, the app is removed from the cache. Ensure that your system memory load isn't high.

+* If the participant doesn't come back to the app within 20 minutes, the app is removed from the cache.

+* If the number of cached apps exceed the maximum cache size, the oldest cached app is removed from the cache. Ensure you don't exceed the maximum cache size.

+## Code sample

+|Sample name | Description | Node.js |

+|-|--|-|

+| App caching in meeting | Sample app to show how app caching works for tab app in Teams meeting. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/app-cache-meetings/nodejs) |

+## See also

+* [Build tabs for meeting](build-tabs-for-meeting.md)

+* [Build tabs for Teams](../tabs/what-are-tabs.md)

+### Advanced tab APIs

+TeamsJS is a rich library used to create Tabs using JavaScript. Use the latest TeamsJS (V.2.0 or later) to work in Teams, Microsoft 365 app, and Outlook. For more information, see [Teams JavaScript client library](/microsoftteams/platform/tabs/how-to/using-teams-client-library).

+### Frame context

+Microsoft Teams JavaScript library exposes the frameContext in which your meeting tab URL is loaded in the getContext API. The possible values of frameContext are content, task, setting, remove, sidePanel, and meetingStage. This allows you to build customized experiences based on where the app renders. For example, showing a specific collaboration focused UI when in the `meetingStage` and a different meeting preparation UI in the chat tab (`content`). For more information, see [getContext API](/microsoftteams/platform/tabs/how-to/access-teams-context?tabs=teamsjs-v2).

+## Enable your tabs for Teams meeting

+### Scope

+### Context

+### Configure tab app for a meeting

+### Other examples

+## Next step

+> [!div class="nextstepaction"]

+> [Enable app caching for your tab app](app-caching-for-your-tab-app.md)

+description: In this article, learn how apps works in Microsoft Teams meeting based on participant and user role and app extensibility.

+### App caching for tab app in Teams meeting

+You can configure your tab app to enable app caching to reduce the reload time of your app during a meeting. The app reloads from the cache, which improves the app relaunch time within the meeting. For more information, see [enable app caching for your tab app](app-caching-for-your-tab-app.md).

+* [Bot Framework Composer](/composer/introduction)

+You can develop Teams apps in any web programming technology and call the [Bot Framework REST APIs](/bot-framework/rest-api/bot-framework-rest-overview) directly. You must perform token handling in all cases.

+* [Channel and group chat conversations with a bot](how-to/conversations/channel-and-group-conversations.md)

+It's recommended to start with [build your first bot app using JavaScript](../sbs-gs-bot.yml) or [build notification bot with JavaScript](../sbs-gs-notificationbot.yml) by using the new generation development tool for Teams. For more information, see [Teams Toolkit overview](../toolkit/teams-toolkit-fundamentals.md).

+> * Bots are available in Government Community Cloud (GCC) and GCC-High but not in Department of Defense (DOD).

+- [Microsoft Graph authentication provider based on scenario](/graph/sdks/choose-authentication-providers)

+You can provide additional .json files with translations of all the user facing strings in your manifest. These files must adhere to the [Localization file JSON schema](../../resources/schem) and they must be added to the `localizationInfo` property of your manifest. Each file correlates to a language tag, which the Microsoft 365 host application, such as Teams or Outlook, uses to select the appropriate strings. The language tag takes the form of `<language>-<region>` but you can omit the `<region>` portion to target all regions that support the desired language.

+The Microsoft 365 host application applies the strings in the following order: default language strings -> user's language only strings -> user's language + user's region strings.

+1. The Microsoft 365 host application takes the 'fr' strings and overwrites them with the 'en' strings.

+1. The Microsoft 365 host application takes the 'fr' strings and overwrites them with the 'en' strings.

+If the user's language is set to 'es-es', the Microsoft 365 host application takes the 'fr' strings. The Microsoft 365 host application doesn't override the strings with any of the language files as no 'es' or 'es-es' translation is provided.

+ Each app includes an **Owners** page, where you can share your app registration with others in your org. You can add **Administrator** and **Operative** role to manage who can change the settings of your app. The **Operative** role has a permission, such as updating an app's configuration. The **Administrator** role has the permissions, such as updating an app's configuration, adding or removing owners, and deleting an app. If there are no active owners for an app, Tenant admins can own the apps by entering the app ID in Teams Developer Portal.

+1. Log in to the Teams client with your [Microsoft 365 development account](https://developer.microsoft.com/microsoft-365/dev-program).

+1. Select **Apps** > **Manage your apps** and **Upload an app**.

+ Your app is hosted using Azure resources.

+ Your app is hosted using Azure resources.

+> [!WARNING]

+> After an in-market app on the Teams platform is updated to a new manifest version, users enrolled for Microsoft 365 Targeted Release will lose access to the app. For more information, see [Manage access to Teams apps across Microsoft 365](/microsoftteams/manage-third-party-teams-apps).

+Enrollment to [Microsoft 365 Targeted Release](/microsoft-365/admin/manage/release-options-in-office-365) and [Microsoft 365 Apps update channel](/deployoffice/change-update-channels) requires admin opt-in for the entire organization or selected users. For more information, see [Manage access to Teams apps across Microsoft 365](/microsoftteams/manage-third-party-teams-apps). Update channels are device specific and apply only to installations of Microsoft 365 running on Windows.

+From the **Apps** menu, select **Manage your apps** > **Upload an app** > **Submit an app to your org**. To submit an app requires approval from your IT admin.

+ Title: Facilitate adoption of your app and create awareness

+description: Learn about the best practices and guidance for app adoption and promotion.

+ms.localizationpriority: medium

+# Five steps to drive adoption of your app

+As an app developer, one of the key activities after publishing your Microsoft Teams app is to drive adoption for your app with your customers. Ensure that the users interact with your app and you [learn from their usage behavior and feedback](/microsoftteams/teams-analytics-and-reports/app-usage-report). You incorporate the learning in your app revisions. Examples of post-publish activities are deployment and adoption-related engagements, user base growth, support for existing app customers, app updates, and app monetization.

+This document provides resources and best practices to support the rollout of your Teams app in your customersΓÇÖ organizations. The relevant personas are the business decision makers, IT admins, and users. The outcome of an app rollout is the successful adoption and engagement by the users of your customerΓÇÖs organization.

+## Prerequisites before your customers roll out your app

+Your customers must have the following access to roll out your Teams app:

+1. Access to Teams

+1. Access to your apps

+### Access to Teams

+Customers need to have appropriate licenses to access Teams and use the apps. To use apps on Teams, users must be signed in to Teams and have a license for [Microsoft 365 Business Basic](https://www.microsoft.com/microsoft-365/business/compare-all-microsoft-365-business-products-b) or higher. If customers arenΓÇÖt already using Teams, then recommend to adopt Microsoft Teams first. For Teams adoption guidance, see [Microsoft Teams Adoption](https://adoption.microsoft.com/microsoft-teams/).

+If you're a Microsoft Partner, you can work with your Microsoft counterpart to facilitate Teams adoption. If you want to become a Microsoft Partner, see [ISV success program overview](https://www.microsoft.com/isv/program-benefits).

+### Access to your apps

+Ensure that the users have access to and appropriate licenses for your app on Teams. There are two types of apps available for your users:

+* **Custom apps**: Custom apps are developed specifically for an organization and are made available by admins in Teams within their organization.

+* **Third-party apps**: Teams store provides many useful apps created by third-party software developers in addition to apps created by Microsoft. For the apps created by third-party providers, Microsoft does rigorous validation of functionality and security. For more information, see [Understand third-party apps in Microsoft Teams](/microsoftteams/overview-third-party-apps).

+Admins can set up an app governance process that manages your organization's IT policies, standards, and risk profiles. For more information. For more information, see [Create policies for app access](#create-policies-to-give-permission-to-use-apps-and-pin-it).

+## Understand how you can drive app adoption

+Following the below five easy steps, you can encourage customers to adopt your apps through admin recommendations to their users, for maximum adoption in an organization. Consider the following elements for app adoption.

+1. **[Perform internal enablement to support app adoption](#perform-internal-enablement-to-support-app-adoption)**: Share your app information and its importance with your customer-facing teams, such as CSM, support, marketing, and sales that help customers adopt your apps. To achieve this, provide an adoption toolkit, define a rollout process, and give enablement training for your customer-facing teams.

+1. **[Help admins to do app configuration and rollout](#help-admins-to-do-app-configuration-and-rollout-for-their-users)**: Help the IT admins do the necessary configurations to enable your app for the users. Provide a help guide for IT admins to understand the configuration steps.

+1. **[Educate users and drive adoption change management for your app](#educate-users-and-drive-adoption-change-management-for-your-app)**: Provide user guide for the users that describes their jobs to be done (JTBD) and your appΓÇÖs features. Promote awareness about your app and its use cases. You can conduct email campaigns, webinars, or social media engagements depending on your target audience.

+1. **[Provide support contact for IT admins and users](#provide-support-information-for-it-admins-and-users)**: When admins or users encounter unknown issues or issues that can't be resolved using the documentation, they might reach for support. Providing support in such scenarios is helpful for healthy retention of users.

+1. **[Track app adoption and usage using analytics](#track-app-adoption-and-usage-using-analytics)**: Track your app adoption progress after the rollout and promptly resolve issues for the early adopters. Your CSM or account manager can engage with the customer's organization and its IT admins to track adoption and provide support.

+## Perform internal enablement to support app adoption

+Within your organization, you must streamline the app support and guidance programs. Internal readiness and enablement training programs helps to create good content, do targeted marketing, create an informed support team, and streamline the sales. All these activities and assets in turn ensure smooth app adoption journey for your customers.

+You must define a rollout process for your Teams app and ensure that:

+* Follow a standard rollout process for onboarding a new customer on the Teams app. For example, if youΓÇÖre onboarding a customer on your SaaS application and that customer also uses Teams, consider Teams app onboarding as part of your standard onboarding.

+* Support professionals and CSMs are trained and familiar with the nuances of your app, its value proposition, features, configuration steps, and the rollout process. For more information, see [deployment guidance for admins](#help-admins-to-do-app-configuration-and-rollout-for-their-users).

+### App installation and configuration guide

+The target audience for this guide is the IT admins in your customer's organization. The guide must contain the following technical information to help them configure your apps on Teams:

+* Prerequisites to install your app.

+* How to configure security settings and permissions.

+To learn and understand how an IT admin can configure your app, see [Help IT admins get your app adopted by their users](#help-admins-to-do-app-configuration-and-rollout-for-their-users). Also, see the [Documentation for IT admins and decision makers](#documentation-requirements-for-it-admins), which contains a checklist of best practices and information required for an IT admin that needs to be included.

+### User guide to describe features to users

+Provide a user guide for your app and cover the following topics:

+* Installation instructions for your app from the Teams store.

+* Key features and use cases of your app. For more information, see [Provide your app's use cases](#provide-a-feature-guide-for-the-users-of-your-app).

+* How can users reach you for support?

+* What are the user configuration settings, for example, profile setup?

+For more information, see [drive awareness about features with users](#educate-users-and-drive-adoption-change-management-for-your-app).

+### User awareness campaign and assets for organizations to drive adoption change management

+Awareness and training are the marketing and enablement segments of your overall app adoption strategy. This will ensure the users are aware of the capabilities of your app and encourages them to install and sign into your app on Teams.

+A campaign must be at the correct time in the adoption life cycle. Contextual reminders after a campaign can help drive the adoption. For example, a campaign that has communications spanning across pre-rollout days to build excitement, at the time of rollout to inform, and post-rollout to serve as a reminder.

+Post-adoption, there's a need for continuous engagement to help existing users with their tasks and to gradually onboard late adopters. You can host interactive sessions with the community such as support webinars and office hours. You can build a community around your app, answer queries, recognize top users or MVPs in your community, and do other similar activities.

+For help on creating these assets, register for the [ISV success program overview](https://www.microsoft.com/isv/program-benefits).

+[Back to top](#understand-how-you-can-drive-app-adoption)

+## Help admins to do app configuration and rollout for their users

+Admins can set up an app governance process that manages your organization's IT policies, standards, and risk profiles. Admins control the availability of apps and influence the adoption of apps within their organizations.

+Teams admin center provides admins with enterprise-grade controls and configurations to govern the apps. IT admins control availability of apps for each user in various contexts, such as meetings, chats, and channels. IT admins accomplish the following tasks:

+* Evaluate and allow apps.

+* Define app availability for the required users using permission policies for access.

+* Add apps for some or all users using setup policies for rollout.

+* Allow apps to access organization and user information by providing admin consent.

+* Buy and manage licenses and subscriptions for paid apps.

+* Upload and manage custom apps in their org-specific app catalog.

+* Customize an app to update its metadata to suit their org-specific requirements, if the app allows it.

+The IT admins attend to various tasks for smoother operations on a daily basis. Sharing the following resources with them helps in their app evaluation and rollout journey.

+### Evaluate and allow apps

+Before the IT admins approve the usage of your app and let the users use it, they need to understand the permissions required by the app and various details about the security, compliance, privacy, and data handling of the app. After an admin evaluates the app to be relevant and safe for their users, they allow the app in their tenant or organization.

+Consider providing the following information to help admins evaluate your app:

+* Detailed documentation of your app that provides information about data security, compliance certification, privacy policies and GDPR, data flow, app architecture, and other required information.

+* Describe the [permissions that your app needs](/microsoftteams/app-permissions-admin-center) to accomplish the use cases.

+* Use the [Microsoft compliance program](/microsoftteams/overview-of-app-certification) that checks and audits an app against controls that are derived from leading industry-standard frameworks. The various tiers of the program are Publisher verification, Publisher attestation, and Microsoft 365 certification that induces trust for admins and users.

+If you [block an app by default](concepts/design/enable-app-customization.md), provide documentation for the requirements before admins can allow the app. For example, the required configuration or subscription purchase that admins must do.

+If admins block any apps in their tenant, they receive [app approval requests from users](/microsoftteams/user-requests-approve-apps). Add guidance in your documentation for admins to consider these requested apps for evaluation before allowing.

+After an admin evaluates the app to be relevant and safe for their organizationΓÇÖs users, they [allow the app](/microsoftteams/manage-apps) in their tenant or organization.

+### Create policies to give permission to use apps and pin it

+Microsoft Teams uses app policies to govern access and handle installation behavior of apps. App policies help Teams admins control the following app actions:

+* Allow individual user or a group of users to use an app.

+* Pin an app for users for quick access.

+* Install apps without user intervention to get started with the relevant apps.

+With the help of the following app policies, admins can manage the aforementioned actions:

+* **App permission policies**: Admins can use app permission policies to control user-specific apps in their organization. They can allow a few apps for all users, a few for a specific group, or specific apps for specific users. For more information, see [app permission policies](/microsoftteams/teams-app-permission-policies).

+* **App setup policies**: App setup policies allow admins to configure how and where apps are available for users in their Teams client. They can choose the apps to pin to the app bar in the Teams client and define the order in which the apps are displayed. For more information, see [app setup policies](/microsoftteams/teams-app-setup-policies).

+### Understand app permissions and grant consent

+If your app accesses any data outside Teams, it does that using Microsoft Graph API calls. Teams requires an explicit consent to be granted for such app permissions. Teams admins review and grant consent to the app on behalf of their users. Each user might not be required to review and accept the app permissions when they use your app. For more information, see [view app permissions and grant admin consent](/microsoftteams/app-permissions-admin-center).

+### Buy and manage licenses and subscriptions for paid apps

+Your app might require purchasing a service subscription to experience the app's full functionality and scope. These service subscriptions are called Software as a Service (SaaS) offers. A license can be made available for purchase through [AppSource](https://appsource.microsoft.com/?exp=ubp8) and through the [Teams admin center](https://admin.teams.microsoft.com/). Include instructions on buying and managing licenses, as part of your appΓÇÖs admin documentation. The governance controls for admins on paid and free apps remain the same. Admins can purchase apps using a credit card, debit card, or with invoice billing. To learn more about licenses and subscriptions, see [how admins manage subscriptions for apps](/microsoftteams/purchase-third-party-apps).

+### Allow custom apps in an organization

+If an organization uses custom or line-of-business apps, then understand how admins control who can upload and use these custom apps. There are three settings that determine whether a user can upload a custom app to a team. These settings don't affect the ability to allow or block third-party apps.

+1. User app setup policy setting: As part of [app setup policies](/microsoftteams/teams-app-setup-policies), admins can control whether a user can upload custom apps to Teams.

+1. Team custom app setting: Admins and team owners can control whether a team allows custom apps to be added to it. The **Allow members to upload custom apps** option, along with user's custom app setting, determines who can add custom apps to a particular team. To learn how to configure custom app, see [Configure the team custom app setting](/microsoftteams/teams-custom-app-policies-and-settings).

+1. Org-wide custom app setting: The **Allow interaction with custom apps** org-wide custom app option applies to everyone in your organization and governs whether they can use custom apps. This setting acts as a master switch for the user and team for settings related to custom apps. To learn how to configure org-wide app setting, see [Configure the org-wide custom app setting](/microsoftteams/teams-custom-app-policies-and-settings).

+### Customize branding of apps

+Microsoft Teams admins can modify the metadata and appearance of some Teams apps to provide a personalized brand experience within their organization. Such modifications help admins adhere to their organization's requirements and branding. Customizing also enhances Teams store experience for the users, improves trust, and promotes app usage. For more information, see [how admins use app customization to update branding](/microsoftteams/customize-apps).

+To support app customization, you as an app developer can allow your app to be customized by admins. Your app in Teams app store contains the default information and metadata that you provide when you create and submit an app. Teams provides an option to customize properties of an app. You can decide what properties of your app can be customized by the admin. However, customizations made for one organization will not affect other organizations of your app. To learn more, see [how to allow app customization](concepts/design/enable-app-customization.md).

+### Documentation requirements for IT admins

+Provide admin-focused documentation in your app toolkit that is based on the above information related to the admin tasks. Your target audiences are decision makers who sponsor the app rollout and IT admins who execute the app rollout. The following information is required in your admin-focused docs:

+* A dedicated webpage of your Teams app on your official website that includes business benefits of using your app.

+* Compliance, security, privacy, and data handling information about your app. App architecture diagram and data flow diagram.

+* If your app is part of Microsoft Compliance program, highlight it and explain the benefits. Link to your appΓÇÖs page in [app security and compliance Microsoft docs](/microsoft-365-app-certification/teams/teams-apps).

+* Mention whether you have allowed app customization or not.

+* Information on governance controls available to admins. Briefly describe how admins can use policies in admin center to control access to apps.

+* Information to troubleshoot any rollout issues. The admins might face app-specific issues, provide troubleshooting tips.

+* Your contact information for app support. If admins canΓÇÖt troubleshoot app rollout or issues faced by the users, then how do they contact you. Your contact information and method to raise a support ticket mustnΓÇÖt require the user to log in.

+* List of supported languages.

+[Back to top](#understand-how-you-can-drive-app-adoption)

+## Educate users and drive adoption change management for your app

+Apps in Microsoft Teams are designed to enable collaboration between people in your organization. Enabling the right workflows and notifications for critical events in your apps in Teams enhances collaboration. The settings proactively notify the users on the tasks to be done and how to do those tasks.

+Ensure that your app is available and IT admins have made the necessary changes for the users to access. When you're ready, begin promoting your app by following the steps outlined below so the users can install and start using the app.

+* [Provide app rollout guidance](#provide-app-rollout-guidance-to-your-customers)

+* [Provide a feature guide for the users of your app](#provide-a-feature-guide-for-the-users-of-your-app)

+* [Promote awareness about your app and its use cases](#promote-awareness-about-your-app-and-its-use-cases-for-smooth-change-management)

+* [Provide training and build champions](#provide-training-and-create-champions-who-facilitate-change-management)

+### Provide app rollout guidance to your customers

+The app rollout journey for your customers requires assistance in the form of consulting, adoption planning, and troubleshooting support. Your customer engagement team can work with the customers to find early adopters to run a pilot program for your app adoption. Running a pilot program aids the customer to adopt the app faster, without roadblocks, and with higher retention numbers.

+Encourage and guide your customers to do a phased rollout with a few members. The business decision makers and IT team can identify a department or a group of volunteer employees as early adopters for a trial run before scaling up the rollout across all planned users. ItΓÇÖll help you build a stronger presence in the customerΓÇÖs organization. Also, it helps you obtain user feedback around the app adoption journey and the app features usage patterns.

+Share important and relevant information to help the users to adopt your app and admins to deploy it. Provide the following assets in your app adoption toolkit:

+* App installation and configuration guides for IT admins.

+* Feature and user guides for users.

+* User awareness assets:

+ * Customer app briefing template.

+ * User awareness campaign guide and assets such as templates for adoption email, banner, and poster.

+ * Customer webinar information for users and IT admins.

+### Provide a feature guide for the users of your app

+Provide the users with guides that help them understand how to use your app, troubleshoot issues, and reach for support. The guide can be in the form of documentation, videos, infographics, or any suitable format.

+* Provide use cases that your app helps accomplish in Teams. Consider having desktop, mobile, and browser platforms. Explain how using a Teams app helps users reduce context-switching.

+* Provide languages supported by your app.

+* Describe how users can add your app to their Teams client.

+* Describe how users can request their adminΓÇÖs approval if your app is blocked in their organization. For more information, see [manage user requests](/microsoftteams/user-requests-approve-apps).

+* Explain how the users can find support for your app. Direct the users to contact their organizationΓÇÖs IT admin or contact your support team. For more information, see [provide support contact](#provide-support-information-for-it-admins-and-users).

+### Promote awareness about your app and its use cases for smooth change management

+The adoption change management relies on awareness and training targeted at your customers. These are the marketing and communications segments of your overall app adoption strategy that make change management successful and smooth. It ensures that your users are aware of the new capabilities of the Teams app and it enables the users to derive value out of your app.

+For both initial pilots and eventual company-wide roll out, your internal communications must be a priority. These must include:

+* Internal awareness materials such as posters, email templates, digital signage, and webinar or events.

+* Campaigns: Educate users about the benefits of using the Teams app. Use the template provided by Microsoft to create campaigns to improve organization-level awareness for apps.

+* Training webinar: Conduct a webinar and place usage, training, and self-help information in a single location.

+* Events: You can also drive user awareness via physical events, kiosk, and other modes, where you distribute assets to promote awareness and usage of your app.

+* Reminders: Remind the users about the campaign before and after it happens.

+Microsoft provides few templates that you can use to speed up the adoption of your app. These templates help you quickly generate toolkit to popularize your app. See [Launch your collaborative apps](/microsoftteams/platform/concepts/deploy-and-publish/appsource/post-publish/app-growth/launch-app) for a list of resources and BOM assets that you should create for app launch. Register for [Microsoft ISV Success program](https://www.microsoft.com/isv/program-benefits) to receive guidance and templates for some of the above digital assets.

+Microsoft provides a few templates that you can use to speed up the adoption of your app. These templates help you quickly generate toolkit to popularize your app. Register for to receive guidance and templates for some of the above digital assets.

+The following considerations might help you make the awareness documents more user-friendly:

+* Include a call to action encouraging users to download and use the app.

+* Ensure that thereΓÇÖs a support path for users to contact the support team if they run into any problems.

+* Your feature and usage guide must cover the details of how users can install the app from the Teams app store from different entry points such as channels, chats, meetings, and message extensions, as well as the details of each feature's usage.

+### Provide training and create champions who facilitate change management

+Champions are essential to drive awareness, adoption, and education in your organization. A champion is motivated to help others, interested in promoting apps, and aids in increasing employee productivity. Additionally, it helps users adopt apps and best practices of using these apps.

+Champions must:

+* Be formally trained to increase their depth and breadth of knowledge.

+* Be encouraged and empowered to guide, teach, and train their peers.

+* Have consistent and positive reinforcement that affirms the impact of their efforts.

+* Have a clear plan to execute.

+Champions help:

+* Create the enthusiasm that grows adoption of improved business processes.

+* Build a circle of influence among their teams.

+* Bring to life the new ways of working across teams.

+* Identify business challenges and possible solutions.

+* Provide feedback to the project team and sponsors.

+You can use Microsoft [Champions Program Guide](https://adoption.microsoft.com/become-a-champion/) as a reference and build this program in your organization for your app. For more information, see [Create your champions program for Microsoft Teams](/microsoftteams/teams-adoption-create-champions-program).

+[Back to top](#understand-how-you-can-drive-app-adoption)

+## Provide support information for IT admins and users

+When your app is being rolled out or being used, your customers might have queries about configuration, admin settings, user flows, app features, support information, and other queries. Provide support at each stage of app lifecycle to facilitate rollout, onboard app users, build a good brand reputation, and exhibit commitment towards your app.

+Enable and train your customer-facing teams such as enablement, consulting, support, and GTM functions to answer the expected support queries. Proactively establish a support process for your app. It might involve internal enablement, socializing documentation and training videos, internally or even externally published escalation matrix, and providing support information in your communications.

+In your appΓÇÖs help documentation, consider providing some or all the following information to provide reliable support to your customers and admins:

+* Contact method with support information, for example, email, phone, or web portal.

+* Links to help documentation about rollout for admins, features for users, and troubleshooting to supporting functions.

+* Language support provided by the app in case the app is available in any non-English language.

+* Latest release date and version that imparts app freshness and hence inspires confidence.

+* Call out any app-specific configuration or permissions that might be required. Also, call out any app-specific uptime information link if your app relies on a backend infrastructure to work.

+* If you [block an app by default](concepts/design/enable-app-customization.md), provide documentation for the requirements before admins can allow the app. For example, the required configuration or subscription purchase that admins must do.

+The following table provides the support information that you already submitted to Microsoft with your app and the interface in Teams where this information is displayed. Your customers can find the above support information and self-serve themselves.

+|Input source when creating app|Parameter|Description and meaning|Visibility of the information in Teams|

+|--|--|--|--|

+|[Manifest file](resources/schem)|websiteUrl|The web page at this URL provides support information for an app.|App details page in Teams admin center displays the website URL.|

+|[Manifest file](resources/schem)|privacyUrl|The URL to the page that provides privacy information for the app.|ΓÇó Displayed in app details page in Teams admin center. <br> ΓÇó Displayed in Store listing.|

+|[Manifest file](resources/schem)|termsOfUseUrl|The URL to the page that provides the terms of use for the app.|ΓÇó Displayed in app details page in Teams admin center. <br> ΓÇó Displayed in Store listing.|

+|[Manifest file](resources/schem)|publisherDocsUrl|The URL to the page provides additional app information for the admins.|Available in Teams admin center for apps that are blocked by publisher.|

+|[Partner Center submission](/azure/marketplace/add-in-submission-guide)|NA|Support or help documentation URL.|Displayed in [AppSource](https://appsource.microsoft.com/?exp=ubp8), under **Details + support** tab.|

+[Back to top](#understand-how-you-can-drive-app-adoption)

+## Track app adoption and usage using analytics

+You build an app for millions of Teams users to achieve specific business or customer goals. For this purpose, you distribute it using the options available on the app store versus a custom app. After the app is published, you'll want to measure how your app is performing in the real-world. YouΓÇÖd also want to guide the admins to measure their org-specific app usage.

+### Track app usage in Partner Center

+You can track your appΓÇÖs overall usage in [Teams app usage report](concepts/deploy-and-publish/appsource/post-publish/overview.md) in Partner Center. You can do this after a week of publishing your app on the Teams public app store. Partner Center's usage report provides standard metrics that enable you to track user demand, user churn, and frequency of usage for your app. These reports are available at an aggregate level, such as:

+* Monthly, daily, and weekly active users.

+* Retention and intensity charts.

+* Users who have used your app more than five days in the last month.

+* Platform, operating system, and geographic split of users for your app.

+Custom app developers can find [usage analytics for their custom apps](concepts/build-and-test/analyze-your-apps-usage-in-developer-portal.md) in the Developer Portal for Teams.

+### Track detailed app usage via your in-app telemetry

+You must build your own, detailed adoption analytics and engagement methods to check tenant-wise adoption and engagement. This information helps you analyze the data against your business goals and take corrective action by fixing issues. It also helps you to intervene in the user journey or make informed decisions about feature investments, enhancements, and adoption for the app.

+Some of the interesting data points you can monitor are:

+1. Who is interested in your app?

+1. Which users and organizations are using your app?

+1. How are users engaging with your app?

+1. Which users have churned away after using your app for some time?

+To learn more about tenant-wise adoption and engagement, see [Analytics overview](concepts/design/overview-analytics.md) for tenant-wise adoption and engagement.

+### Help admins track app usage in Teams admin center for their tenant

+Teams app usage report in the admin center provides admins with information about which apps are being used and their usage numbers. Admins can gain insights on the app activity in their organization for Microsoft apps, third-party apps, and all custom apps in their tenant. You canΓÇÖt get organization-specific information from customer tenants, as an app developer. Hence, add information about Teams app usage report in [your appΓÇÖs admin docs](#help-admins-to-do-app-configuration-and-rollout-for-their-users).

+The data represented in this report provides answers to the following questions:

+* How many installed apps do the users have in your environment?

+* How many apps have at least one active user in your environment based on type (Microsoft, third-party, and custom)?

+* How many apps are being used per platform (Windows, Mac, web, or mobile)?

+* How many active users and active teams are using your app?

+For more information, see [Teams app usage report](/microsoftteams/teams-analytics-and-reports/app-usage-report).

+### Measure and share post-adoption success and engagement

+For better communication and adoption campaign, identify your metrics in advance and build into your app. It's important to plan for the kind of data, metrics, and events that you want to monitor before you start developing your Teams app. For more information, see [strategize and decide what to measure](concepts/design/strategize-measure.md).

+After successful app adoption and analysis, share your journey and your achievements in the form of a case study or an app success story. Work with [Microsoft ISV success program](https://www.microsoft.com/isv/program-benefits) to publish it with Microsoft. For information on how Microsoft can help, see [Succeed with your collaborative app](concepts/deploy-and-publish/appsource/post-publish/app-growth/succeed.md).

+[Back to top](#understand-how-you-can-drive-app-adoption)

+1. Download the plugins, extract them, and upload to their corresponding folders. For example, extract the OpenID Connect plugin (auth_oidc) to a folder called **oidc**, and upload to the **auth** folder of your Moodle document root.

+1. On the **Teams Settings** page, configure the required settings to enable the Teams app integration by clicking the **Check Moodle settings** link will update all required configurations for the Teams integration to work.

+1. Select **Upload an app** and select **Upload an app to your org's app catalog**.

+* [Integrate web apps](~/samples/integrate-web-apps-overview.md)

+* [Power Platform Connectors overview](/connectors/connectors)

+ If **Add** doesn't display in the dialog box then remove the following code from the manifest of the uploaded app package zip folder. Zip the folder again and upload it to Teams.

+ ```Json

+ "staticTabs": [],

+ "bots": [],

+ "connectors": [],

+ "composeExtensions": [],

+ ```

+After your tab is uploaded to Microsoft Teams through **ngrok** and successfully saved, you can view it in Teams until your tunnel session ends.

+* [Universal Actions for search based message extensions](../../../messaging-extensions/how-to/search-commands/universal-actions-for-search-based-message-extensions.md)]

+* [Adaptive Card Templating SDKs](/adaptive-cards/templating/sdk)

+> [!NOTE]

+> The `dialog.submit` property can only be called within a dialog.

+ You need to provision for each environment after you have successfully added the resource in your Teams app.

+ :::image type="content" source="../assets/images/teams-toolkit-v2/upload-app_1.png" alt-text="Screenshot showing the selection of upload an app highlighted in red.":::

+ :::image type="content" source="../assets/images/teams-toolkit-v2/upload-custom-app1_1.png" alt-text="Screenshot showing the selection of Upload a custom app":::

+### Use Adaptive Cards with Outgoing Webhooks

+You can send Adaptive Card, Hero card, and text messages as attachment with an Outgoing Webhook.

+Cards support formatting. For more information, see [format cards with Markdown](~/task-modules-and-cards/cards/cards-format.md?tabs=adaptive-md%2Cconnector-html#format-cards-with-markdown).

+Adaptive Card in Outgoing Webhooks supports only `openURL` card actions.

+* ***February 28, 2023***: [Facilitate adoption of your app and create awareness](promote-app-adoption.md)

+* ***January 31, 2023***: [Introducing Targeted in-meeting notification for apps in Teams.](apps-in-teams-meetings/in-meeting-notification-for-meeting.md#targeted-in-meeting-notification)

+* ***January 30, 2023***: [Enable app caching to improve subsequent launch time of the apps to the meeting side panel.](apps-in-teams-meetings/app-caching-for-your-tab-app.md)