Rilevamento della vitalità: avvisi e codici di errore

Panoramica

Gli avvisi nel report di rilevamento della vitalità segnalano ogni condizione rilevata da Didit durante l’esecuzione del controllo di vitalità. Vengono inseriti nell’array warnings[] di ogni elemento di liveness_checks[] (vedi Report di rilevamento della vitalità), con feature impostato su "LIVENESS". Ogni voce segue la struttura condivisa dell’oggetto avviso: feature, risk, additional_data, log_type, short_description, long_description, node_id. Ogni avviso è composto da tre livelli:

Il codice risk — un identificatore stabile che puoi verificare nel tuo codice (i codici sono elencati di seguito).
Il log_type — uno tra information, warning o error. I rischi di rifiuto automatico presentano sempre error. Per i rischi configurabili viene ricavato dall’azione configurata: Nessuna azione → information, Revisione → warning, Rifiuta → error. Per i rischi basati su soglie (LOW_LIVENESS_SCORE, LOW_FACE_QUALITY) è error quando il valore raggiunge o scende al di sotto della soglia di rifiuto e warning quando raggiunge o scende al di sotto solo della soglia di revisione.
L’impatto sulla decisione — lo stesso routing determina lo status del report di rilevamento della vitalità: un’azione Revisione lo sposta su In Review, un’azione Rifiuta (o qualsiasi rischio di rifiuto automatico) su Declined, mentre Nessuna azione lo lascia invariato.

Alcuni rischi vengono emessi solo quando il metodo di rilevamento della vitalità è PASSIVE (controlli su volti multipli, qualità e luminanza). Le tabelle seguenti elencano la serie completa di codici di rischio di vitalità e i relativi livelli di gravità — non esistono altri codici di rischio per la vitalità.

Condizioni di rifiuto automatico

I seguenti rischi impostano sempre il report di rilevamento della vitalità (e la sessione) su Declined, con log_type: "error":

Risk	Trigger
`NO_FACE_DETECTED`	Nessun volto individuato durante l’acquisizione della vitalità, oppure l’utente ha esaurito i tentativi disponibili.
`LIVENESS_FACE_ATTACK`	Il modello ha rilevato un attacco di presentazione (maschera, riproduzione su schermo, spoofing di tipo deepfake).
`FACE_IN_BLOCKLIST`	Il volto corrisponde a una voce presente nella blocklist dei volti della tua applicazione.
`AGE_BELOW_MINIMUM`	Età stimata inferiore al minimo configurato. Emesso solo nei workflow di verifica dell’età adattivi e nei nodi `AGE_ESTIMATION`.
`AGE_NOT_DETECTED`	Impossibile stimare l’età. Emesso solo nei flussi di stima dell’età con fallback alla verifica dell’identità disabilitato.

Quando si attiva NO_FACE_DETECTED, LOW_LIVENESS_SCORE viene soppresso (non c’è alcun volto a cui assegnare un punteggio).

Impostazioni di verifica configurabili

Nella console Didit, i rischi di vitalità sono raggruppati nelle seguenti impostazioni del workflow:

