Getting Started

Quick Start

Add the following script before the closing </body> tag of your page:

<script src="https://cdn.metios.app/embed.js"></script>
<script>
  Metios.init({
    surveyId: 'your-survey-uuid',
  });
</script>

That’s it! Metios will automatically fetch your survey configuration and display it based on the trigger settings configured in your dashboard.

How It Works

The Metios embed script dynamically loads a survey widget into your page using an <iframe>. It handles:

Fetching survey configuration from the Metios API at /api/embed/{uuid}
Auto-triggering based on the configured behavior (page load, scroll, exit intent, inline)
Responsive positioning and resizing for different devices
Smooth animations with viewport-safe rendering
Auto-scroll functionality to keep the widget visible when it expands

The widget automatically adjusts its height based on content and ensures it stays within the viewport boundaries.

Configuration Options

The embed script supports both automatic configuration (fetched from your dashboard) and manual overrides:

Required Parameters

Parameter	Type	Description
`surveyId`	`string`	The unique UUID of your survey (required)

Optional Override Parameters

Parameter	Type	Default	Description
`trigger`	`string`	From dashboard	Override trigger type (‘page_load’, ‘scroll’, ‘exit-intent’, ‘inline’)
`position`	`string`	From dashboard	Widget position (‘bottom-right’, ‘bottom-left’, ‘top-right’, ‘top-left’, ‘center’)
`inlineSelector`	`string`	From dashboard	CSS selector for inline embedding
`width`	`string`	`'450px'`	Widget width (ignored for inline mode)
`initialHeight`	`number`	`220`	Initial widget height before auto-resize
`zIndex`	`string`	`'999999'`	CSS z-index for layering
`timeSeconds`	`number`	From dashboard	Delay for time-based triggers
`scrollPercent`	`number`	From dashboard	Scroll percentage trigger threshold
`viewportMargin`	`number`	`40`	Margin for viewport clamping (total pixels)

Trigger Types

Page Load (Default)

Displays the survey after a specified time delay when the page loads.

<script src="https://cdn.metios.app/embed.js"></script>
<script>
  Metios.init({
    surveyId: 'your-survey-uuid'
    // Uses settings from dashboard
  });
</script>

Scroll Trigger

Shows the survey when the user scrolls to a specific percentage of the page.

<script src="https://cdn.metios.app/embed.js"></script>
<script>
  Metios.init({
    surveyId: 'your-survey-uuid',
    trigger: 'scroll',
    scrollPercent: 75  // Override dashboard setting
  });
</script>

Exit Intent

Triggers when the user moves their cursor toward the browser’s close button or address bar.

<script src="https://cdn.metios.app/embed.js"></script>
<script>
  Metios.init({
    surveyId: 'your-survey-uuid',
    trigger: 'exit-intent'
  });
</script>

Inline Embed

Embeds the survey directly into a specific element on your page.

<div id="feedback-section"></div>

<script src="https://cdn.metios.app/embed.js"></script>
<script>
  Metios.init({
    surveyId: 'your-survey-uuid',
    trigger: 'inline',
    inlineSelector: '#feedback-section'
  });
</script>

For floating widgets (non-inline), you can position the widget in different areas:

bottom-right (default) - Bottom right corner
bottom-left - Bottom left corner
top-right - Top right corner
top-left - Top left corner
center - Centered on screen

<script>
  Metios.init({
    surveyId: 'your-survey-uuid',
    position: 'top-left'
  });
</script>

Automatic Features

Dynamic Resizing

The widget automatically adjusts its height based on content and sends resize messages to the parent window. The embed script:

Listens for resize messages from the widget
Clamps height to viewport with configurable margin
Only applies meaningful height changes (6px threshold by default)

Auto-Scroll

When the widget resizes, it ensures the entire widget remains visible by:

Checking if the widget extends beyond viewport boundaries
Automatically scrolling the parent page minimally to reveal hidden content
Using 12px margins from viewport edges for comfortable viewing

Responsive Design

Mobile-friendly responsive design
Minimum width of 280px maintained
Automatic width adjustment for inline embeds (100% of container)

API Endpoints

The embed system uses these public API endpoints:

Get Survey Configuration

GET /api/embed/{uuid}

Returns survey configuration including:

Survey metadata (title, description, theme)
Questions and options
Trigger settings (type, timing, positioning)
Subscription status

Submit Response

POST /api/embed/{uuid}/submit

Accepts survey responses with:

Answers object with question responses
Automatic IP address, user agent, and referrer capture
Country code detection (optional)

