Widget

The Retivo widget renders intervention messages directly in your app. Available as a React component or a CDN script.

React Component

Installation

npm install @retivo/widget

Usage

import { RetivoWidget } from '@retivo/widget'

function App() {
  return (
    <>
      <YourApp />
      <RetivoWidget
        apiKey="rt_live_..."
        userId="user-123"
        position="bottom-right"
        maxVisible={3}
      />
    </>
  )
}

Props

Prop	Type	Default	Description
`apiKey`	`string`	required	Your API key
`userId`	`string`	required	Current user ID
`baseURL`	`string`	`https://retivo.ai`	API base URL
`position`	`string`	`bottom-right`	Widget position: `bottom-right`, `bottom-left`, `top-right`, `top-left`
`maxVisible`	`number`	`3`	Max messages shown simultaneously

The widget automatically connects to the SSE endpoint, receives intervention messages in real-time, and renders them as dismissible toast notifications.

CDN Script (Vanilla JS)

For non-React apps or any website:

<script src="https://cdn.retivo.ai/widget.js"></script>
<script>
  Retivo.init({
    apiKey: 'rt_live_...',
    userId: 'user-123',
    position: 'bottom-right',
  });
</script>

The CDN bundle is under 4 KB minified with zero dependencies.

Methods

// Initialize
Retivo.init({ apiKey, userId, baseURL, position })

// Tear down
Retivo.destroy()

Custom Rendering

If you want full control over message UI, use the SDK's onMessage() instead of the widget:

import { Retivo } from '@retivo/sdk'

const retivo = new Retivo({ apiKey: 'rt_live_...' })
retivo.identify('user-123')

retivo.onMessage((message) => {
  // Render your own UI
  showCustomNotification({
    text: message.body,
    id: message.interventionId,
  })
})

How It Works

The widget connects to Retivo and receives intervention messages in real-time. Messages auto-dismiss after 15 seconds or can be manually closed.

Styling

The default widget uses inline styles for zero-conflict rendering:

Dark theme (#1a1a2e background) with light text
12px border radius, subtle shadow
Teal accent dot for Retivo branding
Slide-in animation

For custom styling, use the onMessage() callback approach and render your own components.

Customizing Appearance

Override CSS variables to match your brand. These variables control the default widget theme:

:root {
  --retivo-bg: #ffffff;
  --retivo-text: #1a1a2e;
  --retivo-accent: #0ea5e9;
  --retivo-radius: 12px;
  --retivo-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

Set these variables in your global stylesheet or scoped to a container element. The widget picks up changes immediately without reinitialization.

Handling Message Actions

Use the SDK's onMessage callback to handle CTA button clicks and track message interactions:

import { Retivo } from '@retivo/sdk'

const retivo = new Retivo({ apiKey: 'rt_live_...' })
retivo.identify('user-123')

retivo.onMessage((message) => {
  // Track that the message was displayed
  retivo.track('message_displayed', {
    interventionId: message.interventionId,
    messageType: message.type,
  })

  // Handle CTA button clicks
  if (message.cta) {
    document.querySelector('.retivo-cta')?.addEventListener('click', () => {
      retivo.track('cta_clicked', {
        interventionId: message.interventionId,
        ctaLabel: message.cta.label,
        ctaUrl: message.cta.url,
      })
      window.open(message.cta.url, '_blank')
    })
  }
})

The built-in widget tracks message_displayed, message_dismissed, and cta_clicked events automatically. Custom rendering requires manual tracking as shown above.

Widget

On this page