Gruppo	Rischi	Configurazione
Soglie del punteggio di vitalità	`LOW_LIVENESS_SCORE`	Soglia di revisione + soglia di rifiuto su `score`. Pari o inferiore alla soglia di revisione → `In Review`; pari o inferiore alla soglia di rifiuto → `Declined`.
Azione per volto duplicato	`DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE`	Un’unica impostazione condivisa: Nessuna azione (predefinita) / Revisione / Rifiuta. I rischi vengono completamente ignorati quando il volto corrispondente si trova nella tua allowlist dei volti.
Mancata corrispondenza dell’identità per volto duplicato	`DUPLICATED_FACE_NAME_MISMATCH`	Impostazione dedicata (`face_liveness_duplicated_face_name_mismatch_action`): Nessuna azione / Revisione (predefinita) / Rifiuta. Valutata solo quando si attiva anche `DUPLICATED_FACE` — vedi sotto.
Confronto facciale con attacco alla vitalità	`FACE_MATCHES_LIVENESS_ATTACK`	Impostazione dedicata (`face_liveness_attack_face_match_action`): Nessuna azione (predefinita) / Revisione. L’impostazione Rifiuta qui viene accettata ma applicata come Revisione. Disponibile anche nel nodo Stima dell’età.
Possibile volto in blocklist	`POSSIBLE_FACE_IN_BLOCKLIST`	Non configurabile nei workflow — instradato sempre a Revisione (`log_type: "warning"`).
Azione per volti multipli (solo in modalità passiva)	`MULTIPLE_FACES_DETECTED`	Nessuna azione (predefinita) / Revisione / Rifiuta.
Soglie di qualità del volto (solo in modalità passiva)	`LOW_FACE_QUALITY`	Soglia di revisione (predefinita a 15) + soglia di rifiuto (predefinita a 0, ossia rifiuto disabilitato).
Luminanza del volto (solo in modalità passiva)	`LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`	Soglie minima / massima (predefinite a 20 / 80 sulla scala normalizzata 0–100) + un’azione per direzione (predefinita a Revisione).
Soglie di età (workflow adattivi / nodo `AGE_ESTIMATION`)	`AGE_BELOW_MINIMUM`, `AGE_NOT_DETECTED`	Soglie di età minima e borderline; entrambi i rischi comportano il rifiuto automatico del passaggio di rilevamento della vitalità. Con il fallback alla verifica dell’identità abilitato, il workflow indirizza l’utente a un controllo del documento invece di terminare la sessione.

Avvisi generati

Vitalità principale

Rischio	Causa	Gravità	Influisce sullo stato?	Rimedio
`NO_FACE_DETECTED`	Nessun volto individuato durante l’acquisizione, oppure l’utente ha esaurito i tentativi disponibili (`MAX_ATTEMPTS_REACHED`).	`error`	Rifiuto automatico	Ripeti l’acquisizione con un’illuminazione migliore; assicurati che il volto sia centrato.
`LIVENESS_FACE_ATTACK`	Il modello ha rilevato un attacco di presentazione.	`error`	Rifiuto automatico	Consideralo una frode. La sessione viene rifiutata automaticamente.
`LOW_LIVENESS_SCORE`	`score` pari o inferiore alla soglia di revisione del workflow. Soppresso quando è presente anche `NO_FACE_DETECTED`.	`warning`; passa a `error` quando il punteggio è pari o inferiore alla soglia di rifiuto	Configurabile (soglie di revisione / rifiuto)	Ripeti l’acquisizione; regola le soglie se osservi falsi positivi.

Integrità del canale di acquisizione

Segnali di attacco di iniezione segnalati dal client al momento dell’acquisizione. A differenza degli attacchi di presentazione (un artefatto posto davanti a una fotocamera reale), questi descrivono la sostituzione o l’intercettazione del feed della fotocamera stesso. Ciascuno è configurabile per workflow e l’impostazione predefinita è nessuna azione, quindi l’abilitazione della funzionalità non modifica alcuna decisione finché non attivi esplicitamente la funzionalità.

Rischio	Causa	Chiave di configurazione	Predefinito
`VIRTUAL_CAMERA_DETECTED`	Il dispositivo di acquisizione è stato identificato come una fotocamera virtuale software (OBS, ManyCam, Snap Camera, DroidCam e simili) anziché una fotocamera fisica.	`virtual_camera_action`	`NO_ACTION`
`EXTERNAL_CAPTURE_DEVICE_DETECTED`	Il dispositivo di acquisizione era una fotocamera esterna o una scheda di acquisizione anziché una fotocamera integrata.	`external_capture_device_action`	`NO_ACTION`
`FRAME_INJECTION_SUSPECTED`	I fotogrammi acquisiti mostrano indicatori di composizione software o di iniezione nella pipeline della fotocamera anziché una reale acquisizione dal vivo, o l’acquisizione è stata eseguita su hardware emulato o virtualizzato (un emulatore Android o una macchina virtuale desktop), dove non esiste alcun sensore fisico della fotocamera e ogni fotogramma viene fornito dall’host.	`frame_injection_action`	`NO_ACTION`
`INJECTION_ATTACK_DETECTED`	L’acquisizione è stata iniettata anziché ripresa dalla fotocamera del dispositivo stesso: una fotocamera virtuale software, un feed della fotocamera generato dalla pagina o dall’automazione del browser, una fotocamera sottoposta a hooking o uno strumento di instrumentazione collegato all’app. `additional_data.reasons` elenca solo i motivi che lo dimostrano. I segnali che una persona reale può produrre non lo attivano mai. Per la vitalità e il confronto facciale segue `frame_injection_action`, quindi le decisioni relative ai selfie non cambiano.	`frame_injection_action`	`NO_ACTION`
`SCREEN_CAPTURE_DURING_CAPTURE`	La registrazione dello schermo o la condivisione dello schermo era attiva sul dispositivo durante l’acquisizione biometrica.	`screen_capture_action`	`NO_ACTION`

