zentis-widget

v1.0.13

Published

5 months ago

Componente Web de chat React empaquetado como Web Component (UMD/ESM). Diseñado para integrarse fácilmente en cualquier proyecto (Vanilla JS, React, .NET, PHP+Smarty, etc.) sin necesidad de configurar un bundler.

0High
0Medium
0Low

archesoftware

Zentis Chat Widget

Índice

Características

UMD + ESM
- Empaquetado en formato UMD (con CSS inyectado por JS) para uso directo en HTML estático o frameworks que no requieran bundler.
- Exporta módulo ESM (para proyectos React, Vue, Next.js u otros bundlers modernos).
Sin configuración adicional
Solo importa el bundle UMD o instala el paquete ESM; no necesitas tocar webpack, Vite u otro bundler.
API JavaScript clara
- Método init(...) para inicializar y actualizar configuración en tiempo real.
- Propiedades JavaScript (.apiKey, .endpoint, .metadata, .accountId) con setters que re-renderizan automáticamente.
- Método init(...) recibe un objeto con esas propiedades: { apiKey: apiKey, endpoint: endpoint, accountId?:accountId, metadata?:metadata }
Eventos CustomEvent
- chat-initialized
Desconexión Limpia
Cuando se elimina del DOM, desmonta el árbol React asociado para liberar memoria.

PROPIEDADES

apiKey - string obligatoria endpoint - string obligatoria accountId - string opcional metadata - objecto opcional = { name?: string; lastName?: string; email?: string; workCompany?: string; residenceCountry?: "AR" | "BR" | "CH" /*… */; professionalRole?: "GENERAL_DOCTOR" | "SPECIALIST_DOCTOR" | "RESIDENT" | "MEDICAL_STUDENT" | "PHARMACIST" | "BIOCHEMIST" | "PHYSIOTHERAPIST" | "DIAGNOSTIC_TECHNICIAN" | "OTHER_HEALTH_PROFESSIONAL"; };

Instalación

Desde npm / Yarn (ESM)

Para proyectos basados en Node (React, Vue, Svelte, Next.js, etc.):

# Con npm
npm install zentis-widget

# Con Yarn
yarn add zentis-widget

El paquete exporta el Web Component para que, en tu código, puedas importarlo con import "zentis-widget";
Si el paquete incluye un componente React nativo (por ejemplo, export default function ZentisChatWidget(props) { ... }), úsalo directamente como componente React.

Desde CDN (UMD)

Si quieres usarlo en HTML estático, Razor o PHP clásico, sin bundler:

<!-- Versión UMD con CSS inyectado: -->
<script src="https://unpkg.com/zentis-widget@latest/dist/zentis-widget.umd.js"></script>

O, tras compilar localmente (npm run build), copia dist/zentis-widget.umd.js a tu carpeta pública (por ejemplo, wwwroot/dist/ o public/js/) y referencia:

<script src="/dist/zentis-widget.umd.js"></script>

Uso en HTML (Vanilla JavaScript)

Inserción del Custom Element

En tu HTML, simplemente coloca la etiqueta —aunque no basta con eso: luego debes inicializarlo via JS.

<!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Demo Zentis Widget</title>

    <!-- Carga UMD desde CDN o carpeta local -->
    <script src="https://unpkg.com/zentis-widget@latest/dist/zentis-widget.umd.js"></script>
  </head>
  <body>
    <h1>Bienvenido a Zentis Chat</h1>

    <!-- Aquí va el Web Component -->
    <zentis-widget id="zentis"></zentis-widget>

    <!-- Inicialización via JavaScript -->
    <script>
      document.addEventListener("DOMContentLoaded", () => {
        const widget = document.getElementById("zentis");

        // 1) Llamar a init() con apiKey y endpoint (requeridos)
        widget.init({
          apiKey: "TU_JWT_TOKEN_AQUÍ",                       // apiKey (string)
          endpoint: "https://api.tu-dominio.com/zentis",     // endpoint (string)
          metadata: { name: "12345", email: "admin" },       // metadata (opcional: objeto)
          accountId: "MI_ACCOUNT_ID"  }                      // accountId (opcional: string)
        );

        // 2) Escuchar eventos
        widget.addEventListener("chat-initialized", (e) => {
          console.log("Chat inicializado:", e.detail);
        });
        widget.addEventListener("endpoint-changed", (e) => {
          console.log("Endpoint actualizado:", e.detail);
        });
      });
    </script>
  </body>
</html>

Importante:
El componente no lee atributos HTML por defecto.
Siempre debes llamar a init({apiKey, endpoint, metadata?, accountId?}) para que comience a renderizar.
Si cambias cualquiera de las propiedades (.apiKey, .endpoint, .metadata, .accountId) en tiempo de ejecución, el componente se re-renderizará automáticamente.

Eventos Disponibles

| Evento | event.detail | Cuándo se emite | | -------------------- | ------------------------------------------------------------ | -------------------------------------------------------- | | chat-initialized | { apiKey, endpoint, metadata, accountId } | Al completar init(...) con apiKey y endpoint válidos. |

