Widget de Encuesta SoluCX - SDK Componente Web

Un componente de widget de encuesta personalizable construido con Vue.js que puede integrarse en varios frameworks web. Este widget permite incorporar encuestas SoluCX directamente en tus aplicaciones con soporte para diferentes modos de visualización y manejo completo de eventos.

Funcionalidades

  • 🎯 Varios tipos de widget: inline, modal, barra inferior, caja inferior (derecha/izquierda)
  • 📱 Diseño responsivo con dimensiones personalizables
  • 🔒 Enfoque en seguridad con validación de dominio y sanitización de datos
  • 📊 Analítica integrada y seguimiento del comportamiento del usuario
  • ⚡ Agnóstico de framework: funciona con Vue, React, Angular y otros
  • 🎨 Estilización y posicionamiento personalizables
  • 📡 Manejo de eventos en tiempo real y callbacks

Instalación

npm install solucx-survey-widget

Configuración

El widget requiere las siguientes propiedades:

PropiedadTipoObligatorioDescripción
soluCxKeystring✅Tu clave de encuesta SoluCX
widgetTypeWidgetType✅Modo de visualización: 'inline', 'modal', 'bottomBar', 'bottomBox', 'bottomBoxLeft'
widgetDataWidgetData | string✅Datos de la encuesta (objeto o string JSON)
widgetOptionsWidgetOptions | string❌Opciones de configuración

Estructura de los Datos del Widget

interface WidgetData {
    customer_id?: string
    email?: string
    name?: string
    phone?: string
    document?: string
    transaction_id?: string
    // ... otros campos personalizados
}

Opciones del Widget

interface WidgetOptions {
    width?: number        // Ancho del widget en píxeles
    height?: number       // Alto del widget en píxeles
    retry?: {
        attempts?: number   // Máximo de intentos de repetición (por defecto: 5)
        interval?: number   // Intervalo de repetición en días (por defecto: 1)
    }
    waitDelayAfterRating?: number // Días de espera después de la evaluación (por defecto: 60)
}

Ejemplos de Uso Básico

Importación Directa y Uso

app.js
    // Importa el componente directamente
    import SoluCXSurveyWidget from 'solucx-survey-widget'

    // Usa en tu template/JSX
    <SoluCXSurveyWidget
    solu-cx-key="tu-clave-de-encuesta"
    widget-type="inline"
    widget-data='{"customer_id": "12345", "email": "[email protected]"}'
    />
    ```

Componente Web (HTML/JS Puro)

app.html
    <!DOCTYPE html>
    <html>
    <head>
    <title>Encuesta SoluCX</title>
    </head>
    <body>
    <!-- Incluye el widget -->
    <script type="module">
            import 'solucx-survey-widget'
    </script>
    
    <!-- Usa el componente web -->
    <solucx-survey-widget
            solu-cx-key="tu-clave-de-encuesta"
            widget-type="bottomBox"
            widget-data='{"customer_id": "12345", "email": "[email protected]"}'
            widget-options='{"width": 400, "height": 300}'
    ></solucx-survey-widget>

    <script>
            // Escucha los eventos
            const widget = document.querySelector('solucx-survey-widget')
            
            widget.addEventListener('widgetCompleted', (event) => {
            console.log('¡Encuesta completada!')
            })
            
            widget.addEventListener('widgetError', (event) => {
            console.error('Error en el widget:', event.detail)
            })
    </script>
    </body>
    </html>
    ```

Uso vía CDN

<!DOCTYPE html>
<html>
<head>
    <title>Encuesta SoluCX - CDN</title>
</head>
<body>
    <!-- Carga vía CDN -->
    <script type="module" src="https://unpkg.com/solucx-survey-widget@latest/dist/index.js"></script>
    
    <!-- Usa el componente -->
    <solucx-survey-widget
        solu-cx-key="tu-clave-de-encuesta"
        widget-type="inline"
        widget-data='{"customer_id": "67890", "name": "Juan Pérez"}'
    ></solucx-survey-widget>
</body>
</html>

Ejemplos de Integración con Frameworks

Vue.js

