diff --git a/docs/develop/event-based-activation.md b/docs/develop/event-based-activation.md index 1bfb3dad6..ff30e6cbd 100644 --- a/docs/develop/event-based-activation.md +++ b/docs/develop/event-based-activation.md @@ -1,7 +1,7 @@ --- title: Activate add-ins with events description: Learn how to develop an Office Add-in that implements event-based activation. -ms.date: 10/09/2025 +ms.date: 10/28/2025 ms.topic: concept-article ms.localizationpriority: medium --- @@ -178,7 +178,25 @@ As you develop your event-based add-in, you may need to troubleshoot issues, suc ## Deploy your add-in -Event-based add-ins are restricted to admin-managed deployments only, even if they're acquired from Microsoft Marketplace. If users acquire the add-in from Microsoft Marketplace or the in-app Office Store, they won't be able to activate the event-based function of the add-in. To learn more about listing your event-based add-in in Microsoft Marketplace, see [Microsoft Marketplace listing options for your event-based add-in](../publish/autolaunch-store-options.md). +Depending on the Office application, event-based add-ins can be deployed through one of the following options. +- **Admin-managed deployment**: Add-in is deployed through the Microsoft 365 admin center. +- **Restricted listing on Microsoft Marketplace**: Add-in is published to Microsoft Marketplace, but it doesn't appear in search results. Add-in acquisition requires a flight code URL. The add-in must still be deployed by an admin for the event-based activation feature to work. +- **Unrestricted listing on Microsoft Marketplace**: Add-in is published to Microsoft Marketplace and can be searched for by users and admins using the add-in's name or ID. Admin deployment isn't necessary for the event-based activation feature to work. The add-in must meet certain requirements for unrestricted listing. + +The following table outlines the deployment options for event-based activation by Office application. + +| Office application | Admin-managed deployment | Microsoft Marketplace | +| --- | --- | --- | +| **Excel** | Supported | Restricted listing option | +| **Outlook** | Supported | Restricted and unrestricted listing options | +| **PowerPoint** | Supported | Restricted listing option | +| **Word** | Supported | Restricted listing option | + +For instructions on how to deploy an add-in through the Microsoft 365 admin center, see [Admin-managed deployment](#admin-managed-deployment). To learn more about listing your event-based add-in in Microsoft Marketplace, see [Microsoft Marketplace listing options for your event-based add-in](../publish/autolaunch-store-options.md). + +[!INCLUDE [outlook-smart-alerts-deployment](../includes/outlook-smart-alerts-deployment.md)] + +### Admin-managed deployment Admin deployments are done by uploading the manifest to the Microsoft 365 admin center. To do so, follow these steps. @@ -187,13 +205,11 @@ Admin deployments are done by uploading the manifest to the Microsoft 365 admin ![The Integrated apps page on the Microsoft 365 admin center with the Upload custom apps action highlighted.](../images/outlook-deploy-event-based-add-ins.png) -[!INCLUDE [outlook-smart-alerts-deployment](../includes/outlook-smart-alerts-deployment.md)] - For more information about how to deploy an add-in, please refer to [Deploy and publish Office Add-ins in the Microsoft 365 admin center](/microsoft-365/admin/manage/office-addins). ### Deploy manifest updates -Because event-based add-ins are deployed by admins, any change you make to the manifest requires admin consent through the Microsoft 365 admin center. Until the admin accepts your changes, users in their organization are blocked from using the add-in. To learn more about the admin consent process, see [Admin consent for installing event-based add-ins](../publish/autolaunch-store-options.md#admin-consent-for-installing-event-based-add-ins). +If an event-based add-in was admin-deployed, any change you make to the manifest requires admin consent through the Microsoft 365 admin center. Until the admin accepts your changes, users in their organization are blocked from using the add-in. To learn more about the admin consent process, see [Admin consent for installing event-based add-ins](../publish/autolaunch-store-options.md#admin-consent-for-installing-event-based-add-ins). ## See also diff --git a/docs/outlook/mobile-event-based.md b/docs/outlook/mobile-event-based.md index 593c01f74..4a0cd8194 100644 --- a/docs/outlook/mobile-event-based.md +++ b/docs/outlook/mobile-event-based.md @@ -1,7 +1,7 @@ --- title: Implement event-based activation in Outlook mobile add-ins description: Learn how to develop an Outlook mobile add-in that implements event-based activation. -ms.date: 08/01/2025 +ms.date: 10/28/2025 ms.topic: how-to ms.localizationpriority: medium --- @@ -334,7 +334,7 @@ To learn more about APIs that are supported in Outlook on mobile devices, see [O ## Deploy to users -Event-based add-ins must be deployed by an organization's administrator. For guidance on how to deploy your add-in via the Microsoft 365 admin center, see the "Deploy your add-in" section of [Activate add-ins with events](../develop/event-based-activation.md#deploy-your-add-in). +For guidance on how to deploy your event-based add-in, see the "Deploy your add-in" section of [Activate add-ins with events](../develop/event-based-activation.md#deploy-your-add-in). ## See also diff --git a/docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md b/docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md index 19db7a08b..e7196a8d6 100644 --- a/docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md +++ b/docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md @@ -1,7 +1,7 @@ --- title: Automatically update your signature when switching between Exchange accounts description: Learn how to automatically update your signature when switching between Exchange accounts through the OnMessageFromChanged and OnAppointmentFromChanged events in your event-based activation Outlook add-in. -ms.date: 08/01/2025 +ms.date: 10/28/2025 ms.topic: how-to ms.localizationpriority: medium --- @@ -453,7 +453,7 @@ For guidance on how to troubleshoot your event-based activation add-in, see [Tro ## Deploy to users -Similar to other event-based add-ins, add-ins that use the `OnMessageFromChanged` and `OnAppointmentFromChanged` events must be deployed by an organization's administrator. For guidance on how to deploy your add-in via the Microsoft 365 admin center, see the "Deploy your add-in" section of [Activate add-ins with events](../develop/event-based-activation.md#deploy-your-add-in). +For guidance on how to deploy your event-based add-in, see the "Deploy your add-in" section of [Activate add-ins with events](../develop/event-based-activation.md#deploy-your-add-in). ## Event behavior and limitations diff --git a/docs/outlook/onmessagesend-onappointmentsend-events.md b/docs/outlook/onmessagesend-onappointmentsend-events.md index 06d5be40f..507ddacc8 100644 --- a/docs/outlook/onmessagesend-onappointmentsend-events.md +++ b/docs/outlook/onmessagesend-onappointmentsend-events.md @@ -1,7 +1,7 @@ --- title: Handle OnMessageSend and OnAppointmentSend events in your Outlook add-in with Smart Alerts description: Learn about the Smart Alerts implementation and how it handles the OnMessageSend and OnAppointmentSend events in your event-based Outlook add-in. -ms.date: 10/21/2025 +ms.date: 10/28/2025 ms.topic: concept-article ms.localizationpriority: medium --- @@ -414,7 +414,7 @@ For guidance on how to troubleshoot your Smart Alerts add-in, see [Troubleshoot ## Deploy to users -Similar to other event-based add-ins, add-ins that use the Smart Alerts feature must be deployed by an organization's administrator. For guidance on how to deploy your add-in via the Microsoft 365 admin center, see the "Deploy to users" section in [Activate add-ins with events](../develop/event-based-activation.md#deploy-your-add-in). +For guidance on how to deploy your Smart Alerts add-in, see the "Deploy to users" section in [Activate add-ins with events](../develop/event-based-activation.md#deploy-your-add-in). > [!IMPORTANT] > Add-ins that use the Smart Alerts feature can only be published to Microsoft Marketplace if the manifest's [send mode property](#available-send-mode-options) is set to the **soft block** or **prompt user** option. If an add-in's send mode property is set to **block**, it can only be deployed by an organization's admin as it will fail Microsoft Marketplace validation. To learn more about publishing your event-based add-in to Microsoft Marketplace, see [Microsoft Marketplace listing options for your event-based add-in](../publish/autolaunch-store-options.md). diff --git a/docs/publish/autolaunch-store-options.md b/docs/publish/autolaunch-store-options.md index 2a28074e1..d8af5f9bc 100644 --- a/docs/publish/autolaunch-store-options.md +++ b/docs/publish/autolaunch-store-options.md @@ -1,32 +1,49 @@ --- title: Microsoft Marketplace listing options for your event-based add-in description: Learn about the Microsoft Marketplace listing options available for your Office Add-ins that implement event-based activation. -ms.date: 08/13/2025 +ms.date: 10/28/2025 ms.localizationpriority: medium --- # Microsoft Marketplace listing options for your event-based add-in -Add-ins must be deployed by an organization's admins for end-users to access the [event-based activation](../develop/event-based-activation.md) feature. Event-based activation is restricted if the end-user acquired the add-in directly from [Microsoft Marketplace](https://marketplace.microsoft.com). For example, if the Contoso add-in includes an event-based function, the automatic invocation of the add-in only happens if the add-in was installed for the end-user by their organization's admin. Otherwise, the automatic invocation of the add-in is blocked. +When you're ready to publish your [event-based activation](../develop/event-based-activation.md) add-in to [Microsoft Marketplace](https://marketplace.microsoft.com), you can choose to list your add-in as restricted or unrestricted. This article will help you understand these listing options and choose the right approach for your add-in. -An end-user or admin can acquire add-ins through Microsoft Marketplace or the in-app Microsoft 365 and Copilot store. If your add-in's primary scenario or workflow requires event-based activation, you may want to restrict your add-in to admin deployment only. To enable that restriction, we can provide flight code URLs for add-ins in Microsoft Marketplace. Thanks to the flight codes, only end-users with these special URLs can access the listing. The following is an example URL. +[!INCLUDE [outlook-smart-alerts-deployment](../includes/outlook-smart-alerts-deployment.md)] + +## Add-in listing options + +An event-based add-in can have either a restricted or unrestricted listing in Microsoft Marketplace. The following table compares these listing options based on their prerequisites, supported Office applications, and event-based activation support. + +| Listing features | Restricted | Unrestricted | +| --- | --- | --- | +| **Event-based activation support** | Add-in must be deployed by an organization's admin for the event-based activation feature to work. | Event-based activation works immediately upon installation by either the user or admin, without requiring admin deployment. | +| **Store searchability** | The add-in isn't searchable by name or ID in Microsoft Marketplace. Users and admins must use a specific flight code URL to install the add-in. | The add-in is searchable by name or ID and it appears in the Microsoft Marketplace search results. Users and admins can install the add-in directly from the store. | +| **Prerequisites** | You must specify a flight code for your add-in when you publish it to Microsoft Marketplace. | Your add-in must be [Microsoft 365 Certified](/microsoft-365-app-certification/docs/certification) and must comply with certain usage requirements. | +| **Supported Office apps** | | | + +For more information on how to list your event-based add-in as restricted or unrestricted in Microsoft Marketplace, select the tab for the applicable listing option. + +# [Restricted listing](#tab/restricted) + +Add-ins with restricted listing in Microsoft Marketplace must be deployed by an organization's admins for users to access the event-based activation features. Event-based activation is restricted if the user acquired the add-in directly from Microsoft Marketplace. For example, if the Contoso add-in includes an event-based function, the automatic invocation of the add-in only happens if the add-in was installed for the user by their organization's admin. Otherwise, the automatic invocation of the add-in is blocked. + +To enable that restriction, we can provide flight code URLs for add-ins in Microsoft Marketplace. Thanks to the flight codes, only users with these special URLs can access the listing. The following is an example URL. `https://marketplace.microsoft.com/product/office/WA200002862?flightCodes=EventBasedTest1` -Users and admins can't explicitly search for an add-in by its name in Microsoft Marketplace or the in-app Microsoft 365 and Copilot store when a flight code is enabled for it. As the add-in creator, you can privately share these flight codes with organization admins for add-in deployment. +When a flight code is enabled for an add-in, the add-in isn't searchable by name or ID in Microsoft Marketplace or the in-app Microsoft 365 and Copilot store. As the add-in creator, you can privately share these flight codes with organization admins for add-in deployment. > [!NOTE] -> While end-users can install the add-in using a flight code, the add-in won't include event-based activation. +> While users can install an event-based add-in using a flight code, the add-in won't include event-based activation. However, users can use other components of the add-in, such as a task pane or function command. -[!INCLUDE [outlook-smart-alerts-deployment](../includes/outlook-smart-alerts-deployment.md)] - -## Specify a flight code +### Specify a flight code To specify the flight code for your add-in, share the code in the **Notes for certification** when you publish your add-in. **Important**: Flight codes are case-sensitive. ![A sample request for flight code in Notes for certification screen during publishing process.](../images/outlook-publish-notes-for-certification.png) -## Deploy add-in with flight code +### Deploy add-in with flight code After the flight codes are set, you'll receive the URL from the app certification team. You can then share the URL with admins privately. @@ -35,26 +52,36 @@ After the flight codes are set, you'll receive the URL from the app certificatio To deploy the add-in, the admin can use the following steps. -- Sign in to admin.microsoft.com or Microsoft Marketplace.com with your Microsoft 365 admin account. If the add-in has single sign-on (SSO) enabled, global admin credentials are needed. -- Open the flight code URL into a web browser. -- On the add-in listing page, select **Get it now**. You should be redirected to the integrated app portal. +1. Sign in to [https://admin.microsoft.com](https://admin.microsoft.com) or [https://marketplace.microsoft.com](https://marketplace.microsoft.com) with your Microsoft 365 admin account. If the add-in has single sign-on (SSO) enabled, global admin credentials are needed. +1. Open the flight code URL in a web browser. +1. On the add-in listing page, select **Get it now**. You should be redirected to the [integrated apps portal](/microsoft-365/admin/manage/test-and-deploy-microsoft-365-apps). + +# [Unrestricted listing](#tab/unrestricted) + +If an event-based add-in for Outlook has an unrestricted listing in Microsoft Marketplace, users and admins can use the event-based activation feature immediately after installing the add-in. An unrestricted add-in listing doesn't require admin deployment. -## Unrestricted Microsoft Marketplace listing +To qualify for unrestricted listing: -If your add-in doesn't use event-based activation for critical scenarios (that is, your add-in works well without automatic invocation), consider listing your add-in in Microsoft Marketplace without any special flight codes. If an end-user gets your add-in from Microsoft Marketplace, automatic activation won't happen for the user. However, they can use other components of your add-in such as a task pane or function command. +1. Your add-in must be Microsoft 365 Certified. For guidance on the certification process, see [Microsoft 365 Certification framework overview](/microsoft-365-app-certification/docs/certification). +1. Once Microsoft 365 Certification is awarded to your add-in, complete the [form](https://aka.ms/AutoLaunchForEndUser) to request for unrestricted listing. You must provide the following information. + - The certification status of your add-in. + - A link to your add-in's listing in Microsoft Marketplace. + - Your contact information. -> [!IMPORTANT] -> This is a temporary restriction. In future, we plan to enable event-based add-in activation for end-users who directly acquire your add-in. +After submitting the form, your add-in will undergo further review for usage and market trend considerations. Upon approval, your add-in will have unrestricted listing in Microsoft Marketplace and users can immediately access event-based activation features upon installation. + +--- ## Update existing add-ins to include event-based activation You can update your existing add-in to include event-based activation then resubmit it for validation and decide if you want a restricted or unrestricted Microsoft Marketplace listing. -After the updated add-in is approved, organization admins who have previously deployed the add-in will receive an update message in the **Integrated apps** section of the admin center. The message advises the admin about the event-based activation changes. After the admin accepts the changes, the update will be deployed to end-users. To learn more about the admin consent process, see [Admin consent for installing event-based add-ins](#admin-consent-for-installing-event-based-add-ins). +After the updated add-in is approved, organization admins who previously deployed the add-in will receive an update message in the **Integrated apps** section of the admin center. The message advises the admin about the event-based activation changes. After the admin accepts the changes, the update will be deployed to users. To learn more about the admin consent process, see [Admin consent for installing event-based add-ins](#admin-consent-for-installing-event-based-add-ins). ![App update notifications on the "Integrated apps" screen.](../images/outlook-deploy-update-notification.png) -For end-users who installed the add-in on their own, the event-based activation feature won't work even after the add-in has been updated. +> [!NOTE] +> For users who installed an add-in listed as restricted, the event-based activation feature won't work even after the add-in has been updated. ## Admin consent for installing event-based add-ins