I browser non espongono alcuna attestazione a livello di sistema operativo sull’origine della fotocamera a nessun fornitore, quindi sul web questi segnali costituiscono prove a supporto piuttosto che prove certe. Sul web, un verdetto pari a null indica non determinato (le etichette dei dispositivi non sono disponibili finché non viene concesso il permesso per la fotocamera) e non genera mai un rischio.

Una fotocamera virtuale viene identificata dal nome del dispositivo, quindi una fotocamera che il sistema operativo presenta con un nome comune non viene riconosciuta in questo modo. All’interno di un emulatore Android la fotocamera rimappata viene etichettata come una qualsiasi integrata, motivo per cui il caso dell’hardware emulato viene segnalato tramite FRAME_INJECTION_SUSPECTED: viene rilevato dall’ambiente del dispositivo (lo stack di rendering e il modello del dispositivo segnalati nello user agent) anziché dal nome della fotocamera. I rilievi generati dall’ambiente del dispositivo contengono additional_data.reason: "emulated_capture_device", distinguendosi così dall’analisi dei frame eseguita dal modello di liveness stesso.

Il rilevamento della macchina da un browser costituisce una prova indiziaria, non un’attestazione, e un utente malintenzionato determinato può interferire con esso. Gli SDK nativi per dispositivi mobili segnalano segnali di integrità più solidi a livello di sistema operativo che un browser non può rilevare (emulatore, dispositivo sottoposto a root o jailbreak, hooking del runtime, debugger collegato), ciascuno con la propria azione configurabile in Integrità del runtime e del dispositivo. Questi segnali aumentano notevolmente i costi per l’attaccante, ma da soli non provano che un’acquisizione provenga da un dispositivo autentico. I segnali di integrità del dispositivo sono indipendenti dal metodo di liveness, pertanto si combinano con qualsiasi modalità tra Passiva, 3D Flash o 3D Action & Flash.

Analisi forense dell’integrità della registrazione

LIVENESS_VIDEO_ANOMALY viene calcolato lato server sulla registrazione di liveness archiviata, indipendentemente dal modello di liveness. Rileva una sequenza in movimento ripetuta su più cicli, compatibile con un feed riprodotto in loop.

Rischio	Causa	Chiave di configurazione	Predefinito
`LIVENESS_VIDEO_ANOMALY`	La registrazione contiene una sequenza in movimento ripetuta. Blocchi della fotocamera, fotogrammi statici ripetuti, sequenze iniziali scure e una consegna lenta dei fotogrammi non attivano da soli questo segnale.	`face_liveness_video_anomaly_action`	`NO_ACTION`

Imposta l’azione sul tuo nodo Rilevamento della vitalità o Stima dell’età: NO_ACTION registra un rilievo informativo, REVIEW può far passare una verifica con decisione presa allo stato In revisione, e DECLINE può farla passare a Rifiutata. Il controllo viene eseguito in modo asincrono, quindi un’escalation può arrivare dopo il risultato iniziale. Una decisione esistente più severa non viene declassata e le decisioni di revisione manuale vengono mantenute. I rilievi della versione 2 includono forensics_version: 2, prove di repeated_sequence e repeated_moving_sequence in anomaly_reasons. Le misurazioni di consegna come unique_frame_ratio, static_pair_ratio, decoded_fps_ratio e max_frame_gap_seconds rimangono diagnostiche; non possono da sole dimostrare che si tratta di un replay. I rilievi più datati descrivono la versione del rilevatore utilizzata all’epoca e non vengono riclassificati retroattivamente.