app.vue
    <template>
    <div>
            <SoluCXSurveyWidget
            :solu-cx-key="surveyKey"
            widget-type="inline"
            :widget-data="surveyData"
            :widget-options="options"
            @widget-opened="onWidgetOpened"
            @widget-closed="onWidgetClosed"
            @widget-completed="onWidgetCompleted"
            />
    </div>
    </template>

    <script setup>
    import { ref } from 'vue'
    import SoluCXSurveyWidget from 'solucx-survey-widget'

    const surveyKey = 'tu-clave-de-encuesta'
    const surveyData = ref({
    customer_id: '12345',
    email: '[email protected]',
    name: 'Juan Pérez'
    })

    const options = ref({
    width: 600,
    height: 400
    })

    const onWidgetOpened = (userId) => {
    console.log('Widget abierto para el usuario:', userId)
    }

    const onWidgetClosed = () => {
    console.log('Widget cerrado')
    }

    const onWidgetCompleted = (userId) => {
    console.log('Encuesta completada por el usuario:', userId)
    }
    </script>
    ```

React

app.jsx
    import React, { useEffect, useRef } from 'react'
    import 'solucx-survey-widget'

    const SoluCXWidget = ({ 
    soluCxKey, 
    widgetType = 'inline', 
    widgetData, 
    widgetOptions = {},
    onWidgetCompleted,
    onWidgetClosed,
    onWidgetError 
    }) => {
    const widgetRef = useRef(null)

    useEffect(() => {
            const widget = widgetRef.current

            if (widget) {
            widget.soluCxKey = soluCxKey
            widget.widgetType = widgetType
            widget.widgetData = JSON.stringify(widgetData)
            widget.widgetOptions = JSON.stringify(widgetOptions)

            const handleCompleted = () => onWidgetCompleted?.(widgetData.customer_id)
            const handleClosed = () => onWidgetClosed?.()
            const handleError = (event) => onWidgetError?.(event.detail)

            widget.addEventListener('widgetCompleted', handleCompleted)
            widget.addEventListener('widgetClosed', handleClosed)
            widget.addEventListener('widgetError', handleError)

            return () => {
                    widget.removeEventListener('widgetCompleted', handleCompleted)
                    widget.removeEventListener('widgetClosed', handleClosed)
                    widget.removeEventListener('widgetError', handleError)
            }
            }
    }, [soluCxKey, widgetType, widgetData, widgetOptions])

    return <solucx-survey-widget ref={widgetRef} />
    }

    export default SoluCXWidget
    ```

Angular

app.jsx
    import { Component, Input, Output, EventEmitter, OnInit, ViewChild, ElementRef, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'

    @Component({
    selector: 'app-survey-widget',
    template: `
            <solucx-survey-widget 
            #widget
            [attr.solu-cx-key]="soluCxKey"
            [attr.widget-type]="widgetType"
            [attr.widget-data]="widgetDataString"
            [attr.widget-options]="widgetOptionsString"
            ></solucx-survey-widget>
    `,
    schemas: [CUSTOM_ELEMENTS_SCHEMA]
    })
    export class SurveyWidgetComponent implements OnInit {
    @Input() soluCxKey!: string
    @Input() widgetType: string = 'inline'
    @Input() widgetData: any = {}
    @Input() widgetOptions: any = {}
    
    @Output() widgetCompleted = new EventEmitter<string>()
    @Output() widgetClosed = new EventEmitter<void>()
    @Output() widgetError = new EventEmitter<string>()

    @ViewChild('widget', { static: true }) widget!: ElementRef

    get widgetDataString(): string {
            return JSON.stringify(this.widgetData)
    }

    get widgetOptionsString(): string {
            return JSON.stringify(this.widgetOptions)
    }

    async ngOnInit() {
            await import('solucx-survey-widget')
            
            const widgetElement = this.widget.nativeElement
            
            widgetElement.addEventListener('widgetCompleted', () => {
            this.widgetCompleted.emit(this.widgetData.customer_id)
            })
            
            widgetElement.addEventListener('widgetClosed', () => {
            this.widgetClosed.emit()
            })
            
            widgetElement.addEventListener('widgetError', (event: any) => {
            this.widgetError.emit(event.detail)
            })
    }
    }
    ```

Eventos

El widget emite los siguientes eventos:

EventoDescripciónPayload
widgetOpenedWidget mostradouserId: string
widgetClosedWidget cerrado-
widgetCompletedEncuesta completadauserId: string
widgetErrorOcurrió un errorerror: string
widgetResizedAltura del widget cambiadaheight: number
widgetPageChangedPágina de la encuesta cambiadapage: string

Tipos de Widget

  • inline: Embebido directamente en el contenido de la página
  • modal: Modal superpuesto con backdrop
  • bottomBar: Barra fija en la parte inferior con ancho completo
  • bottomBox: Caja fija en la esquina inferior derecha
  • bottomBoxLeft: Caja fija en la esquina inferior izquierda

Desarrollo

# Instala las dependencias
npm install

# Ejecuta los tests
npm test

# Build para producción
npm run build

Soporte

Para soporte y dudas, contacta al equipo de SoluCX o consulta la documentación oficial.