> For the complete documentation index, see [llms.txt](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/notify-me-and-coming-soon/widget-installation-and-configuration.md).

# Widget installation and configuration

## Prerequisite

For Shopify, first install and configure the TWC app proxy using the [Proxy App Install Guide](/the-wishlist-documentation-docs/developer-reference/proxy-app-install-guide.md). Verify that the token endpoint works both while logged out and while logged in. Then configure the widget with proxy authentication. Customer login is not a prerequisite for Notify Me or Coming Soon registration.

## Installation

The `notify-me-wl` JavaScript package provides the customer-facing experience for both **Notify Me** and **Coming Soon / Register Interest**.

{% stepper %}
{% step %}

## Install the widget

Load the current widget bundle from npm via jsDelivr:

```html
<script src="https://cdn.jsdelivr.net/npm/notify-me-wl/build/notify-me-wl.min.js"></script>
```

{% hint style="info" %}
**Version 2 and later**

The distributed bundle is located at `build/notify-me-wl.min.js`. Earlier implementations that referenced `index.js` should be updated to the current path.
{% endhint %}
{% endstep %}

{% step %}

## Provide product context

The widget expects the current product to be available as `window.currentProduct`, including the product variants that can be selected by the customer.

A Shopify Liquid implementation can use the following pattern:

```html
<script>
  window.currentProduct = {
    id: {{ product.id | json }},
    title: {{ product.title | json }},
    variants: [
      {% for variant in product.variants %}
        {
          id: {{ variant.id | json }},
          title: {{ variant.title | json }}
        }{% unless forloop.last %},{% endunless %}
      {% endfor %}
    ]
  };
</script>
```

The widget uses the variant ID as the `variantRef` submitted to TWC.
{% endstep %}

{% step %}

## Add the widget container and trigger

The page requires:

* a container with the ID `notification-widget`; and
* a trigger element with the ID `popup-open`.

### Notify Me example

```html
<div id="notification-widget"></div>

<button
  id="popup-open"
  data-type="notify-me"
  data-auth="proxy"
  data-proxy-app="twc-sdk"
  data-tenant="YOUR_TWC_TENANT"
  data-country-code="{{ localization.country.iso_code }}"
  data-fields='["email", "mobile", "firstName", "lastName"]'>
  Notify Me
</button>
```

### Coming Soon example

```html
<div id="notification-widget"></div>

<button
  id="popup-open"
  data-type="coming-soon"
  data-auth="proxy"
  data-proxy-app="twc-sdk"
  data-tenant="YOUR_TWC_TENANT"
  data-country-code="{{ localization.country.iso_code }}"
  data-fields='["email", "mobile", "firstName", "lastName"]'>
  Register Interest
</button>
```

The widget initialises when the page DOM is ready.
{% endstep %}
{% endstepper %}

## Configuration reference

Configuration is supplied using `data-*` attributes on the `#popup-open` element.

<table><thead><tr><th width="223.140625">Attribute</th><th>Required</th><th width="147.16796875">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>data-type</code></td><td>Yes</td><td>—</td><td><code>notify-me</code> or <code>coming-soon</code>. Determines the customer-facing copy and Customer Interest API flag.</td></tr><tr><td><code>data-fields</code></td><td>No</td><td><code>["email"]</code></td><td>JSON array of customer fields to display. Supported values are <code>email</code>, <code>mobile</code>, <code>firstName</code>, <code>lastName</code>, <code>countryCode</code>, <code>provinceCode</code>.</td></tr><tr><td><code>data-display</code></td><td>No</td><td><code>modal</code></td><td><code>modal</code> or <code>panel</code>. Controls how the widget is presented.</td></tr><tr><td><code>data-auth</code></td><td>No</td><td><code>token</code></td><td>Supported values are <code>proxy</code> and <code>token</code>. For Shopify, explicitly use <code>proxy</code> after installing and configuring the TWC app proxy. The authentication method does not determine whether the shopper must log in.  <a href="broken://pages/9b99fb88bc804e74c65d77d79e367b649984aaf1">Widget Authentication</a>.</td></tr><tr><td><code>data-tenant</code></td><td>No*</td><td>configured tenant</td><td>Production implementations must use the tenant assigned by TWC.  Do not rely on a package environment default.</td></tr><tr><td><code>data-proxy-app</code></td><td>No</td><td><code>twc-sdk</code></td><td>Shopify App Proxy path used when <code>data-auth="proxy"</code>.</td></tr><tr><td><code>data-market-id</code></td><td>No</td><td>detected where possible</td><td>Shopify Market ID. Numeric IDs and <code>gid://shopify/Market/...</code> values are accepted.  Recommended for Shopify Markets implementations.</td></tr><tr><td><code>data-market-handle</code></td><td>No</td><td>—</td><td>Shopify Market handle, for example <code>au</code>.  Recommended for Shopify Markets implementations.</td></tr><tr><td><code>data-country-code</code></td><td>Conditional</td><td>detected where possible</td><td>Two-letter ISO country code, for example <code>AU</code>.  Required for Shopify Markets implementations.</td></tr><tr><td><code>data-recommendations</code></td><td>No</td><td>enabled</td><td>Set to <code>false</code> to disable Shop Similar Styles recommendations.</td></tr><tr><td><code>data-recommendations-count</code></td><td>No</td><td><code>8</code></td><td>Number of recommendation cards requested. Invalid or non-positive values fall back to 8.</td></tr><tr><td><code>data-currency</code></td><td>No</td><td>Shopify active currency</td><td>Fallback ISO currency code used for recommendation prices when Shopify currency context is unavailable.</td></tr><tr><td><code>data-customer-email</code></td><td>No</td><td>—</td><td>Testing/development override for recommendation lookup. Production implementations should normally derive the customer email from Shopify customer context or form submission.</td></tr></tbody></table>

