Pular para o conteúdo principal
Zenovaydocs
6 min de leitura

Embeddable Widgets

Zenovay provides ready-to-use widgets that you can embed on your website to display live visitor counts, activity timelines, and geographic breakdowns. No authentication required - just use your tracking code.

Widget Types

WidgetDescriptionUse Case
RealtimeLive visitor countShow current online visitors
Preview24-hour activity timelineDisplay visitor activity over the past day
Recent30-minute breakdown by countryShow recent visitor locations

Base URL

All widget endpoints are available at:

https://api.zenovay.com/widgets/{trackingCode}

Replace {trackingCode} with your website's tracking code (e.g., ZV_XXXXXXXXXXX).

Realtime Widget

Displays the current number of live visitors on your website:

GET/widgets/:trackingCode/realtime

Live visitor count widget

Query Parameters:

ParameterTypeDefaultDescription
mainTextSizestring48pxFont size for the visitor count
primaryColorstring#e78468Primary accent color (hex)
themestringsystemTheme: light, dark, or system
hideBrandingbooleanfalseHide "Powered by Zenovay" footer (Enterprise)
Embed with iframeHTML
<iframe
src="https://api.zenovay.com/widgets/ZV_XXXXXXXXXXX/realtime?theme=dark&primaryColor=%236366f1"
width="200"
height="120"
frameborder="0"
style="border-radius: 12px; overflow: hidden;"
></iframe>

Widget Preview:

The realtime widget displays:

  • Large visitor count number
  • "visitors online now" label
  • Animated pulse indicator
  • Optional branding footer

Preview Widget (24-Hour Timeline)

Displays visitor activity over the past 24 hours as a timeline chart:

GET/widgets/:trackingCode/preview

24-hour activity timeline widget

Query Parameters:

ParameterTypeDefaultDescription
mainTextSizestring36pxFont size for the total count
primaryColorstring#e78468Chart line color (hex)
secondaryColorstring#8dcdffChart fill color (hex)
themestringsystemTheme: light, dark, or system
Embed with iframeHTML
<iframe
src="https://api.zenovay.com/widgets/ZV_XXXXXXXXXXX/preview?theme=light&primaryColor=%236366f1"
width="400"
height="200"
frameborder="0"
style="border-radius: 12px; overflow: hidden;"
></iframe>

Widget Preview:

The preview widget displays:

  • Total visitors in the last 24 hours
  • Hourly breakdown chart
  • Peak hour indicator
  • Trend arrow (up/down vs previous day)

Recent Widget (Country Breakdown)

Displays visitor activity from the last 30 minutes broken down by country:

GET/widgets/:trackingCode/recent

30-minute breakdown by country

Query Parameters:

ParameterTypeDefaultDescription
mainTextSizestring32pxFont size for the count
primaryColorstring#e78468Primary accent color (hex)
themestringsystemTheme: light, dark, or system
hideBrandingbooleanfalseHide branding footer (Enterprise)
Embed with iframeHTML
<iframe
src="https://api.zenovay.com/widgets/ZV_XXXXXXXXXXX/recent?theme=dark"
width="300"
height="250"
frameborder="0"
style="border-radius: 12px; overflow: hidden;"
></iframe>

Widget Preview:

The recent widget displays:

  • Visitor count from the last 30 minutes
  • Top countries with flags
  • Percentage breakdown by country
  • Live updating every 30 seconds

Styling Examples

Dark Theme with Custom Colors

Dark Theme WidgetHTML
<iframe
src="https://api.zenovay.com/widgets/ZV_XXXXXXXXXXX/realtime?theme=dark&primaryColor=%2310b981&mainTextSize=64px"
width="220"
height="140"
frameborder="0"
style="border-radius: 16px; box-shadow: 0 4px 6px -1px rgba(0,0,0,0.1);"
></iframe>

Light Theme for Dashboards

Dashboard WidgetHTML
<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px;">
<!-- Live Visitors -->
<iframe
  src="https://api.zenovay.com/widgets/ZV_XXXXXXXXXXX/realtime?theme=light"
  width="100%"
  height="120"
  frameborder="0"
></iframe>

<!-- 24h Timeline -->
<iframe
  src="https://api.zenovay.com/widgets/ZV_XXXXXXXXXXX/preview?theme=light"
  width="100%"
  height="120"
  frameborder="0"