Si tratta di un segnale aggiuntivo prudenziale, non di un rilevamento completo di media sintetici o video iniettati. Una registrazione senza anomalie non costituisce una prova di vitalità. Acquisizioni brevi o ambigue e acquisizioni prive di prove di replay utilizzabili non vengono contrassegnate da questo controllo. Le registrazioni mancanti o illeggibili non producono alcun rilievo da questo controllo; continuano ad applicarsi gli altri controlli di verifica.

Confronto facciale tra sessioni

Rischio	Causa	Dati aggiuntivi	Gravità
`FACE_IN_BLOCKLIST`	Il volto corrisponde a un volto presente in blocklist.	`blocklisted_session_id`, `blocklisted_session_number`, `api_service`	`error` — rifiuto automatico
`POSSIBLE_FACE_IN_BLOCKLIST`	Il volto corrisponde a un volto presente in blocklist in una fascia di affidabilità inferiore.	`blocklisted_session_id`, `blocklisted_session_number`, `api_service`	`warning` — instradato sempre a Revisione nei workflow
`FACE_IN_ALLOWLIST`	Il volto corrisponde a un volto presente in allowlist.	`allowlisted_session_id`, `allowlisted_session_number`, `api_service`	`information` — azione per volto duplicato ignorata
`POSSIBLE_FACE_IN_ALLOWLIST`	Il volto corrisponde a un volto presente in allowlist in una fascia di affidabilità inferiore.	`allowlisted_session_id`, `allowlisted_session_number`, `api_service`	`information` — azione per possibile volto duplicato ignorata
`DUPLICATED_FACE`	Il volto corrisponde a un volto già approvato di un altro utente (una sessione `Approved` con diverso `vendor_data`, o un volto importato associato a uno dei tuoi utenti vendor).	`duplicated_session_id`, `duplicated_session_number`, `api_service`	Configurabile — `information` per impostazione predefinita
`POSSIBLE_DUPLICATED_FACE`	Il volto corrisponde a un altro volto approvato o importato in una fascia di affidabilità inferiore.	`duplicated_session_id`, `duplicated_session_number`, `api_service`	Configurabile — `information` per impostazione predefinita
`DUPLICATED_FACE_NAME_MISMATCH`	Emesso insieme a `DUPLICATED_FACE` quando l’identità della sessione corrispondente non coincide con il nome risolto di questa sessione (documento d’identità, `expected_details` o utente vendor collegato), utilizzando lo stesso punteggio di corrispondenza del nome e la stessa soglia della verifica dell’identità. Un volto riutilizzato con un nome diverso costituisce un segnale di frode più forte rispetto a un semplice duplicato, pertanto prevede un’azione configurabile dedicata.	`duplicated_session_id`, `duplicated_session_number`, `api_service`, `name_match_score`	Configurabile — `warning` per impostazione predefinita. Non riduce mai l’esito configurato di `DUPLICATED_FACE`, ma può solo aggravarlo.
`DUPLICATED_FACE_DOCUMENT_MISMATCH`	Emesso insieme a `DUPLICATED_FACE` quando il documento d’identità dell’utente corrispondente riporta una data di nascita diversa rispetto al documento di questa sessione. La stessa persona non viene segnalata se presenta un documento diverso (ad esempio un passaporto dopo una carta d’identità) o un documento rinnovato, e due sessioni che condividono lo stesso numero di documento dello stesso paese non vengono mai segnalate.	`duplicated_session_id`, `duplicated_session_number`, `api_service`, `mismatch_dimensions`	Configurabile (`face_liveness_duplicated_face_document_mismatch_action`) - `Review` per impostazione predefinita. Non riduce mai l’esito configurato di `DUPLICATED_FACE`, ma può solo aggravarlo.
`FACE_MATCHES_LIVENESS_ATTACK`	Il volto corrisponde a un volto di una sessione precedente di questa applicazione, appartenente a un altro utente, la cui acquisizione della vitalità è stata valutata come un attacco con elevata affidabilità. Costituisce un elemento per la revisione, non una prova certa di un attacco.	`liveness_attack_session_id`, `liveness_attack_session_number`, `similarity_percentage`, `liveness_attack_sessions_count`	Configurabile - `information` per impostazione predefinita (Nessuna azione)