Survey Requirements

For a survey to be embeddable:

Survey Status: Must be set to 'active' status
Valid UUID: Survey must exist in the database
Questions: At least one question configured
Trigger Settings: Properly configured in the dashboard

Note: Inactive surveys return a 403 status and will not display the widget.

Troubleshooting

Check Survey Status: Ensure your survey is set to “Active” in your dashboard
Verify Survey ID: Confirm you’re using the correct UUID (not the internal database ID)
Console Errors: Check browser console for API errors:
- 404 - Survey not found (check UUID)
- 403 - Survey not active or not available
Script Loading: Ensure the embed script loads before initialization
Inline Target: For inline mode, verify the target element exists in DOM

Common Issues

// ❌ Wrong - using internal ID instead of UUID  
surveyId: '123'

// ✅ Correct - using survey UUID
surveyId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'

<!-- ❌ Wrong - script after initialization -->
<script>
  Metios.init({ surveyId: 'uuid' });
</script>
<script src="https://cdn.metios.app/embed.js"></script>

<!-- ✅ Correct - embed script loaded first -->
<script src="https://cdn.metios.app/embed.js"></script>
<script>
  Metios.init({ surveyId: 'uuid' });
</script>

Debug Information

The embed script includes version information in console:

// Metios Embed Script  
// Version: 1.0.4-dynamic (auto-scroll to keep full widget visible)

For additional debugging, check the network tab for API calls to /api/embed/{uuid}.

Advanced Configuration

Multiple Surveys

You can embed multiple surveys on the same page:

<script src="https://cdn.metios.app/embed.js"></script>
<script>
  // First survey
  Metios.init({
    surveyId: 'survey-1-uuid',
    position: 'bottom-right'
  });

  // Second survey  
  Metios.init({
    surveyId: 'survey-2-uuid',
    trigger: 'inline',
    inlineSelector: '#feedback-2'
  });
</script>

Security & Privacy

All survey data is transmitted securely via HTTPS
IP addresses and user agents are captured for analytics (configurable)
No cookies or local storage used by the widget
GDPR compliant data collection
Referrer URLs captured for traffic analysis

Performance

The Metios embed is optimized for performance:

Lazy Loading: Widget content loaded only when triggered
Minimal Bundle: Lightweight JavaScript footprint
CDN Delivery: Fast global content delivery
Async Loading: Non-blocking script loading
Efficient Messaging: Minimal parent-iframe communication

Version Information

Current embed version: 1.0.4-dynamic Features:

Auto-scroll to keep full widget visible
Dynamic height adjustment with viewport clamping
Reduced jitter with height change thresholds
Improved cross-browser compatibility

Support

Documentation: https://docs.metios.app
Dashboard: https://app.metios.app
Support: [email protected]

Getting Started

Quick Start

How It Works

Configuration Options

Required Parameters

Optional Override Parameters

Trigger Types

Page Load (Default)

Scroll Trigger

Exit Intent

Inline Embed

Widget Positions

Automatic Features

Dynamic Resizing

Auto-Scroll

Responsive Design

API Endpoints

Get Survey Configuration

Submit Response

Survey Requirements

Troubleshooting

Widget Not Appearing

Common Issues

Debug Information

Advanced Configuration

Multiple Surveys

Security & Privacy

Performance

Version Information

Support

Getting started

​Quick Start

​How It Works

​Configuration Options

​Required Parameters

​Optional Override Parameters

​Trigger Types

​Page Load (Default)

​Scroll Trigger

​Exit Intent

​Inline Embed

​Widget Positions

​Automatic Features

​Dynamic Resizing

​Auto-Scroll

​Responsive Design

​API Endpoints

​Get Survey Configuration

​Submit Response

​Survey Requirements

​Troubleshooting

​Widget Not Appearing

​Common Issues

​Debug Information

​Advanced Configuration

​Multiple Surveys

​Security & Privacy

​Performance

​Version Information

​Support

Quick Start

How It Works

Configuration Options

Required Parameters

Optional Override Parameters

Trigger Types

Page Load (Default)

Scroll Trigger

Exit Intent

Inline Embed

Widget Positions

Automatic Features

Dynamic Resizing

Auto-Scroll

Responsive Design

API Endpoints

Get Survey Configuration

Submit Response

Survey Requirements

Troubleshooting

Widget Not Appearing

Common Issues

Debug Information

Advanced Configuration

Multiple Surveys

Security & Privacy

Performance

Version Information

Support