></iframe>

<!-- Countries -->
<iframe
  src="https://api.zenovay.com/widgets/ZV_XXXXXXXXXXX/recent?theme=light"
  width="100%"
  height="120"
  frameborder="0"
></iframe>
</div>

JavaScript Dynamic Loading

Load widgets dynamically with JavaScript:

Dynamic Widget LoadingJavaScript
function loadZenovayWidget(trackingCode, type, options = {}) {
const defaults = {
  theme: 'system',
  primaryColor: '#e78468',
  mainTextSize: '48px'
};

const settings = { ...defaults, ...options };
const params = new URLSearchParams(settings).toString();

const iframe = document.createElement('iframe');
iframe.src = `https://api.zenovay.com/widgets/${trackingCode}/${type}?${params}`;
iframe.width = options.width || '200';
iframe.height = options.height || '120';
iframe.frameBorder = '0';
iframe.style.borderRadius = '12px';

return iframe;
}

// Usage
const widget = loadZenovayWidget('ZV_XXXXXXXXXXX', 'realtime', {
theme: 'dark',
primaryColor: '#10b981',
width: '250',
height: '150'
});

document.getElementById('widget-container').appendChild(widget);

React Component

Embed widgets in React applications:

React Widget ComponentTSX
interface ZenovayWidgetProps {
trackingCode: string;
type: 'realtime' | 'preview' | 'recent';
theme?: 'light' | 'dark' | 'system';
primaryColor?: string;
width?: number;
height?: number;
}

function ZenovayWidget({
trackingCode,
type,
theme = 'system',
primaryColor = '#e78468',
width = 200,
height = 120
}: ZenovayWidgetProps) {
const params = new URLSearchParams({
  theme,
  primaryColor
}).toString();

return (
  <iframe
    src={`https://api.zenovay.com/widgets/${trackingCode}/${type}?${params}`}
    width={width}
    height={height}
    frameBorder="0"
    style={{ borderRadius: '12px', overflow: 'hidden' }}
    title={`Zenovay ${type} widget`}
  />
);
}

// Usage
<ZenovayWidget
trackingCode="ZV_XXXXXXXXXXX"
type="realtime"
theme="dark"
primaryColor="#10b981"
width={250}
height={150}
/>

Vue Component

Embed widgets in Vue applications:

Vue Widget ComponentVUE
<template>
<iframe
  :src="widgetUrl"
  :width="width"
  :height="height"
  frameborder="0"
  :style="{ borderRadius: '12px', overflow: 'hidden' }"
  :title="`Zenovay ${type} widget`"
/>
</template>

<script setup lang="ts">
import { computed } from 'vue';

interface Props {
trackingCode: string;
type: 'realtime' | 'preview' | 'recent';
theme?: 'light' | 'dark' | 'system';
primaryColor?: string;
width?: number;
height?: number;
}

const props = withDefaults(defineProps<Props>(), {
theme: 'system',
primaryColor: '#e78468',
width: 200,
height: 120
});

const widgetUrl = computed(() => {
const params = new URLSearchParams({
  theme: props.theme,
  primaryColor: props.primaryColor
}).toString();

return `https://api.zenovay.com/widgets/${props.trackingCode}/${props.type}?${params}`;
});
</script>

White-Label (Enterprise)

Enterprise customers can remove Zenovay branding:

White-Label WidgetHTML
<iframe
src="https://api.zenovay.com/widgets/ZV_XXXXXXXXXXX/realtime?hideBranding=true&primaryColor=%23your-brand-color"
width="200"
height="100"
frameborder="0"
></iframe>

The hideBranding parameter is only available on the Enterprise plan. Contact sales to enable white-label widgets for your account.

Caching and Performance

Widgets are optimized for performance:

  • CDN Cached: Widget HTML is cached at the edge for fast loading
  • Data Updates: Live data refreshes every 5-30 seconds automatically
  • Lightweight: Self-contained HTML with no external dependencies
  • Responsive: Widgets adapt to their container size

Security Considerations

Widgets only display read-only analytics data. Your tracking code is designed to be public and cannot be used to modify or access sensitive data.

  • Widgets use your public tracking code, not your API key
  • No authentication is required to display widgets
  • Data displayed is limited to aggregate statistics
  • No personally identifiable information is exposed

Next Steps

Esta página foi útil?