Per le corrispondenze con volti importati o voci di elenco (che non hanno una sessione), i valori di *_session_id, *_session_number e api_service in additional_data sono null. I volti appartenenti allo stesso utente (stesso vendor_data, o lo stesso utente vendor quando disponibile) sono esclusi dall’intera ricerca nell’indice — sia dal rilevamento dei duplicati sia dallo screening delle blocklist. L’ordine di precedenza delle corrispondenze è: blocklist esatta → allowlist esatta → duplicato esatto → blocklist possibile → allowlist possibile → duplicato possibile — solo uno di questi sei codici mutuamente esclusivi compare per ciascun report. DUPLICATED_FACE_NAME_MISMATCH non fa parte di questo gruppo di precedenza: è un codice aggiuntivo emesso in aggiunta a DUPLICATED_FACE quando fallisce anche il controllo dell’identità, mai al suo posto. additional_data.name_match_score non include mai i nomi messi a confronto — solo gli ID e un punteggio, evitando così l’inclusione di PII nel payload dell’avviso. Un nome scritto in un sistema di scrittura diverso su ciascun documento (ad esempio ebraico su uno e latino sull’altro) può ottenere un punteggio inferiore alla soglia anche se entrambe le sessioni appartengono alla stessa persona. In questo caso specifico, DUPLICATED_FACE_NAME_MISMATCH non viene emesso se i documenti d’identità delle due sessioni si confermano a vicenda su tutti i seguenti elementi:

Entrambi i documenti riportano lo stesso stato emittente.
Un identificativo corrisponde esattamente tra i due documenti. document_number e personal_number sono intercambiabili, poiché lo stesso numero nazionale può comparire in entrambi i campi a seconda del tipo di documento.
Laddove entrambi i documenti riportino una data di nascita, questa corrisponde alla stessa data.

Se i nomi utilizzano lo stesso sistema di scrittura, se l’identificativo o lo stato emittente differiscono o sono assenti, oppure se le date di nascita sono in contrasto tra loro, l’avviso viene comunque emesso come descritto in precedenza.

Qualità della vitalità passiva (solo quando `method = "PASSIVE"`)

Rischio	Causa	Gravità	Rimedio
`MULTIPLE_FACES_DETECTED`	È stato rilevato più di un volto durante l’acquisizione. Il volto più grande viene sempre utilizzato per il calcolo del punteggio e il confronto.	Configurabile — `information` per impostazione predefinita	Ripetere l’acquisizione da soli.
`LOW_FACE_QUALITY`	Qualità del volto inferiore alla soglia di revisione (valore predefinito: 15).	`warning`; `error` quando inferiore alla soglia di rifiuto (valore predefinito: 0 — rifiuto disabilitato)	Migliore messa a fuoco / minore occlusione / volto centrato.
`LOW_FACE_LUMINANCE`	Luminanza normalizzata inferiore alla soglia minima (valore predefinito: 20).	Configurabile — `warning` per impostazione predefinita (l’azione predefinita è Revisione)	Illuminazione migliore.
`HIGH_FACE_LUMINANCE`	Luminanza normalizzata superiore alla soglia massima (valore predefinito: 80).	Configurabile — `warning` per impostazione predefinita (l’azione predefinita è Revisione)	Ridurre l’illuminazione; evitare il controluce.

LOW_FACE_LUMINANCE e HIGH_FACE_LUMINANCE sono mutuamente esclusivi — la luminanza è o inferiore al minimo o superiore al massimo, mai entrambi.

Stima dell’età (workflow adattivi e nodi `AGE_ESTIMATION`)

Rischio	Causa	Gravità	Rimedio
`AGE_BELOW_MINIMUM`	Età stimata inferiore al minimo configurato (o alla soglia limite quando il fallback sulla verifica dell’identità è abilitato).	`error`	Il workflow esegue il fallback sulla verifica dell’identità se configurato.
`AGE_NOT_DETECTED`	Impossibile stimare l’età e il fallback sulla verifica dell’identità è disabilitato.	`error`	Abilita il fallback o ripeti l’acquisizione.

Stringhe di descrizione esatte

L’API restituisce queste stringhe esatte di short_description e long_description per ciascun rischio:

