Event Forwarding

Overview

The Rose widget automatically forwards analytics events to your website via the browser's postMessage API. This allows you to capture Rose interactions in your own analytics tools (Google Analytics, Mixpanel, Segment, etc.) without any additional configuration.

This feature is enabled by default - no setup required on your end.

How It Works

sequenceDiagram participant User participant Rose Widget participant Your Page participant Your Analytics User->>Rose Widget: Interacts (click, type, etc.) Rose Widget->>Rose Widget: Tracks event internally Rose Widget->>Your Page: postMessage(event) Your Page->>Your Analytics: Forward to GA4, Mixpanel, etc.

Listening for Events

Add this JavaScript to your website to receive Rose events:

window.addEventListener('message', (event) => {
    // Filter for Rose analytics events
    if (event.data?.type === 'rose-analytics-event') {
        const { eventType, category, properties, context } = event.data.payload;

        console.log('Rose event:', eventType, properties);

        // Forward to your analytics system
        // Example: gtag('event', eventType, properties);
    }
});

Event Format

Each event message has the following structure:

interface RoseEventMessage {
    type: 'rose-analytics-event';
    payload: {
        eventType: string;      // e.g., 'message_sent', 'cta_clicked'
        category: string;       // 'user_action', 'conversion', or 'system'
        properties: object;     // Event-specific data
        context: {
            sessionId: string;  // Rose conversation session ID
            domain: string;     // Current domain
            timestamp: number;  // Unix timestamp (ms)
        };
    };
}

Event Categories

Events are organized into three categories:

Category	Description	Examples
user_action	User interactions with the widget	Clicking, typing, hovering
conversion	Key conversion events	CTA clicks, form submissions
system	Widget lifecycle events	Widget displayed, CTA rendered

Available Events

User Action Events

Event	Description	Key Properties
typed_into_input	User typed in the input field	inputLength, isFirstInput
message_sent	User sent a message	messageNumber, messageLength
mouse_hover	User hovered over the widget	widgetState
click_hidden_zone	User clicked to reveal widget	clickMethod
widget_revealed_by_scroll	Widget revealed by scrolling	viewport_height, scroll_position
dynamic_question_clicked	Clicked a suggested question	questionText, language
follow_up_question_clicked	Clicked a follow-up question	questionText, questionIndex
suggested_answer_clicked	Clicked a suggested answer	answerText, answerIndex
minimized_dynamic_questions	Minimized the question list	isMinimized, totalQuestions

Conversion Events

Event	Description	Key Properties
cta_clicked	User clicked a CTA button	url, label, ctaId
form_submitted	Form submission detected	formId, status, detectionMethod
cta_page_display	User arrived at CTA destination	pageUrl, source

System Events

Event	Description	Key Properties
widget_impression	Widget was displayed	siteName
cta_rendered	CTA button was rendered	language, url, label
dynamic_question_displayed	Question was shown	questionText, language
follow_up_questions_displayed	Follow-up questions shown	questionCount, questions
suggested_answers_displayed	Suggested answers shown	answerCount, answers

Complete Example: Google Analytics 4

// Listen for Rose events and forward to GA4
window.addEventListener('message', (event) => {
    if (event.data?.type !== 'rose-analytics-event') return;

    const { eventType, category, properties, context } = event.data.payload;

    // Map Rose events to GA4
    gtag('event', `rose_${eventType}`, {
        event_category: category,
        rose_session_id: context.sessionId,
        ...properties
    });

    // Track specific conversions
    if (eventType === 'cta_clicked') {
        gtag('event', 'conversion', {
            send_to: 'AW-XXXXXXXXXX/XXXXXXXXXXXX',
            rose_session_id: context.sessionId
        });
    }
});

Security Considerations

• Only non-sensitive event data is forwarded (no PII, no conversation content)
• The context.sessionId allows you to correlate events with Rose conversations

Debugging

To see events in real-time during development:

1. Open your browser's Developer Tools (F12)
2. Go to the Console tab
3. Add the event listener above with console.log
4. Interact with the Rose widget to see events