InsightEmbed Docs

Appearance

Widget Visibility Settings ​

This document explains how to configure the visibility behavior of the InsightEmbed widget on your website.

Visibility Overview ​

InsightEmbed offers flexible visibility settings that allow you to control when and how the widget appears to your website visitors. You can configure these settings to ensure the widget enhances user experience without being intrusive.

Configuration Methods ​

You can configure the widget's visibility through:

  1. Management Portal: Use the visibility settings in the Management Portal
  2. API: Set visibility properties programmatically via the Widget Configuration API
  3. Initialization Options: Pass visibility settings when initializing the widget

Basic Visibility Options ​

Initial State ​

PropertyDescriptionDefault
initiallyVisibleWhether the widget button is visible when the page loadstrue
initiallyExpandedWhether the widget panel is expanded when the page loadsfalse

Display Delay ​

PropertyDescriptionDefault
showDelayDelay in milliseconds before showing the widget after page load0
expandDelayDelay in milliseconds before auto-expanding the widget (if enabled)0

Page-Based Visibility ​

URL Patterns ​

You can show or hide the widget based on URL patterns:

javascript
InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  visibility: {
    urlPatterns: {
      include: [
        '/blog/*',
        '/products/*'
      ],
      exclude: [
        '/checkout/*',
        '/admin/*'
      ]
    }
  }
});

Query Parameters ​

You can control visibility based on URL query parameters:

javascript
InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  visibility: {
    queryParams: {
      // Show widget only when ?showWidget=true is in the URL
      showWidget: 'true',
      // Hide widget when ?hideWidget=true is in the URL
      hideWidget: 'true'
    }
  }
});

User-Based Visibility ​

User Segments ​

You can show the widget only to specific user segments:

javascript
InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  visibility: {
    userSegments: {
      // Show to logged-in users only
      loggedIn: true,
      // Show to users with specific roles
      roles: ['premium', 'admin']
    }
  }
});

Visitor History ​

You can control visibility based on visitor history:

javascript
InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  visibility: {
    visitorHistory: {
      // Show only to returning visitors
      returningOnly: true,
      // Show only after X page views
      minPageViews: 3,
      // Hide after X uses of the widget
      hideAfterUses: 10
    }
  }
});

Behavior-Based Visibility ​

Scroll Depth ​

You can show the widget after the user scrolls to a certain depth:

javascript
InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  visibility: {
    scrollTrigger: {
      enabled: true,
      depth: 50, // Show after scrolling 50% of the page
      delay: 500 // Wait 500ms after reaching scroll depth
    }
  }
});

Time on Page ​

You can show the widget after the user spends a certain amount of time on the page:

javascript
InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  visibility: {
    timeTrigger: {
      enabled: true,
      seconds: 30 // Show after 30 seconds on the page
    }
  }
});

Exit Intent ​

You can show the widget when the user shows exit intent (moving cursor toward browser controls):

javascript
InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  visibility: {
    exitIntent: {
      enabled: true,
      sensitivity: 20, // Higher values = more sensitive detection
      delay: 300, // Delay before showing after detecting exit intent
      showOnce: true // Only show once per session
    }
  }
});

Responsive Visibility ​

Device Types ​

You can control visibility based on device type:

javascript
InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  visibility: {
    devices: {
      desktop: true,
      tablet: true,
      mobile: false // Hide on mobile devices
    }
  }
});

Screen Size ​

You can control visibility based on screen size breakpoints:

javascript
InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  visibility: {
    breakpoints: {
      min: 768, // Hide on screens smaller than 768px
      max: 1920 // Hide on screens larger than 1920px
    }
  }
});

Programmatic Control ​

You can programmatically control the widget's visibility using JavaScript methods:

javascript
// Initialize the widget
const widget = InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY'
});

// Show the widget
widget.show();

// Hide the widget
widget.hide();

// Toggle the widget visibility
widget.toggle();

// Expand the widget panel
widget.expand();

// Collapse the widget panel
widget.collapse();

Example Configuration ​

Using the Management Portal ​

Navigate to Widget Settings > Visibility in the Management Portal to access the visibility settings.

Using JavaScript Initialization ​

javascript
InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  visibility: {
    initiallyVisible: true,
    showDelay: 2000,
    urlPatterns: {
      include: ['/blog/*', '/products/*'],
      exclude: ['/checkout/*']
    },
    scrollTrigger: {
      enabled: true,
      depth: 30
    },
    devices: {
      desktop: true,
      tablet: true,
      mobile: true
    }
  }
});

Using the API ​

bash
curl -X PATCH https://api.insightembed.com/v1/widget/configuration \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": {
      "initiallyVisible": true,
      "showDelay": 2000,
      "urlPatterns": {
        "include": ["/blog/*", "/products/*"],
        "exclude": ["/checkout/*"]
      },
      "scrollTrigger": {
        "enabled": true,
        "depth": 30
      },
      "devices": {
        "desktop": true,
        "tablet": true,
        "mobile": true
      }
    }
  }'

Best Practices ​

  1. Be Considerate: Avoid showing the widget in ways that might disrupt the user experience

  2. Target Appropriately: Show the widget on pages where content analysis would be most valuable

  3. Respect User Choice: If a user dismisses the widget, respect that choice for a reasonable period

  4. Test Different Strategies: Experiment with different visibility settings to find what works best

  5. Mobile Considerations: Consider using different visibility settings for mobile devices

Common Visibility Scenarios ​

Blog or Article Pages ​

Recommended settings: Show after 30% scroll depth or 20 seconds on page

Product Pages ​

Recommended settings: Initially visible with prominent placement

Documentation Pages ​

Recommended settings: Initially visible but collapsed, with clear indication of functionality

Landing Pages ​

Recommended settings: Show only after significant engagement (50% scroll or 45 seconds)

© 2026 InsightEmbed