Widget Integration Guide

This guide explains how to embed the notifito widget on your website to allow consumers to subscribe to product availability notifications.

Quick Start

Add a single script tag to your website:

html
<script src="https://cdn.notifito.com/notifito.js"

data-key="pk_live_your_publishable_key"

data-item-type="sneaker">

</script>

The widget will automatically:

  1. Fetch the item type's attribute schema
  2. Render a subscription form
  3. Handle form submission
  4. Show confirmation message

Installation

Basic Embed

html
<!DOCTYPE html>

<html>

<head>

<title>My Store</title>

</head>

<body>

<h1>Nike Air Max 90</h1>

<p>Currently out of stock</p>

<!-- notifito Widget -->

<script src="https://cdn.notifito.com/notifito.js"

data-key="pk_live_your_publishable_key"

data-item-type="sneaker">

</script>

</body>

</html>

With Specific Item

If you want to notify about a specific product variant:

html
<script src="https://cdn.notifito.com/notifito.js"

data-key="pk_live_your_publishable_key"

data-item-type="sneaker"

data-item-id="01a04f92-c68e-7333-b731-c691115aed23">

</script>


Configuration

Data Attributes

AttributeRequiredDescription
data-keyYesPublishable API key (pk_live_xxx)
data-item-typeYesItem type slug
data-item-idNoSpecific item UUID

How It Works

1. Schema Loading

When the widget loads, it fetches the attribute schema from the edge API:

GET https://edge.notifito.com/v1/widget/schema?key=pk_live_xxx&item_type=sneaker

2. Form Rendering

The widget renders form inputs based on attribute types:

Attribute TypeWidget Input
enumSelect dropdown
enum (multiple)Multi-select
integerNumber input
decimalNumber input
dateDate picker
date_rangeDate range picker
booleanCheckbox
textText input

3. Form Submission

When the consumer submits the form:

POST https://edge.notifito.com/v1/widget/subscriptions

{

"key": "pk_live_xxx",

"item_type": "sneaker",

"attributes": {"size": "42"},

"contact_value": "consumer@example.com"

}

4. Confirmation Flow

After submission:

  1. Consumer sees "Check your email" message
  2. Consumer receives confirmation email
  3. Consumer clicks confirmation link
  4. Subscription becomes active

Customization

CSS Variables

Customize the widget appearance using CSS variables:

html
<style>

notifito-widget {

/* Primary color */

--notifito-primary: #3b82f6;

--notifito-primary-hover: #2563eb;

/* Border radius */

--notifito-border-radius: 8px;

/* Font */

--notifito-font-family: 'Inter', sans-serif;

--notifito-font-size: 14px;

/* Spacing */

--notifito-spacing: 12px;

/* Background */

--notifito-background: #ffffff;

--notifito-background-hover: #f3f4f6;

/* Text */

--notifito-text: #1f2937;

--notifito-text-muted: #6b7280;

/* Border */

--notifito-border: #e5e7eb;

--notifito-border-focus: #3b82f6;

/* Error */

--notifito-error: #ef4444;

/* Success */

--notifito-success: #10b981;

}

</style>

Shadow DOM

The widget uses Shadow DOM for CSS isolation. Your website's styles won't affect the widget, and the widget's styles won't affect your website.

To style the widget from outside, use CSS variables (see above).


Attribute Types

Enum (Single Selection)

Renders as a select dropdown:

json
{

"key": "size",

"label": "Size",

"type": "enum",

"options": ["40", "41", "42", "43"],

"required": true

}

Enum (Multiple Selection)

Renders as a multi-select:

json
{

"key": "colors",

"label": "Colors",

"type": "enum",

"options": ["red", "blue", "green"],

"required": false,

"multiple": true

}

Integer / Decimal

Renders as a number input:

json
{

"key": "guests",

"label": "Number of Guests",

"type": "integer",

"required": true

}

Date

Renders as a date picker:

json
{

"key": "appointment",

"label": "Appointment Date",

"type": "date",

"required": true

}

Date Range

Renders as a date range picker:

json
{

"key": "stay",

"label": "Stay Dates",

"type": "date_range",

"required": true

}

Boolean

Renders as a checkbox:

json
{

"key": "gift_wrap",

"label": "Gift Wrap",

"type": "boolean",

"required": false

}

Text

Renders as a text input (max 500 characters):

json
{

"key": "notes",

"label": "Special Notes",

"type": "text",

"required": false

}


Browser Support

BrowserVersion
Chrome90+
Firefox88+
Safari14+
Edge90+

The widget uses Shadow DOM and Custom Elements, which are supported in all modern browsers.


Security

API Key Safety

Origin Validation

The widget validates the origin of requests against the tenant's registered domains. This prevents unauthorized websites from using your widget.

Rate Limiting

The widget API is rate-limited to prevent abuse:


Troubleshooting

Widget Not Appearing

  1. Check the script tag: Ensure data-key and data-item-type are correct
  2. Check browser console: Look for JavaScript errors
  3. Check network tab: Verify API calls are successful
  4. Check CORS: Ensure your domain is registered in the tenant settings

Form Not Submitting

  1. Check required fields: Ensure all required attributes are filled
  2. Check validation errors: Look for error messages below form fields
  3. Check network tab: Verify the API response

Styling Issues

  1. Use CSS variables: Don't try to style the widget directly
  2. Check specificity: CSS variables override internal styles
  3. Check Shadow DOM: External styles don't penetrate Shadow DOM

Examples

E-commerce Product Page

html
<!DOCTYPE html>

<html>

<head>

<title>Nike Air Max 90 - Out of Stock</title>

<style>

.product {

max-width: 600px;

margin: 0 auto;

padding: 20px;

}

.notify-form {

margin-top: 20px;

padding: 20px;

background: #f9fafb;

border-radius: 8px;

}

</style>

</head>

<body>

<div class="product">

<h1>Nike Air Max 90</h1>

<p>Currently out of stock. Sign up to be notified when available.</p>

<div class="notify-form">

<script src="https://cdn.notifito.com/notifito.js"

data-key="pk_live_your_key"

data-item-type="sneaker"

data-item-id="01a04f92-c68e-7333-b731-c691115aed23">

</script>

</div>

</div>

</body>

</html>

Hotel Booking Page

html
<!DOCTYPE html>

<html>

<head>

<title>Grand Hotel - No Availability</title>

<style>

notifito-widget {

--notifito-primary: #059669;

--notifito-border-radius: 4px;

}

</style>

</head>

<body>

<h1>Grand Hotel</h1>

<p>No rooms available for your dates. Sign up to be notified.</p>

<script src="https://cdn.notifito.com/notifito.js"

data-key="pk_live_your_key"

data-item-type="room">

</script>

</body>

</html>

Clinic Appointment Page

html
<!DOCTYPE html>

<html>

<head>

<title>City Clinic - Book Appointment</title>

</head>

<body>

<h1>City Clinic</h1>

<p>No appointments available. Sign up to be notified.</p>

<script src="https://cdn.notifito.com/notifito.js"

data-key="pk_live_your_key"

data-item-type="appointment">

</script>

</body>

</html>