Widget Positioning

This document explains how to configure the position and placement of the InsightEmbed widget on your website.

Position Overview

The InsightEmbed widget can be positioned anywhere on your website to provide the optimal user experience. You can control both the initial position of the widget button and the direction in which the analysis panel opens.

Configuration Methods

You can configure the widget's position through:

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

Basic Positioning

Edge Anchoring

The widget can be anchored to any edge of the viewport:

Position	Description
bottom-right	Bottom right corner (default)
bottom-left	Bottom left corner
top-right	Top right corner
top-left	Top left corner
middle-right	Middle of the right edge
middle-left	Middle of the left edge

Offset from Edge

You can specify the distance from the viewport edge:

Property	Description	Default
horizontalOffset	Distance from left/right edge in pixels	20
verticalOffset	Distance from top/bottom edge in pixels	20

Panel Opening Direction

The analysis panel can open in different directions relative to the widget button:

Direction	Description
up	Panel opens upward from the button
down	Panel opens downward from the button
left	Panel opens to the left of the button
right	Panel opens to the right of the button
auto	Direction is automatically determined based on available space (default)

Z-Index Control

You can control the stacking order of the widget relative to other elements on your page:

Property	Description	Default
zIndex	CSS z-index value for the widget	9999

Example Configuration

Using the Management Portal

Navigate to Widget Settings > Positioning in the Management Portal to access the visual position editor.

Using JavaScript Initialization

InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  position: {
    anchor: 'bottom-left',
    horizontalOffset: 30,
    verticalOffset: 25,
    openDirection: 'up',
    zIndex: 10000
  }
});

Using the API

curl -X PATCH https://api.insightembed.com/v1/widget/configuration \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": {
      "anchor": "bottom-left",
      "horizontalOffset": 30,
      "verticalOffset": 25,
      "openDirection": "up",
      "zIndex": 10000
    }
  }'

Advanced Positioning

Responsive Positioning

You can specify different positions for different screen sizes:

InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  position: {
    // Default position for all screen sizes
    anchor: 'bottom-right',
    
    // Override for mobile devices
    responsive: {
      mobile: {
        anchor: 'bottom-center',
        verticalOffset: 10
      },
      // Override for tablet devices
      tablet: {
        anchor: 'middle-right'
      }
    }
  }
});

Custom Selector Positioning

For more precise control, you can attach the widget to a specific element on your page:

InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  position: {
    type: 'selector',
    selector: '#widget-container',
    alignment: 'center', // 'left', 'right', 'center'
    openDirection: 'up'
  }
});

Inline Positioning

You can embed the widget inline within your content:

<div id="inline-widget-container"></div>

<script>
  InsightEmbed.init({
    apiKey: 'YOUR_WIDGET_API_KEY',
    position: {
      type: 'inline',
      container: '#inline-widget-container'
    }
  });
</script>

Position Constraints

Exclusion Zones

You can define areas where the widget should not appear:

InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  position: {
    anchor: 'bottom-right',
    exclusionZones: [
      {
        selector: '#chat-widget',
        margin: 20 // Keep 20px distance from this element
      },
      {
        selector: '.cookie-banner',
        margin: 10
      }
    ]
  }
});

Collision Detection

The widget automatically detects and avoids collisions with other fixed elements on your page. You can control this behavior:

InsightEmbed.init({
  apiKey: 'YOUR_WIDGET_API_KEY',
  position: {
    anchor: 'bottom-right',
    collisionDetection: {
      enabled: true,
      avoidFixed: true,
      avoidSelectors: ['.chat-button', '#feedback-tab']
    }
  }
});

Best Practices

1. Consider User Experience: Position the widget where it's accessible but not intrusive

2. Mobile Optimization: Use responsive positioning to ensure good placement on mobile devices

3. Avoid Conflicts: Use exclusion zones to prevent overlap with other floating elements

4. Test Thoroughly: Test your positioning across different devices and screen sizes

5. Consider Page Content: For content-heavy sites, consider inline positioning within the content

Common Positioning Scenarios

Blog or Content Site

Recommended position: bottom-right or middle-right with panel opening to the left

E-commerce Product Page

Recommended position: Inline positioning near product description or bottom-left to avoid cart buttons

Documentation Site

Recommended position: top-right with panel opening downward or inline within content sections

Dashboard or Application

Recommended position: Custom selector positioning in a designated area of your UI