`risk`	`short_description`	`long_description`
`NO_FACE_DETECTED`	No Face Detected in liveness	The system couldn’t identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues.
`LIVENESS_FACE_ATTACK`	Liveness Face Attack	The system detected a potential attempt to bypass the liveness check.
`LOW_LIVENESS_SCORE`	Low liveness score	The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.
`LIVENESS_VIDEO_ANOMALY`	Liveness video stream anomaly	The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live.
`FACE_IN_BLOCKLIST`	Face in blocklist	The system identified a face in the blocklist, which means the face is not allowed to be verified.
`POSSIBLE_FACE_IN_BLOCKLIST`	Possible face in blocklist	The system identified a possible face in the blocklist, which means the face is not allowed to be verified.
`FACE_IN_ALLOWLIST`	Face in allowlist	The face matched the application’s face allowlist, so duplicate-face actions were skipped for this signal.
`POSSIBLE_FACE_IN_ALLOWLIST`	Possible face in allowlist	The face possibly matched the application’s face allowlist, so possible duplicate-face actions were skipped for this signal.
`DUPLICATED_FACE`	Duplicated face from other approved session	The system identified a duplicated face from another approved session, requiring further investigation.
`POSSIBLE_DUPLICATED_FACE`	Possible duplicated face from other approved session	The system identified a possible duplicate face from another approved session, requiring further investigation.
`DUPLICATED_FACE_NAME_MISMATCH`	Duplicated face under a different name	The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.
`FACE_MATCHES_LIVENESS_ATTACK`	Face matches a liveness attack	The face in this liveness capture matches a face from an earlier session of this application whose own capture the liveness engine judged to be an attack with high confidence, in a session of another user. A genuine user can be rejected by mistake, so this is a signal for review, not proof of an attack.
`MULTIPLE_FACES_DETECTED`	Multiple faces detected	Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.
`LOW_FACE_QUALITY`	Low face quality	The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.
`LOW_FACE_LUMINANCE`	Low face luminance	The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.
`HIGH_FACE_LUMINANCE`	High face luminance	The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended.
`AGE_BELOW_MINIMUM`	Age below minimum	The age of the face is below the minimum age threshold for the application.
`AGE_NOT_DETECTED`	Age not detected	The system couldn’t identify the age of the face, which is necessary for document verification.

API autonoma di rilevamento passivo della vitalità

La Liveness API standalone riutilizza gli stessi codici di rischio con alcune differenze di comportamento:

NO_FACE_DETECTED e LOW_LIVENESS_SCORE si escludono a vicenda: il controllo del punteggio viene eseguito solo se viene trovato un volto. LOW_LIVENESS_SCORE si attiva rispetto al valore di face_liveness_score_decline_threshold della richiesta (predefinito 30) e restituisce sempre log_type: "error".
POSSIBLE_FACE_IN_BLOCKLIST viene gestito come un rifiuto (log_type: "error") invece che come revisione.
MULTIPLE_FACES_DETECTED restituisce log_type: "warning", mentre i rischi legati a volti duplicati rimangono informativi. Solo gli avvisi di livello error impostano il campo status della risposta standalone su Declined.
Le voci di avviso standalone includono feature ma nessun node_id.

Esempi

Rifiuto automatico su attacco rilevato

"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_FACE_ATTACK",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Liveness Face Attack",
    "long_description": "The system detected a potential attempt to bypass the liveness check.",
    "node_id": "liveness_primary"
  }
]

Avvisi configurabili su un’acquisizione passiva

"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_QUALITY",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face quality",
    "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_LUMINANCE",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face luminance",
    "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "MULTIPLE_FACES_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Multiple faces detected",
    "long_description": "Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.",
    "node_id": "liveness_primary"
  }
]

Volto duplicato con payload

"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "warning",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  }
]

In questo caso l’azione per il volto duplicato è impostata su Review, quindi l’avviso include log_type: "warning" e lo stato del report di rilevamento della vitalità è In Review. Con l’impostazione predefinita (No action) includerebbe invece log_type: "information". api_service è null perché il volto corrispondente proveniva da una sessione di workflow e non da una chiamata API autonoma.

Volto duplicato con un nome diverso

"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "information",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE_NAME_MISMATCH",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null,
      "name_match_score": 42.5
    },
    "log_type": "warning",
    "short_description": "Duplicated face under a different name",
    "long_description": "The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.",
    "node_id": "liveness_primary"
  }
]

