> For the complete documentation index, see [llms.txt](https://staysignal.gitbook.io/staysignal-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://staysignal.gitbook.io/staysignal-docs/integration-guides/simple-html-js-integration.md).

# Simple HTML/JS integration

### Simple HTML/JavaScript Integration

Follow these steps to integrate the Staysignal widget into your website:

#### 1. Include the Script

Add the Staysignal script to your website, replacing `YOUR_SITE_ID_HERE` with your actual Site ID:

```html
<script src="https://app.staysignal.com/api/widget/script/YOUR_SITE_ID_HERE"></script>
```

**Activate your 14-day free trial to get Site ID**

Please [activate your subscription](https://app.staysignal.com/dashboard/settings/subscription) to get your unique Site ID and fully integrate the widget. This code example uses a placeholder.

#### 2. Initialize the Widget

Initialize the widget with callback handlers. The Site ID is automatically included from the script URL.

```javascript
<script>
StaySignal.init({
  // site_id is embedded in the script loaded via /api/widget/script/[siteId]
  onComplete: (payload) => {
    console.log('Widget flow complete:', payload);
    if (payload.resolution === 'cancelled') {
      // Handle successful cancellation
    } else {
      // Handle when user decides to stay
    }
  },
  onError: (error) => {
    console.error('Widget error:', error);
  }
});
</script>
```

#### 3. Add Cancel Buttons

You have two options to add cancel buttons to your site, and you can also opt out of automatic cancellation if you have a custom process:

**Opt-Out of Automatic Cancellation**

**To prevent Staysignal from cancelling the subscription automatically**, use either of these methods:

* **Config option:** Pass `cancelOptOut: true` to the widget init config.
* **Button attribute:** Add `data-ss-cancel-optout="true"` to your cancel button.

**Precedence:** If either method is set, cancellation is skipped and a message is logged to the console.

**Option 1: Class-based Approach (Recommended)**

Add the `staysignal-cancel` class and `data-subscription_id` attribute to any button. To opt out, add `data-ss-cancel-optout="true"`:

```html
<button class="staysignal-cancel" data-subscription_id="sub_123456" data-ss-cancel-optout="true">
    Cancel Subscription
</button>
```

[Need help finding the subscription ID?](https://app.gitbook.com/o/L1J4IXndMOL7SI7HjRkS/s/vYa98TfDh2GiMvr5EyYo/~/changes/10/basics/integrations/finding-stripe-subscription-ids)

**Option 2: JavaScript Approach**

Manually trigger the widget using JavaScript. To opt out globally, pass `cancelOptOut: true` to the config:

```javascript
<script>
StaySignal.init({
    siteId: 'YOUR_SITE_ID',
    cancelOptOut: true // Opt out of automatic cancellation
});
</script>
```

#### Complete Example

```html
<!DOCTYPE html>
<html>
<head>
    <title>StaySignal Integration Example</title>
</head>
<body>
    {/* Example Button: */} 
    <button class="staysignal-cancel" data-subscription_id="sub_123456">Cancel Subscription</button>

    <!-- Include the StaySignal Widget -->
    <script>
        const script = document.createElement('script');
        script.src = 'https://app.staysignal.com/api/widget/script/YOUR_SITE_ID_HERE';
        script.onload = function() {
            StaySignal.init({
                // site_id is embedded in the script loaded via /api/widget/script/[siteId]
                onComplete: (payload) => {
                    console.log('Widget flow complete:', payload);
                    if (payload.resolution === 'cancelled') {
                        alert('Subscription cancelled successfully.');
                    } else {
                        alert('Great! You decided to stay with us.');
                    }
                },
                onError: (error) => {
                    console.error('Widget error:', error);
                }
            }); // Escape backticks in the initLogic string itself
            StaySignal.onReady(() => {
                console.log('StaySignal Ready!');
                // Optional: Add JS click handlers if not using class-based approach
            });
        };
        document.body.appendChild(script);
    </script>
</body>
</html>
```

### Testing

To test your integration:

1. Ensure the widget script loads successfully
2. Check browser console for any errors
3. Test both class-based and JavaScript-based cancel buttons
4. Verify the `onComplete` callback is triggered
5. Test error scenarios by providing invalid subscription IDs

### Need Help?

If you encounter any issues with the integration, please contact our support team.