Ejemplo de escucha:

const widget = document.querySelector("zentis-widget");
widget.addEventListener("chat-initialized", (e) => {
  console.log("API Key cambió a:", e.detail);
});

Uso en React (ESM)

Si instalaste el paquete desde npm/Yarn, puedes usar el Web Component dentro de React, o bien si el paquete exporta también un componente React “puro” (revisa package.json).

1. Importar el Web Component

npm install zentis-widget
# o
yarn add zentis-widget

En tu punto de entrada de React (por ejemplo src/main.tsx o src/index.tsx), registra el Web Component así:

import React from "react";
import { createRoot } from "react-dom/client";

// Esto registra el Web Component <zentis-widget> en el DOM
import "zentis-widget/dist/zentis-widget.esm.js";
// O, si el paquete ESM expone directamente: import "zentis-widget";
import App from "./App";

const root = createRoot(document.getElementById("root")!);
root.render(<App />);

2. Usar el Web Component en un Componente React

// src/App.tsx
import React, { useEffect, useRef } from "react";

function App() {
  const widgetRef = useRef(null);

  useEffect(() => {
    if (!widgetRef.current) return;

    // 1) Llamamos a init() cuando el componente se monte
    widget.init({
          apiKey: "TU_JWT_TOKEN_AQUÍ",                       // apiKey (string)
          endpoint: "https://api.tu-dominio.com/zentis",     // endpoint (string)
          metadata: { name: "12345", email: "admin" },       // metadata (opcional: objeto)
          accountId: "MI_ACCOUNT_ID"  }                      // accountId (opcional: string)
        );

    // 2) Escuchar evento de inicialización
    widgetRef.current.addEventListener(
      "chat-initialized",
      (e) => {
        console.log("Chat iniciado (React):", e.detail);
      }
    );
  }, []);

  return (
    <div>
      <h1>Mi App en React</h1>
      {/* Renderiza el web component referenciado */}
      <zentis-widget ref={widgetRef}></zentis-widget>
    </div>
  );
}

export default App;

Uso en .NET Core (Razor)

1. Copia el bundle UMD

2. Edita `_Layout.cshtml`

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="utf-8" />
    <title>@ViewData["Title"] - Mi Aplicación</title>
    <link rel="stylesheet" href="~/css/site.css" />
</head>
<body>
    <div class="container">
        @RenderBody()
    </div>

    <!-- Cargar Web Component UMD al final del body -->
<script src="https://unpkg.com/zentis-widget@latest/dist/zentis-widget.umd.js"></script> 
// o apuntando a donde lo tengas localmente (<script src="~/dist/zentis-widget.umd.js"></script>)

    @RenderSection("Scripts", required: false)
</body>
</html>

3. En tu Vista Razor específica (por ejemplo, `Chat.cshtml`)

@{
    ViewData["Title"] = "Zentis Chat";
}
<h2>Integración con Zentis Chat</h2>

<!-- Web Component sin configuración adicional aquí -->
<zentis-widget id="zentis"></zentis-widget>

@section Scripts {
  <script>
    document.addEventListener("DOMContentLoaded", () => {
      var widget = document.getElementById("zentis");

      // Inicializar el widget
     widget.init({
          apiKey: "TU_JWT_TOKEN_AQUÍ",                       // apiKey (string)
          endpoint: "https://api.tu-dominio.com/zentis",     // endpoint (string)
          metadata: { name: "12345", email: "admin" },       // metadata (opcional: objeto)
          accountId: "MI_ACCOUNT_ID"  }                      // accountId (opcional: string)
        );

      // Opcional: escuchar eventos
      widget.addEventListener("chat-initialized", (e) => {
        console.log("Chat inicializado (.NET Razor):", e.detail);
      });
    });
  </script>
}

Uso en PHP con Smarty Templates

Para proyectos PHP que usan Smarty como motor de plantillas, sigue estos pasos:

Estructura de Archivos de Ejemplo

/project-root
  /templates
    header.tpl
    chat.tpl
  /templates_c
  /configs
  index.php

templates/header.tpl / footer.tpl: Cabecera y pie comunes de Smarty.
templates/chat.tpl: Plantilla específica para el chat.
index.php: Controlador que inicializa Smarty y asigna variables.

1. Configurar Smarty en `index.php`

<?php
require 'libs/Smarty.class.php';

$smarty = new Smarty();

// Ajusta rutas según tu proyecto
$smarty->setTemplateDir(__DIR__ . '/templates');
$smarty->setCompileDir(__DIR__ . '/templates_c');
$smarty->set
setConfigDir(__DIR__ . '/configs');
$smarty->setCacheDir(__DIR__ . '/cache');

// Variables para el widget
$smarty->assign('apiKey', 'TU_JWT_TOKEN_AQUÍ');
$smarty->assign('endpoint', 'https://api.tu-dominio.com/zentis');
$smarty->assign('accountId', 'MI_ACCOUNT_ID');
 $this->smartyv3->assign('metadata', [
            'name'  => "555",
            'email' => "[email protected]"
            ...
        ]);

