npm package: @storedotapp/pwa-install-dialog
Description: Web component for PWA managing installation modal with store.app metadata included.
Latest version: 1.1.2

# pwa-install-dialog

Web component for PWA managing installation modal with store.app metadata included.

## Features

- Show/hide modal with installation instructions according to OS/Browser
- Includes Rating and Verified status from store.app with link to the listing
- Light/Dark theme
- Responsive: center modal on desktop, bottom drawer on mobile
- `[>=1.1.0]` Tracking events
- `[>=1.1.0]` Auto-open modal when coming from store.app listing (can be disabled)

## Requirements

Your PWA needs to be listed on https://store.app.
List your app for free:

1. Sign up on [store.app](https://store.app)
2. Request a Dev Account
3. Claim your App
4. Publish your listing

### How to use

1. Install

```shell
npm i @storedotapp/pwa-install-dialog
```

2. Import in your `main.ts` or `main.js` or any top level file

```js
import "@storedotapp/pwa-install-dialog";
```

3. Use the web component in your html or template file. See attribute list below for more details.

```html
<!-- Examples-->
<pwa-install-dialog id="install-dialog" app="fitness-app" theme="dark"></pwa-install-dialog>
<pwa-install-dialog id="install-dialog" app="fitness-app" open></pwa-install-dialog>
```

4. Define your opening trigger on the event you want (usually a click on an <Install> button).
   Call the `show()` method on the component

```html
<!-- Example-->
<button onclick="document.getElementById('install-dialog').show()">Install</button>
```

### Attributes

| Attribute | Required | Type     | Default                       | Description                                                                                                  |
|:----------|:--------:|----------|:------------------------------|--------------------------------------------------------------------------------------------------------------|
| `app`     | Required | `string` | n/a                           | Your app id from your listing page (eg. `fitness-app` if the listing page is `https://store.app/fitness-app` |
| `theme`   | Optional | `string` | User's `prefers-color-scheme` | Color theme for the modal. Supports `light` and `dark`                                                       |
| `open`    | Optional | `bool`   | n/a                           | Whether the modal is visible or not. Can be omitted and controlled via `show()`/`hide()` methods             |

### Methods

| Method   | Description                                                                                                               |
|:---------|---------------------------------------------------------------------------------------------------------------------------|
| `show()` | Set `open` to `true`                                                                                                      |
| `hide()` | Set `open` to `false`. This is taken care of automatically when the backdrop is clicked but you can add your own triggers |

### Events

#### Ready (from `1.1.1`)

The component dispatches a `ready` event when it finishes initializing. You can wait for this event to trigger before making the Install button available to your user.

```js
document.getElementById("pwa-install").addEventListener("ready", () => {
  document.getElementById("dialog-trigger").style.visibility = "visible"
})
```

#### Interactions (from `1.1.0`)

The component dispatches `interact` events when the user interacts with the dialog, allowing you to react to or track behaviors on your app.

The event `detail` always has an `interaction` value, plus some optional payload depending on the interaction.

```js
document.getElementById("pwa-install").addEventListener("interact", (e) => {
  console.log(e.detail) // { interaction: 'first-open', mode: 'support' }
})
```

| Interaction          | Description                                                                  | Additional Payload    | Details                                                                                         |
|:---------------------|:-----------------------------------------------------------------------------|-----------------------|:------------------------------------------------------------------------------------------------|
| `first-open`         | The user opened the install modal for the first time since last page refresh | `mode`: `<see_below>` | Whether or not the device supports native prompt; if not, what custom instructions are provided |
| `open-listing`       | The user opened the app listing from the dialog                              |                       |                                                                                                 |
| `click-instructions` | The user clicked the manual install instructions section (no effect)         |                       |                                                                                                 |
| `install`            | The user triggered the native install prompt                                 |                       |                                                                                                 |

Supported values for `mode` currently are:

- `native-prompt`
- `not-supported`
- `ios-safari`
- `ios-chrome`
- `ios-edge`
- `ios-firefox`
- `android-chrome`
- `android-edge`
- `android-firefox`
- `android-opera`
- `android-samsung-browser`
- `macos-safari`

## Screenshots

#### Native Prompt in Dark Mode

<img src="https://static.store.app/docs/install-modal/dark-native-prompt.png" alt="Native Prompt in Dark Mode" width="500"/>

#### iOS/Safari in Light Mode

<img src="https://static.store.app/docs/install-modal/light-ios-safari.png" alt="iOS-Safari Light Mode" width="500"/>

#### Opera/Android in Dark Mode

<img src="https://static.store.app/docs/install-modal/dark-android-opera.png" alt="Opera-Android in Dark Mode" width="500"/>