Captura consentimientos

Captura consentimientos

Solicitar y obtener el consentimiento es el primer paso del ciclo de vida del consentimiento. En esta guía, te explicaremos cómo capturar el consentimiento de tus usuarios usando el SDK de Soyio.

Flujo de captura de consentimiento

1. Se muestra el componente de consentimiento al usuario en un formulario o sección de tu interfaz
2. El usuario revisa y acepta los términos mediante un checkbox opt-in.
3. Se genera un token de acción (action token) cada vez que el usuario haga click en un checkbox de consentimiento
4. Al momento de persistir los datos del usuario, envías uno o varios token de acción para crear un registro de consentimientos con evidencia del proceso.
5. En base a estas acciones de consentimiento, el sistema automáticamente crea o actualiza los Agreements para el usuario. El Agreement es la fuente de verdad que determina las finalidades de tratamiento autorizadas en tu empresa en tiempo real.

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Los Agreements pueden cambiar a lo largo del tiempo debido a nuevas acciones de consentimiento, modificaciones o revocaciones. Por eso, siempre es recomendable consultar el Agreement actual o el ComplianceStatus correspondiente antes de utilizar un dato para una finalidad específica. Revisa la guía de consulta de consentimiento para más información.

Obtén el token de la acción del usuario

El token de acción (action token) es el identificador único de la interacción de un usuario. El token es necesario para registrar la acción de consentimiento y su evidencia. Para obtener un token, debes tener una plantilla de consentimiento. Revisa la guía de creación de plantilla de consentimiento para más información.

Puedes obtener el token de acción de tres maneras:

1. Usa el SDK y escucha el evento del componente
2. Usa el SDK y usa la función getStatus del componente
3. Usa la API de Soyio directamente para crear el token de acción

Opción 1: Usa el SDK y escucha el evento del componente

Despliega el componente de captura de consentimiento usando el SDK de Soyio y una plantilla de consentimiento.

Captura el evento CONSENT_CHECKBOX_CHANGE que emite el componente del SDK de Soyio cuando el usuario hace clic en el checkbox de consentimiento. Este evento contiene el token de acción.

Usa este método para casos donde necesitas registrar el consentimiento en el momento de interacción del usuario. Por ejemplo, cuando estás solicitando el consentimiento para una finalidad adicional para datos que ya tienes en tu sistema.

Si tu plantilla tiene múltiples alcances (por ejemplo, productos o sucursales) y quieres que el usuario seleccione cuáles autoriza, revisa la configuración en la guía de Personalización.

Importante: Persistencia de "Última Intención"

Ten en cuenta que cada interacción del usuario con un checkbox genera un nuevo actionToken que representa ese estado específico. Debes siempre persistir el último actionToken generado, ya que este representa la última intención o decisión confirmada del usuario.

SDK Web

const consentBox = new ConsentBox(consentOptions);
consentBox.on('CONSENT_CHECKBOX_CHANGE', (data) => {
    console.log(data);
});

Respuesta

{
    eventName: 'CONSENT_CHECKBOX_CHANGE',
    isSelected: boolean,
    actionToken: string
}

SDK Mobile

<ConsentBox
    options={options}
    params={params}
    onEvent={(event) => {
        if (event.type === 'CONSENT_CHECKBOX_CHANGE') {
            console.log(event);
        }
    }}
/>

Respuesta

{
    type: 'CONSENT_CHECKBOX_CHANGE',
    isSelected: boolean,
    actionToken: string
}

Opción 2: Consulta el estado del componente (getStatus / getState)

Usa la función getStatus del componente del SDK de Soyio para obtener el estado del checkbox. Este método es útil para casos donde necesitas registrar el consentimiento en el momento de persistir los datos del usuario. Por ejemplo, cuando el usuario hace submit de un formulario de registro.

SDK Web

Consulta el estado del checkbox

const consentBox = new ConsentBox(consentOptions);
const status = consentBox.getStatus();
console.log(status);

Respuesta

{
    isSelected: boolean,
    actionToken: string | undefined
}

SDK Mobile

Consulta el estado del checkbox

// Usa una referencia al componente para obtener su estado actual
const consentRef = useRef<ConsentBoxRef>(null);

// ...

<ConsentBox
    ref={consentRef}
    options={options}
    params={params}
/>

// ...