\* The package may contain an environment/default tenant configuration, but production implementations should explicitly use the tenant supplied by TWC rather than rely on package defaults.

## Customer fields

The `data-fields` attribute controls which customer fields are shown in the form. Only email is required.  Mobile is required if customer wishes to be notified by SMS.  Country\_code is required if using Shopify Markets.  The other fields are optional.

```html
<button
  id="popup-open"
  data-type="notify-me"
  data-fields='["email", "mobile", "firstName", "lastName"]'>
  Notify Me
</button>
```

Supported values are:

| Field          | Purpose                                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `email`        | Customer email address. Required by the TWC Customer Interest API                                              |
| `mobile`       | Customer mobile number. Required when SMS notification is selected.                                            |
| `firstName`    | Customer first name.  Optional.                                                                                |
| `lastName`     | Customer last name. Optional.                                                                                  |
| `countryCode`  | Country selector/context for market-aware implementations.  Required for Shopify Market aware implementations. |
| `provinceCode` | Province/state selector/context where applicable. Recommended for Shopify Market aware implementations.        |

If `data-fields` is omitted, the widget defaults to email.

## Variant / size selection

A **Size** selector is included by the widget and is populated from `window.currentProduct.variants`.

The customer must select a variant before submitting. The selected variant ID is submitted to TWC as `variantRef`.

For products where the variant title represents something other than size, the same underlying selector still uses the configured Shopify/product variant title.

## Marketing preferences

The standard widget includes optional preferences for:

* **Email me store updates**; and
* **Text me store updates**.

These are separate from registering Notify Me or Coming Soon interest.

The email preference is submitted as `subscribe`. The SMS preference is submitted as `subscribeSms`; when SMS subscription is selected, a mobile number must also be supplied.

## Display modes

{% tabs %}
{% tab title="Modal" %}

```html
<button id="popup-open" data-type="notify-me" data-display="modal">
  Notify Me
</button>
```

The modal is centred over the page and is the default presentation.
{% endtab %}

{% tab title="Panel" %}

```html
<button id="popup-open" data-type="notify-me" data-display="panel">
  Notify Me
</button>
```

The panel is docked to the right of the viewport on desktop and uses the available viewport on smaller screens.
{% endtab %}
{% endtabs %}

Both display modes use the same form, validation and submission behaviour. The widget can be closed using the close control, backdrop or Escape key, and page scrolling is managed while the widget is open.

## Submission behaviour

For a Notify Me submission, the widget sends `notifyMe: true`.

For a Coming Soon submission, the widget sends `comingSoon: true`.

The widget also sends the selected variant, email and any configured customer, consent and market information.

Successful and failed submissions are displayed inline to the customer.

## Next steps

* For authentication options, see [Widget Authentication](broken://pages/9b99fb88bc804e74c65d77d79e367b649984aaf1).
* For Shopify Markets, see [Shopify Markets Support](broken://pages/2200f96f5cca5bff466ba75947d76efb24622607).
* For Shop Similar Styles, see [Product Recommendations & Integrations](broken://pages/ea38528eb92781511938bb60da9abf7467ca0596).
* For a custom frontend, see [API / Custom Implementations](broken://pages/6ec1abf3a2937bf70afe114a479318034df5f863).

Package reference: [notify-me-wl on npm](https://www.npmjs.com/package/notify-me-wl)