Skip to content

Widget

Jump to bottom
willykeynua edited this page Oct 10, 2024 · 21 revisions

Widget

El widget de firma de Keynua (en adelante Widget) es la manera de firmar contratos y este puede ser incrustado en cualquier sitio Web.

¿Cómo incrustar el Widget de firma?

El script

Lo primero que debes hacer es agregar el Widget <header> tag de tu sitio web teniendo en cuenta el ambiente que se usará:

URL PROD: https://sign.keynua.com
URL STG: https://sign.stg.keynua.com

Ejemplo para PROD:

<header>
  <script src="https://sign.keynua.com/widgets/widget.js"></script>
</header>

El token de firma

Un dato muy importante para poder realizar la firma es el token, este le pertenece al usuario que va a realizar la firma usando el Widget, este token se genera al momento de crear el Contrato o Identificación. Al crear un contrato, obtendrás el token de cada usuario dentro del campo "users". Al crear una identificación, obtendrás el token en el campo "userToken".

El token debe ser colocado dentro de una etiqueta <div> en la propiedad data-token y la clase keynua-widget.

Ejemplo:

<body>
  <div class="keynua-widget" data-token="***TOKEN***"></div>
</body>

Ejecutar el Widget

Como paso final es necesario ejecutar el Widget para que este pueda funcionar con el token proporcionado, como se muestra en el siguiente ejemplo.

Ejemplo:

<script>
  window.Keynua.run();
</script>

Opciones (options) del Widget

Adicionalmente puedes pasarle una serie de parámetros a la función Keynua.run() para usos más avanzados, ten en cuenta que al hacerlo de esta manera deberas indicar siempre el token de firma.

token (requerido):

El token de firma del usuario generado al momento de crear el contrato.

Ejemplo:

<div class="keynua-widget"></div>

<script>
  window.Keynua.run({
    token: "***TOKEN***"
  });
</script>

widgetContainer (opcional):

Keynua proporciona una clase llamada keynua-widget, este muestra al Widget ocupando todo el espacio disponible, si deseas, puedes reemplazarlo y deberás indicar la nueva clase en las opciones.

Ejemplo:

<div class="mi-widget"></div>

<script>
  window.Keynua.run({
    token: "***TOKEN***",
    widgetContainer: "mi-widget"
  });
</script>

widgetContainerId (opcional):

Otra forma de indicar el elemento html donde se debe renderizar el Widget de Keynua es pasando el id del elemento.

Ejemplo:

<div id="the-widget"></div>

<script>
  window.Keynua.run({
    token: "***TOKEN***",
    widgetContainerId: "the-widget"
  });
</script>

uiCallback (opcional):

Adicionalmente puedes agregar una función ejecutable que se llama para distintos eventos generados por el widget. Ejemplo:

<div class="mi-widget"></div>

<script>
  window.Keynua.run({
    token: "***TOKEN***",
    uiCallback: (ev) => console.log(ev)
  });
</script>

autoRefresh (opcional):

Valor numérico en segundos que podrás enviar para que el flujo de firma busque actualizaciones y refresque la vista. El valor mínimo posible es 30.

Ejemplo:

<div class="mi-widget"></div>

<script>
  window.Keynua.run({
    token: "***TOKEN***",
    autoRefresh: 30
  });
</script>

Es importante que por cada archivo se devuelva el header content-type correcto.

Eventos

Todos los eventos que se envían a la función proporcionada en uiCallback extienden de la siguiente estructura:

Atributo Tipo Descripcion
name string El nombre del evento
url string El url actual desde donde se está ejecutando el widget
sessionId string El id de la sesión
timestamp string La fecha de emisión del evento en formato ISO
contractId string El identificador del contrato de Keynua al que hace referencia
userId number El identificador interno de Keynua del usuario dentro del contrato
templateId string El identificador del proceso utilizado para el contrato

Los tipos de eventos pueden ser identificados por el atributo name y son los siguientes (todos los eventos extienden de la estructura base y solo se definen los atributos adicionales):

ViewsLoadedEvent

Cuando se cargaron las vistas a mostrar.

Atributo Tipo Descripcion
views View[] Un arreglo de las vistas a mostrar

ViewDisplayedEvent

Cuando se muestra una vista específica.

Atributo Tipo Descripcion
view View La vista que se está mostrando

ViewValueSetEvent

Cuando se asigna un valor a una vista.

Atributo Tipo Descripcion
view View La vista a la cual se le ha asignado el valor

ViewsFailedEvent

Cuando no fue posible obtener las vistas a mostrar.

Atributo Tipo Descripcion
error Error El error generado

SubmitStartedEvent

Cuando se está por enviar los datos al servidor de Keynua.

Atributo Tipo Descripcion
bytesTotal number El total en bytes que fueron enviados

SubmitFinishedEvent

Cuando se enviaron todos los datos de las vistas actuales al servidor de Keynua.

Atributo Tipo Descripcion
bytesTotal number El total en bytes que fueron enviados

SubmitFailedEvent

Cuando no fue posible enviar los datos al servidor de Keynua.

