Widget Integration Guide

Version: 1.0.0

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:

<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

<!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:

<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

Attribute	Required	Description
`data-key`	Yes	Publishable API key (`pk_live_xxx`)
`data-item-type`	Yes	Item type slug
`data-item-id`	No	Specific item UUID

Example

<script src="https://cdn.notifito.com/notifito.js"
        data-key="pk_live_ADbaCjvo5TT1x8104zHXKSHr"
        data-item-type="sneaker"
        data-item-id="01a04f92-c68e-7333-b731-c691115aed23">
</script>

How It Works

1. Schema Loading

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

// Widget automatically calls:
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 Type	Widget Input
`enum`	Select dropdown
`enum` (multiple)	Multi-select
`integer`	Number input
`decimal`	Number input
`date`	Date picker
`date_range`	Date range picker
`boolean`	Checkbox
`text`	Text input

3. Form Submission

When the consumer submits the form:

// Widget automatically calls:
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:

<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>

<script src="https://cdn.notifito.com/notifito.js"
        data-key="pk_live_your_publishable_key"
        data-item-type="sneaker">
</script>

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:

{
    "key": "size",
    "label": "Size",
    "type": "enum",
    "options": ["40", "41", "42", "43"],
    "required": true
}

Enum (Multiple Selection)

Renders as a multi-select:

{
    "key": "colors",
    "label": "Colors",
    "type": "enum",
    "options": ["red", "blue", "green"],
    "required": false,
    "multiple": true
}

Integer / Decimal

Renders as a number input:

{
    "key": "guests",
    "label": "Number of Guests",
    "type": "integer",
    "required": true
}

Date

Renders as a date picker:

{
    "key": "appointment",
    "label": "Appointment Date",
    "type": "date",
    "required": true
}

Date Range

Renders as a date range picker:

{
    "key": "stay",
    "label": "Stay Dates",
    "type": "date_range",
    "required": true
}

Boolean

Renders as a checkbox:

{
    "key": "gift_wrap",
    "label": "Gift Wrap",
    "type": "boolean",
    "required": false
}

Text

Renders as a text input (max 500 characters):

{
    "key": "notes",
    "label": "Special Notes",
    "type": "text",
    "required": false
}

Browser Support

The widget supports all modern browsers:

Browser	Version
Chrome	90+
Firefox	88+
Safari	14+
Edge	90+

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

Security

API Key Safety

Publishable keys (pk_) are safe to expose in page source
Secret keys (sk_) must never be exposed to browsers
The widget only uses publishable keys

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: - 60 requests per minute for schema fetches - 30 requests per minute for subscription submissions

Troubleshooting

Widget Not Appearing

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

Form Not Submitting

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

Styling Issues

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

Examples

E-commerce Product Page

<!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_ADbaCjvo5TT1x8104zHXKSHr"
                    data-item-type="sneaker"
                    data-item-id="01a04f92-c68e-7333-b731-c691115aed23">
            </script>
        </div>
    </div>
</body>
</html>

Hotel Booking Page

<!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_tA16CQGi5GcxRB8tjWwa9K4u"
            data-item-type="room">
    </script>
</body>
</html>

Clinic Appointment Page

<!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_NmRY71VOkBOZ9RPQ8idJQmt6"
            data-item-type="appointment">
    </script>
</body>
</html>