Sample code for the Web Widget that facilitate Office add-in distribution.

Introduction

This project simplifies the process of distributing Office add-ins by enabling direct installation from a website. We provide a convenient install link and a web widget to enhance user experience and streamline the add-in installation process for better acquisition conversion.

Getting Started

The webpage will show the add-in name, a few details about the add-in functionality for highlight, a dropdown button to install and use the add-in and an image to demo the add-in. This is what the UI looks like.

[!IMPORTANT]
To use this sample code, please follow the Partner-Led Marketing Guidelines.

[!TIP] If you want a simple trial on the dropdown button link that enables user to install and use add-in, please clone https://github.com/OfficeDev/OfficeJSAddinWidget/blob/main/LinkGenerator.html to your local, open with browser app and input the information as the UI shows.

Usage for how to generate the install link for Office on Windows or Mac

To better distribute your add-in, you can create an install link to provide your users with the "click and run" experience from your website or anywhere else after you submit your add-in to AppSource. The link will seamlessly bring users to their Web sersion WXP with your add-in automatically launched, so you can directly guide users to try your add-in instead of letting them find it themselves in the Add-in Store.

To create the link, you can reference the link below and configure the parameters in the query string.
{{appName}}:https://api.addins.store.office.com/addinstemplate/{{language}}/{{correlation}}/{{addinId}}/none/{{addinName}}.{{fileFormat}}?omexsrctype=1

1. appName
   This parameter controls which Office application would be opened when users click the link.
   · For Word: ms-word
   · For Excel: ms-excel
   · For PowerPoint: ms-powerpoint
   This approach currently supports WXP on Windows and Mac only.
   

[!Note] This parameter is part of the deeplink.

2. language
   This is the language of Add-in instructions after opened on Word/Excel/PowerPoint on Windows or Mac.
   Please set as needed. For example: "de-DE", "fr-FR", "it-IT", "ja-JP", "zh-CN".
   

3. correlation
   A GUID for diagnostic purpose. For example, "7bf846ec-905a-5edd-b162-83498f9a8674".
   We strongly recommend you to runtime generate it and make it different per click.
   

4. addInId
   The ID of your add-in published in AppSource
   

[!NOTE] This parameter is case sensitive. Please use upper case in order to succeed.

5. addInName
   The full name of your add-in in percent encoding format. For example, "space" should be %20, and "-" should be %2D...etc.
   

6. fileFormat
   · For Word: docx
   · For Excel: xlsx
   · For PowerPoint: pptx
   

For example, if we want to create an install link so that users can click and launch Script Lab on Word on Windows, this link should be: ms-word:https://api.addins.store.office.com/addinstemplate/en-US/228a829b-69d7-45f4-a338-c6aba330ec7e/WA104380862/none/Script-Lab--a-Microsoft-Garage-project.docx?omexsrctype=1.

Usage for how to generate the install link for Office on the Web

To better distribute your add-in, you can create an install link to provide your users with the "click and run" experience from your website or anywhere else after you submit your add-in to AppSource. The link will seamlessly bring users to their Web sersion WXP with your add-in automatically launched, so you can directly guide users to try your add-in instead of letting them find it themselves in the Add-in Store.

To create the link, you can reference the link below and configure the 3 parameters in the query string.
https://go.microsoft.com/fwlink/?linkid={{linkId}}&templateid={{addInId}}&templatetitle={{addInName}}

1. linkId
   This prarmeter controls which web endpoint would be opened when users click the link.
   · For Word Web: 2261098
   · For Excel Web: 2261819
   · For PowerPoint Web: 2261820
   This approach currently supports WXP Web only.
   

2. addInId
   The ID of your add-in published in AppSource
   

3. addInName
   The full name of your add-in in percent encoding format. For example, "space" should be %20, and "-" should be %2D...etc.
   

For example, for the add-in Script Lab, it supports all Word, Excel, PowerPoint. If we want to create an install link so that users can click and launch Script Lab, this link should be: https://go.microsoft.com/fwlink/?linkid=2261819&templateid=WA104380862&templatetitle=Script%20Lab,%20a%20Microsoft%20Garage%20project Where 2261819 is the Excel Web launch link ID, WA104380862 is Script Lab's add-in id, and "Script%20Lab,%20a%20Microsoft%20Garage%20project" is the full name in percent encoding format.

Usage for the web widget

1. Download the WebWidget/Example-ScriptLab.html file and go to Githubissues.

2. Githubissues is a development platform for aggregating issues.