DUPLICATED_FACE mantiene l’azione configurata (qui, No action — log_type: "information"), mentre DUPLICATED_FACE_NAME_MISMATCH riporta la propria azione, che per impostazione predefinita è Review (log_type: "warning"). Lo stato del report di rilevamento della vitalità assume il livello più grave tra i due: qui In Review, anche se la sola impostazione del volto duplicato non lo avrebbe segnalato.

Anomalia di integrità della registrazione con le relative misurazioni

"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_VIDEO_ANOMALY",
    "additional_data": {
      "forensics_version": 2,
      "duration_seconds": 6.0,
      "repeated_sequence": {
        "period_frames": 6,
        "cycles": 3,
        "matched_pairs": 12
      },
      "anomaly_reasons": ["repeated_moving_sequence"]
    },
    "log_type": "information",
    "short_description": "Liveness video stream anomaly",
    "long_description": "The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live.",
    "node_id": "liveness_primary"
  }
]

Questo esempio mostra le prove di replay provenienti da una registrazione contenente tre copie di una sequenza in movimento. log_type è information perché l’azione configurata è NO_ACTION. La diagnostica della consegna dei frame, omessa in questo esempio per brevità, non attiva la segnalazione.

Tipi di avviso

A ciascun rischio viene assegnata una gravità in base alla configurazione della tua applicazione. I tre livelli di gravità sono:

Correlati

Report di rilevamento della vitalità — schema completo del report e degli stati.
Avvisi di confronto facciale — avvisi associati al confronto facciale 1:1.
Webhook — session.status.updated trasmette gli avvisi non appena termina il passaggio di rilevamento della vitalità.
Modelli di dati — Controllo di rilevamento della vitalità — schema canonico con tutti i campi.
Modelli di dati — Oggetto di avviso — la struttura di ogni voce in warnings[].

Autenticazione

Verifica

Monitoraggio

Piattaforma

Rilevamento della vitalità: avvisi e codici di errore

Panoramica

Condizioni di rifiuto automatico

Impostazioni di verifica configurabili

Avvisi generati

Vitalità principale

Integrità del canale di acquisizione

Analisi forense dell’integrità della registrazione

Confronto facciale tra sessioni

Qualità della vitalità passiva (solo quando `method = "PASSIVE"`)

Stima dell’età (workflow adattivi e nodi `AGE_ESTIMATION`)

Stringhe di descrizione esatte

API autonoma di rilevamento passivo della vitalità

Esempi

Rifiuto automatico su attacco rilevato

Avvisi configurabili su un’acquisizione passiva

Volto duplicato con payload

Volto duplicato con un nome diverso

Anomalia di integrità della registrazione con le relative misurazioni

Tipi di avviso

Correlati

​Panoramica

​Condizioni di rifiuto automatico

​Impostazioni di verifica configurabili

​Avvisi generati

​Vitalità principale

​Integrità del canale di acquisizione

​Analisi forense dell’integrità della registrazione

​Confronto facciale tra sessioni

​Qualità della vitalità passiva (solo quando method = "PASSIVE")

​Stima dell’età (workflow adattivi e nodi AGE_ESTIMATION)

​Stringhe di descrizione esatte

​API autonoma di rilevamento passivo della vitalità

​Esempi

​Rifiuto automatico su attacco rilevato

​Avvisi configurabili su un’acquisizione passiva

​Volto duplicato con payload

​Volto duplicato con un nome diverso

​Anomalia di integrità della registrazione con le relative misurazioni

​Tipi di avviso

​Correlati

Panoramica

Condizioni di rifiuto automatico

Impostazioni di verifica configurabili

Avvisi generati

Vitalità principale

Integrità del canale di acquisizione

Analisi forense dell’integrità della registrazione

Confronto facciale tra sessioni

Qualità della vitalità passiva (solo quando `method = "PASSIVE"`)

Stima dell’età (workflow adattivi e nodi `AGE_ESTIMATION`)

Stringhe di descrizione esatte

API autonoma di rilevamento passivo della vitalità

Esempi

Rifiuto automatico su attacco rilevato

Avvisi configurabili su un’acquisizione passiva

Volto duplicato con payload

Volto duplicato con un nome diverso

Anomalia di integrità della registrazione con le relative misurazioni

Tipi di avviso

Correlati