const stateInfo = consentRef.current?.getState();
console.log(stateInfo);

Respuesta

{
    isSelected: boolean,
    actionToken: string | null
}

Opción 3: Usa la API de Soyio directamente

⭐

Disponible como add-on

Esta funcionalidad está disponible como add-on en ciertos planes. Consulta por los planes completando el siguiente formulario.

Si no puedes utilizar el SDK de Soyio, utiliza el módulo de consentimiento a través de la API de Soyio. Esta forma es ideal cuando quieres implementar tu propia interfaz de consentimiento o integrar Soyio a sistemas que tienen sus propias interfaces. Revisa la guía de integración sin SDK para más información.

Registra el consentimiento

El registro de la acción de consentimiento es el paso final para capturar el consentimiento de tus usuarios, ya que con esto persistes la evidencia de la acción en Soyio. Este paso lo realizarás desde tu backend usando la API de Soyio.

Puedes hacer el registro de la acción de consentimiento de dos maneras:

1. Crea una acción de consentimiento (ConsentAction)
2. Crea un commit de varios consentimientos (ConsentCommit)

El action_token es un JWT, por lo que puede confundirse con el API Key de Soyio. El action_token debe ir en el cuerpo de la solicitud, no en el header.

Opción 1: Crea una acción de consentimiento (ConsentAction)

Crea una acción de consentimiento (ConsentAction) mediante el endpoint de creación de acción de consentimiento.

Proporciona el action_token que obtuviste en el paso anterior. Tanto el entity_id como el user_reference son opcionales.

• Incluye el entity_id si ya tienes un identificador de entidad de Soyio asociado a un usuario en tu sistema, esto permite que este nuevo consentimiento se asocie a la entidad existente. Si es el primer consentimiento otorgado por un usuario, no proporciones un entity_id, se creará una nueva entidad en Soyio y se retornará el entity_id. El entity_id te permitirá consultar el estado de todos los consentimientos de un usuario.

• El user_reference es útil para conciliar los datos de tu usuario con los consentimientos en Soyio, sin embargo, no reemplaza al entity_id.

POST /api/v1/consent_actions

{
    "action_token": "<action_token>",
    "entity_id": "<id_del_usuario_en_soyio>", // Opcional
    "user_reference": "<identificador_usuario>" // Opcional
}

Para revisar validaciones y respuestas del endpoint, consulta Crear un consent action.

Opción 2: Crea un commit de varios consentimientos (ConsentCommit)

Crea un commit de varios consentimientos (ConsentCommit) mediante el endpoint de creación de commit de consentimientos.

Proporciona los action_tokens que obtuviste en el paso anterior. Tanto el entity_id como el user_reference son opcionales.

• Incluye el entity_id si ya tienes un identificador de entidad de Soyio asociado a un usuario en tu sistema, esto permite que estos nuevos consentimientos se asocien a la entidad existente. Si es el primer consentimiento otorgado por un usuario, no proporciones un entity_id, se creará una nueva entidad en Soyio y se retornará el entity_id. El entity_id te permitirá consultar el estado de todos los consentimientos de un usuario.

• El user_reference es útil para conciliar los datos de tu usuario con los consentimientos en Soyio, sin embargo, no reemplaza al entity_id.

Un ConsentCommit puede procesar acciones mixtas de otorgamiento (grant) y revocación (revoke) en una sola llamada. Esto es ideal para escenarios como la actualización de preferencias en un portal de privacidad, ya que genera una única versión del acuerdo del usuario (Agreement) y una sola evidencia, simplificando el historial de consentimientos.

POST /api/v1/consent_commits

{
    "user_reference": "<identificador_usuario>", // Opcional
    "entity_id": "<id_del_usuario_en_soyio>", // Opcional
    "consent_actions": [
        {
            "action_token": "<action_token_1>"
        },
        {
            "action_token": "<action_token_2>"
        }
    ]
}

Si quieres profundizar en este flujo, revisa Crear un commit de consentimiento.

Flujo del Consent Commit

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Próximos pasos

• Consulta los consentimientos - Consulta el consentimiento de tus usuarios
• Plantillas de consentimiento - Crea plantillas de consentimiento para tus aplicaciones
• Personalización - Personaliza el componente de consentimiento
• Gestión de consentimientos - Habilita un portal para que tus usuarios gestionen y revoquen su consentimiento