robssen81 / app-store-badge

Web component that renders the "Get this app on Microsoft Store" badge

App Store Badge

This repository contains the source code for web component that displays the "Get this app on the Microsoft Store" badge.

Usage

Generate your own app badge using https://apps.microsoft.com/store/app-badge/

Alternately, add the following code in your HTML where you want the button to appear:

<script type="module" src="https://get.microsoft.com/badge/ms-store-badge.bundled.js"></script>
<ms-store-badge productid="9wzdncrfhvjl"></ms-store-badge>

The component has some additional configuration options:

Option	Type	Default value	Description
productid	string	undefined	Your app ID in the Microsoft Store. You can find this value by navigating to your app in the Microsoft Store for Web and grabbing the last part of the URL. The Discord app, for example, is at https://apps.microsoft.com/store/detail/discord/XPDC2RH70K22MN, so its product ID is XPDC2RH70K22MN
cid	string	undefined	Your app campaign code for analytics purposes. If the user clicks the app badge, this value will be passed to analytics and will be available to you in your Microsoft Partner Center reports.
window-mode	"popup" or "full"	"popup"	Configure the badge to open your app in popup store mode or full store mode. In popup mode, users who click your app badge will see the popup store: In full mode, users who click your app badge will see full store app: )
theme	"dark" or "light" or "auto"	"dark"	Configure the badge theme dark mode, light mode, or auto mode. Auto mode detects the user's dark mode preference and sets the badge theme accordingly. dark should be used on sites with light backgrounds: light should be use on sites with dark backgrounds:
animation	"on" or "off"	"off"	When on, the badge will use an animation and shadow on hover. Alternately, you may build and apply your own animations by adding CSS to the img part. See styling the badge for more information.
language	string	''	The language to display the app badge. If left empty, the language will be detected from the user's browser navigator.userAgent.language. Sample of specifying a different language: See supported languages Afrikaans: "af" Arabic: "ar" Belarusian: "be" Bulgarian: "bg" Bengali: "bn" Bosnian: "bs" Catalan: "ca" Chinese (Simplified): "zh-cn" Chinese (Traditional): "zh-tw" Czech: "cs" Danish: "da" Dutch: "nl" German: "de" Greek: "el" English: "en" Spanish: "es" Estonian: "et" Persian: "fa" Finnish: "fi" Filipino: "fil" French: "fr" Galician: "gl" Hebrew: "he" Hindi: "hi" Croatian: "hr" Hungarian: "hu" Indonesian: "id" Icelandic: "is" Italian: "it" Japanese: "ja" Georgian: "ka" Kazakh: "kk" Korean: "ko" Lithuanian: "lt" Latvian: "lv" Malay: "ms" Norwegian: "nb" Polish: "pl" Portuguese (Brazil): "pt-br" Portuguese (Portugal): "pt-pt" Romanian: "ro" Russian: "ru" Slovak: "sk" Slovenian: "sl" Serbian: "sr" Swedish: "sv" Swahili: "sw" Thai: "th" Turkish: "tr" Ukrainian: "uk" Vietnamese: "vi" Welsh: "cy"

Example using all the available options:

<script type="module" src="https://get.microsoft.com/badge/ms-store-badge.bundled.js"></script>
<ms-store-badge productid="9wzdncrfhvjl" language="he" cid="abc123" theme="light"></ms-store-badge>

Styling the badge

To style the app badge web component, use CSS parts to style the badge image. Specifically, the app badge web component exposes the badge image as img part:

/* Customize the badge's appearance */
ms-store-badge::part(img) {
    max-height: 52px;
}

Why a web component?

Most app store badges are a simple image with a link to the web store. Why is this a web component?

In short, for better localization and better user experience.

• Localization: the web component supports automatic detection of the user's locale, showing a localized button to the user based on the user's browser locale.
• Fewer security prompts: if the user is on Edge on Windows, no browser security prompt ("this site is trying to launch Microsoft Store") is shown.
• popup mode centering: Where supported, when a user who clicks your app badge on Windows, instead of launching the full Store app, they'll get a mini popup dialog (mini product description page, or miniPDP) centered within the parent page, allowing for inline install. The user doesn't lose context. Here's what it looks like:
  
• Better behavior on other OSes: If the user is on MacOS or other non-Windows OS and they click your app badge, instead of trying (and failing) to launch the Microsoft Store app or MiniPDP, it instead launches the OS's native share dialog, allowing the user to share the link to your app.
• Automatic theme support: You can configure your app badge to use automatic theme detection. When theme="auto", the app badge will be themed based on whether the user has dark mode enabled.

HTML-only

While the app badge script is small (about 9k), there are contexts where a script doesn't make sense: Github markdown pages, static sites, or other contexts without Javascript available. For such contexts, you can use a simple image with link:

<!-- display an HTML-only app badge. Useful when you can't execute JS, such as in Github markdown pages -->
<a href="ms-windows-store://pdp/?ProductId=XPDC2RH70K22MN&mode=mini">
   <img src="https://get.microsoft.com/images/en-us%20dark.svg" alt="Download Discord" />
</a>

Be mindful that the HTML-only version of the badge loses some functionality of the full badge. For example, automatic theme detection, OS-specific behavior (e.g. launch the Store on Windows, or open the apps's web Product Description Page on non-Windows OS), localization, and fewer user prompts for Edge users are not available in the HTML-only version of the badge.

Running the code

To run code locally, npm run dev, then launch http://localhost:8000/create-your-own.html

To build for production, npm run build. This will create the production artifacts in /dist.

Deploying

Github actions are set to deploy successful builds of main to the app badge CDN.