Widget Setup Guide

Learn how to embed the SpotEngine widget on your website

On this page

1. Basic Usage

The simplest way to add an ad spot to your page. Just include the script and add the custom element with your token.

index.html 
<spot-engine token="YOUR_EMBED_TOKEN"></spot-engine>

<script src="https://cdn.spotengine.io/widget.js"></script>

Tip: You can find your embed token on the ad spot details page in your dashboard.

2. Setting Dimensions

Specify width and height to reserve space and prevent layout shift when the ad loads:

index.html 
<spot-engine
  token="YOUR_EMBED_TOKEN"
  width="300"
  height="250"
></spot-engine>

Note: The dimensions should match your ad spot configuration. You can find these on the ad spot details page.

3. Custom Styling with CSS Variables

Customize the widget appearance to match your site's design using CSS variables:

styles.css 
.custom-ad {
  --se-primary-color: #8b5cf6;
  --se-text-color: #1f2937;
  --se-border-radius: 12px;
  --se-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}
index.html 
<spot-engine
  token="YOUR_EMBED_TOKEN"
  class="custom-ad"
></spot-engine>

4. Multiple Ad Spots on One Page

You can embed multiple ad spots on a single page, each with their own token:

index.html 
<!-- Sidebar ad -->
<spot-engine token="SIDEBAR_TOKEN"></spot-engine>

<!-- Footer ad -->
<spot-engine token="FOOTER_TOKEN"></spot-engine>

<!-- Only include the script once -->
<script src="https://cdn.spotengine.io/widget.js"></script>

5. Theme Examples

Here are some pre-built theme examples you can use or adapt:

Purple Theme

styles.css 
.purple-theme {
  --se-primary-color: #8b5cf6;
  --se-primary-hover: #7c3aed;
  --se-border-color: #c4b5fd;
  --se-border-radius: 16px;
}

Dark Theme

styles.css 
.dark-theme {
  --se-ad-bg: #1f2937;
  --se-text-color: #f9fafb;
  --se-text-secondary: #9ca3af;
  --se-border-color: #374151;
  --se-primary-color: #60a5fa;
}

Minimal Theme

styles.css 
.minimal-theme {
  --se-border-color: transparent;
  --se-border-radius: 0;
  --se-ad-bg: transparent;
  --se-shadow: none;
}

Other Targeting Options

You can target widgets in different ways:

styles.css 
/* Target by token attribute */
spot-engine[token="abc123"] {
  --se-primary-color: red;
}

/* Target by ID */
#sidebar-ad {
  --se-primary-color: blue;
}

/* Target by location */
.sidebar spot-engine {
  --se-primary-color: green;
}

footer spot-engine {
  --se-ad-bg: #1f2937;
}

6. Zero Layout Shift

For the best user experience, prevent layout shift by styling the widget before JavaScript loads:

styles.css 
/* Add to your <head> - styles widget before JS registers it */
spot-engine:not(:defined) {
  display: block;
  min-height: 80px;
  background: #f3f4f6;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
}

Combined with width/height attributes:

index.html 
<spot-engine
  token="YOUR_EMBED_TOKEN"
  width="300"
  height="250"
></spot-engine>

Why this works: The :not(:defined) selector targets custom elements before their JavaScript is loaded. Once the widget script runs, the element becomes "defined" and your styles take over.

7. All CSS Variables

Here's a complete list of all available CSS variables for customization:

styles.css 
/* Colors */
--se-primary-color: #3b82f6;      /* Primary/CTA color */
--se-primary-hover: #2563eb;      /* Primary color on hover */
--se-text-color: #1f2937;         /* Main text color */
--se-text-secondary: #6b7280;     /* Secondary text color */
--se-border-color: #e5e7eb;       /* Border color */

/* Layout */
--se-border-radius: 8px;          /* Border radius */
--se-shadow: 0 1px 3px rgba(...); /* Box shadow */

/* Typography */
--se-font-family: system-ui;      /* Font family */

/* Backgrounds */
--se-ad-bg: #ffffff;              /* Ad background */
--se-icon-bg: #f9fafb;            /* Icon background */
--se-empty-bg: #f9fafb;           /* Empty state background */

/* States */
--se-loading-bg: #e5e7eb;         /* Loading skeleton color */
--se-error-bg: #fef2f2;           /* Error background */
--se-error-border: #fecaca;       /* Error border */
--se-error-text: #991b1b;         /* Error text color */