// Renderizar la plantilla chat.tpl
$smarty->display('chat.tpl');

2. Plantilla `templates/header.tpl`

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="UTF-8">
  <title>Zentis Chat con Smarty</title>
  {literal}
  <!-- Carga UMD Web Component -->
<script src="https://unpkg.com/zentis-widget@latest/dist/zentis-widget.umd.js"></script> 
  {/literal}
</head>
<body>
  <header>
    <h1>Mi Sitio</h1>
  </header>

3. Plantilla `templates/chat.tpl`

{include file='header.tpl'}

{block name="content"}
  <h2>Chat Zentis Integrado con Smarty</h2>


  <zentis-widget id="zentisChat"></zentis-widget>

  <div style="margin-top: 1rem;">
    <button id="btnInitChat" style="padding: 0.5rem 1rem; font-size: 1rem;">
      Iniciar Chat
    </button>
  </div>

<script>
    document.addEventListener("DOMContentLoaded", function() {
      const chatEl    = document.getElementById("zentisChat");
      const btnIniciar = document.getElementById("btnInitChat");

      const apiKey    = "{$apiKey}";
      const endpoint  = "{$endpoint}";
      const accountId = "{$accountId}";

      const metadata = {$metadata|json_encode nofilter};

      function iniciarChat() {
        chatEl.init({
          apiKey: apiKey,
          endpoint: endpoint,
          metadata: metadata,
          accountId: accountId
        });

        btnIniciar.disabled    = true;
        btnIniciar.textContent = "Chat iniciado";
      }

      btnIniciar.addEventListener("click", iniciarChat);
    });
  </script>

{/block}

API del Web Component

Estos son los miembros públicos del web component ZentisWebComponent:

Propiedades (setters)

widget.apiKey = valor: string obligatorio
- Asigna el JWT.
- Dispara api-key-changed.
- Relanza renderIfInitialized().
widget.endpoint = valor: string obligatorio
- Asigna la URL del backend.
- Dispara endpoint-changed.
- Relanza renderIfInitialized().
widget.metadata = valor: Metadata opcional
- Asigna datos adicionales (objeto).
- Dispara metadata-changed.
- Relanza renderIfInitialized().
widget.accountId = valor: string opcional
- Asigna el identificador de cuenta.
- Dispara account-id-changed.
- Relanza renderIfInitialized().

Métodos públicos

widget.init(apiKey: string, endpoint: string, metadata?: any, accountId?: string): void
- Inicializa (o re-inicializa) el componente con los valores indicados.
- Asigna internamente _apiKey, _endpoint, _metadata y _accountId.
- Llama a renderIfInitialized().
- Dispara el evento chat-initialized con detalle { apiKey, endpoint, metadata, accountId }.
- Debe llamarse una vez que el elemento esté conectado al DOM (por ejemplo, en DOMContentLoaded o en montajes de React/Razor/Smarty).

Ciclo de vida

connectedCallback()
- Cuando el elemento se inserta en el DOM, crea el root React con createRoot(this).
- (No renderiza nada hasta que se llame a init() o se asigne apiKey y endpoint).
disconnectedCallback()
- Al remover el elemento del DOM, desmonta el root React (libera memoria).

Resumen de Uso Rápido

HTML estático / Vanilla JS:
1. Incluye <script src="zentis-widget.umd.js">.
2. Coloca <zentis-widget id="zentis"></zentis-widget>.
3. En JS, llama a widget.init({apiKey, endpoint, metadata?, accountId?}).
4. Escucha eventos si lo necesitas.
React (ESM):
1. npm install zentis-widget.
2. import "zentis-widget"; (registra el Web Component).
3. Dentro de un componente React, renderiza <zentis-widget ref={ref} /> y llama a ref.current.init(...) en useEffect.
.NET Core (Razor):
1. Copia zentis-widget.umd.js a wwwroot/dist/.
2. En _Layout.cshtml, incluye <script src="~/dist/zentis-widget.umd.js"></script>.
3. En tu vista, pon <zentis-widget id="zentis"></zentis-widget> y llama a init(...) dentro de <script> en la sección @section Scripts.
- PHP + Smarty:
1. Copia zentis-widget.umd.js a public/js/.
2. En header.tpl, pon <script src="https://unpkg.com/zentis-widget@latest/dist/zentis-widget.umd.js"></script>.
3. En chat.tpl, inserta <zentis-widget id="zentis"></zentis-widget>.
4. En chat.tpl, llama a widget.init({apiKey, endpoint, metadata, accountId}) usando variables Smarty con {$apiKey}, {$endpoint}, {$metadata}, {$accountId}.

Con este README ya tienes todo lo necesario para instalar, configurar y usar tu Web Component zentis-widget en distintos entornos: Vanilla JS, React, .NET Core Razor y PHP con Smarty. ¡Disfruta integrando el chat Zentis en tu proyecto!