Atributo Tipo Descripcion
error Error El error generado
bytesTotal number El total en bytes que se debía enviar
percent number El porcentaje hasta el que llegó el envío

DetailsLoadedEvent

Cuando se cargó el detalle del contrato.

DetailsFailedEvent

Cuando no fue posible obtener el detalle del contrato.

Atributo Tipo Descripcion
error Error El error generado

ItemErrorsEvent

Cuando el contrato cargado presenta errores.

Atributo Tipo Descripcion
itemErrors array Lista de errores del contrato
itemErrors[*].itemId string Id del item que dió el error
itemErrors[*].itemType string Tipo del item que dió el error
itemErrors[*].code string Código del error
itemErrors[*].message string Descripción del error
itemErrors[*].data objeto (opcional) Detalle adicional del error

El evento es lanzado sólo para los siguientes códigos de error:

  • InvalidInstructionGrade cuando el firmante es iletrado según reniec.
  • InvalidVerificationDigit cuando el firmante ingresa un dígito de verificación incorrecto.

Estructuras adicionales

Se definen algunas estructuras adicionales que son enviadas en los eventos:

View

Atributo Tipo Descripcion
id string El identificador de la vista
type string El tipo de vista. Puede ser info o input
input null/Input Cuando la vista es de tipo input se enviará un objeto de tipo Input

Input

Atributo Tipo Descripcion
id number El identificador del input
refId string El identificador utilizado por el proceso
type string El tipo de elemento definido en el proceso
version number La versión del input
userId number/null El identificador del usuario al que le pertenece el input
value any El valor actual de la vista

Personalizar el diseño del Widget

El atributo theme en los options del widget

Con este atributo puedes hacer modificaciones del diseño de las vistas usando propiedades CSS en camelCase. Por ejemplo la propiedad CSS background-color ahora se colorcaría backgroundColor.

<div class="mi-widget"></div>
<script>
  window.Keynua.run({
		token: "***TOKEN***",
		theme: {
			bgDark: {
				// Aquí personalizas las propiedades de bgDark usando reglas CSS
				backgroundColor: "black",
			}
		}
  });
</script>

Existen muchos atributos para muchos aspectos de como se visualiza el widget, aquí mencionaremos las principales:

  • bgDark: Estilo usado en vistas con fondo oscuro, por ejemplo la vista de aceptación de términos y condiciones o la vista de proceso finalizado.
  • card: Usado en los elementos de documentos.
  • placeholderEmpty: Antes de tomar una fotografía se muestra una imagen, a esta imagen se le conoce como placeholderEmpty, aquí podrás cambiar esa imagen.
  • placeholderVideoEmpty: Posee un comportamiento similar a placeholderEmpty solo que este es previo a capturar un video.
  • paragraph: Modifica el estilo del texto simple a lo largo de todo el widget.
  • h1, h2, h3, h4, h5, h6: Modifica el estilo del texto de los encabezados HTML a lo largo de todo el widget.
  • btn: El botón por diseño por defecto.
  • btnPrimary: Diseño del botón primario de Keynua.
  • btnSecondary: Diseño del botón secundario de Keynua.
  • btnPlain: Diseño del botón plano de Keynua.
  • btnDisabled: Diseño del botón deshabilitado de Keynua.
  • colorPrimary: Modifica el diseño de los textos de color primario en el widget.
  • colorSecondary: Modifica el diseño de los textos de color secundario en el widget.
  • colorError: Modifica el diseño de los textos de color para casos de error en el widget.
  • inputText: Modifica el diseño de los input de tipo texto en el widget.
  • shortCodeEven: Cambia el estilo de los números pares del shortcode.
  • shortCodeOdd: Cambia el estilo de los números impares del shortcode.

Listado de errores

Aquí una lista de los errores que pueden verse al momento de incrustar el Widget:

  • Component does not have a token: Este error se muestra cuando el Widget no ha podido encontrar el atributo token dentro de las opciones al momento de llamar a Keynua.run().
  • 403 - Forbidden: Este error sucede cuando el atributo data-token contiene un token inválido.
  • Pantalla en blanco (white screen): Algunas veces puede suceder que al momento de ejecutar el Widget no logres visualizarlo, esto puede pasar principalmente porque no es posible obtener el contenedor del Widget widgetContainer.
  • error when trying to upload the value: Este error indica que no ha podido culminar el proceso de firma debido a que no ha podido subir los archivos como las fotografías y videos, esto puede ser provocado principalmente por una conexión inestable a internet.
  • Congelado y sin errores: Si el widget está congelado, es decir, no cambia la pantalla de carga o no funciona al hacer clic y no hay algún error visual o en la consola, es porque React ha dejado de supervisar el componente. Esto sucede al eliminar el contenedor del widget en el HTML y volverlo a poner. Adicionalmente, puede ocurrir si ejecuta el Keynua.run del lado servidor y no en el navegador del cliente.

Volver arriba

  1. API Reference
  2. Authentication
  3. Errors
  4. Contracts
  5. Contract Items
  6. Widget

Clone this wiki locally