Registro Consensi | Enesi Docs

Integrazione base

L'integrazione base permette di registrare il consenso con la sola applicazione di alcuni tag, è necessario:

identificare i campi standard
identificare eventuali campi aggiuntivi (opzionale)
mostrare le informative di consenso
raccogliere il consenso

Il campo hidden data-epp-consent-resume contiene un payload base64(JSON) da inviare al server sul parametro consent.

Campi standard

I campi standard identificano i dati sensibili più utilizzati e l'indirizzo e-mail per l'invio della notifica di raccolta del consenso, si applicano tramite l'attributo data-epp-consent-field
Quando non è presente alcun attributo viene letto automaticamente l'attributo name

Campi standard disponibli

first_name	facoltativo	Nome
last_name	facoltativo	Cognome
email	obbligatorio	Indirizzo e-mail
phone	facoltativo	Telefono fisso
mobile_phone	facoltativo	Telefono cellulare
tax_code	facoltativo	Codice fiscale o P.Iva

Esempio

<input ... data-epp-consent-field="[NAME]" ... />
<input ... name="[NAME]" ... />

NAME identificativo del campo standard

Campi aggiuntivi

I campi di un form, che non rientrano nei campi stanrdard, si applicano tramite l'attributo data-epp-consent-field-label
Quando non è presente alcun attributo viene letta automaticamente la relativa label legata tramite la relazione label[for] : input[id]

Esempio

<input ... data-epp-consent-field-label="[LABEL]" ... />

<label for="name">[LABEL]</label>
<input id="name" ... />

LABEL label del campo (testo libero)

Campi da escludere

I campi di un form che non necessitano di tracciamento ai fini della registrazione del consenso possono essere esclusi tramite l'attributo data-epp-consent-field-skip

È consigliato escludere campi che contengono informazioni corpose per ridurre il peso del consenso, come ad esempio i campi di testo.

Esempio

<input ... data-epp-consent-field-skip ... />

Informative di consenso

Per mostrare le informative di consenso è necessario inserire elementi identificati tramite l'attributo data-epp-consent.
È consigliato inserire anche il blocco introduttivo con data-epp-consent="intro" per visualizzare la dicitura generale con richiamo alla privacy policy.

Formattazioni disponibili

Default: il testo dell'informativa viene caricato automaticamente dalle api.
Label personalizzata: il testo inserito nel tag viene usato come label visibile (es. testo legale personalizzato).
Campo richiesto: aggiungendo required il checkbox generato per quella informativa diventa obbligatorio.
Intro: data-epp-consent="intro" mostra il testo introduttivo generale.

Esempio

<div data-epp-consent="[PID]"></div>  // Formato default
<div data-epp-consent="[PID]">Label personalizzata</div>  // Testo personalizzato
<div data-epp-consent="[PID]" required></div>  // Checkbox obbligatorio
<div data-epp-consent="intro"></div>

PID codice informativa di consenso

Test del consenso

È possibile verificare la presenza del consenso e in caso di esito positivo:

preselezionare il checkbox dell'informativa tramite il tag data-epp-consent-test.

Il test viene eseguito tramite una verifica dei campi standard, impostati tramite una stringa json, i campi possono essere combinati tra loro in AND

Esempio

// Test con match su email e cognome
<div data-epp-consent="[PID]" data-epp-consent-test='{"email":"l.rossi@gmail.com","last_name":"Rossi"}'></div>

Opzioni aggiuntive

E' possibile aggiungere delle opzioni di formattazione tramite l'attributo data-epp-consent-opts inserendo la lista di opzioni disponibili separate da una virgola

Opzioni disponibli

text-first

visualizza prima il testo dell'informativa e poi il nome con il check

Esempio

<div data-epp-consent="[PID]" data-epp-consent-opts="text-first"></div>

Raccolta del consenso

I dati del consenso vengono generati automaticamente lato client all'accettazione di almeno una informativa di consenso e vengono salvati in un campo hidden identificato tramite l'attributo data-epp-consent-resume

Questo campo (in documentazione denominato come [name="_epp_consent_resume"]) contiene i dati che possono essere utilizzati per la registrazione del consenso lato server

Esempio

<input data-epp-consent-resume type="hidden" name="_epp_consent_resume" />

Registrazione del consenso lato server

La registrazione del consenso può essere eseguita con una chiamata verso https://privacy.ene.si/api/consent/add/

$ch = curl_init('https://privacy.ene.si/api/consent/add/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'key' => [KEY],
    'uid' => [UID],
    'ln' => [LANG],
    'consent' => $_REQUEST['_epp_consent_resume']
]);

$response = json_decode(curl_exec($ch));
curl_close($ch);

if($response && $response->s === true){
    // Consenso registrato correttamente
}

KEY api key del cliente

UID codice identificativo del progetto

LANG lingua richiesta tra quelle disponibili: ita, eng, spa, fra, deu, por, tur, rus, ukr

Auto invio del form

È possibile registrare automaticamente il consenso da un form utilizzando il tag data-epp-consent-auto senza quindi eseguire la registrazione lato server

Questa tecnica è da utilizzare in casi limite, dove non ci sono alternative. È sempre preferibile registrare manualmente il consenso lato server. L'auto invio potrebbe inoltre eseguire una registrazione di consenso senza un effettivo invio del form.

Esempio

<form data-epp-consent-auto> ... </form>

Eventi disponibli

Utilizzando l'auto invio sono disponibili due eventi per recuperare lo stato di registrazione del consenso:

_epp_consent:added consenso registrato
_epp_consent:error errore durante la registrazione del consenso

// Consenso registrato
form.on("_epp_consent:added", function(e, consent, response){
    console.log(consent.toString() + response.toString());
});
// Errore durante la registrazione del consenso<
form.on("_epp_consent:error", function(e, consent, response){
    console.log(consent.toString() + response.toString());
});

Esempio

Di seguito un esempio completo di un form per la registrazione del consenso

Codice utilizzato

Callbacks

<form id="consent-test-form" data-epp-consent-auto onsubmit="return false;">
    <div class="form-group row">
        <label for="first_name" class="col-sm-2 col-form-label">Nome</label>
        <div class="col-sm-10"><input class="form-control" type="text" data-epp-consent-field="first_name" data-epp-consent-field-label="Nome" id="first_name" name="name"></div>
    </div>
    <div class="form-group row">
        <label for="last_name" class="col-sm-2 col-form-label">Cognome</label>
        <div class="col-sm-10"><input class="form-control" type="text" id="last_name" name="last_name"></div>
    </div>
    <div class="form-group row">
        <label class="col-sm-2 col-form-label">Email</label>
        <div class="col-sm-10"><input class="form-control" type="email" data-epp-consent-field="email" data-epp-consent-field-label="Email" name="email"></div>
    </div>
    <div class="form-group row">
        <label class="col-sm-2 col-form-label">Indirizzo (Campo aggiuntivo)</label>
        <div class="col-sm-10"><input class="form-control" type="text" data-epp-consent-field-label="Indirizzo" name="address_1"></div>
    </div>
    <div class="form-group row">
        <label for="citta" class="col-sm-2 col-form-label">Citt&agrave;</label>
        <div class="col-sm-10"><input id="citta" class="form-control" type="text" name="citta"></div>
    </div>
    <div class="form-group row">
        <label class="col-sm-2 col-form-label">Indirizzo 2 (Campo escluso)</label>
        <div class="col-sm-10"><input class="form-control" type="text" data-epp-consent-field-skip name="address_2"></div>
    </div>

    <div data-epp-consent="10001">Esempio di una label personalizzata</div>
    <div data-epp-consent="10001" data-epp-consent-opts="text-first"></div>
    <div data-epp-consent="10002" required></div>
    <div data-epp-consent="intro"></div>
    <input data-epp-consent-resume type="hidden" name="_epp_consent_resume" />

    <div class="text-right">
        <button class="btn btn-primary" type="submit">Registra consenso automaticamente</button>
        <button class="btn btn-primary" type="button" data-consent-test-form-curl>Registra consenso lato server</button>
    </div>
</form>

Metodi Javascript

L'SDK Javascript permette di eseguire una serie di operazioni

L'integrazione base non necessita dell'utilizzo di queste operazioni, poichè viene effettuato tutto automaticamente tramite l'applicazione dei tag ed invio lato server

load()

Permette di ricaricare le informative di consenso

window.EPP.consent.load();

add()

Invia uno o più consensi già costruiti (array oggetti consenso).

window.EPP.consent.add(consent, function(r){
    if(r.s === true){
        // consenso inserito correttamente
    }
});

consent array di oggetti consenso

addForm()

Invia un consenso recuperandolo automaticamente dai dati di un form

window.EPP.consent.addForm(form, function(r){
    if(r.s === true){
        // consenso inserito correttamente
    }
});

form elemento javascript che identifica il form

Nota: gli eventi _epp_consent:added e _epp_consent:error vengono emessi solo se è presente jQuery.

getFormConsent()

Recupera l'array di consensi automaticamente dai dati di un form

window.EPP.consent.getFormConsent(form)

form elemento javascript che identifica il form

replaceConsentInformations()

Ricarica dal server le informative presenti nel DOM tramite i tag data-epp-consent.

window.EPP.consent.replaceConsentInformations();

refreshConsentResume()

Aggiorna i campi hidden data-epp-consent-resume in base allo stato corrente del form.

window.EPP.consent.refreshConsentResume();

Struttura del consenso

A titolo informativo. Di seguito le strutture dei dati di invio e risposta. Attualmente non è presente altra documentazione in merito.

Invio

{
    key: [KEY] (obbligatorio)
    uid: [UID]
    ln: [LANG] (obbligatorio)
    consent: [
        {
            pid: [PID] (obbligatorio),
            time: [timestamp] (default: time())
            channel: [web|web.form|web.social.login|email|app.form] (obbligatorio)
            channelData: {
                ...
                [chiave]: "[valore]"
                ...
            },
            proof: {
                url: "...",
                html: "...",
                ...
                [chiave]: "[valore]"
                ...
            },
            userData: {
                [chiave]: { (utilizzabili i campi standard come chiavi: first_name, last_name, email, phone, mobile_phone, tax_code )
                    [label]: [valore],
                    [value]: [valore]
                }
            }
        }
    ]
}

Risposta

{
    "s": true,
    "data": {
        "10000":{ // [PID]
            "consentId":"69f7d8d611cac4584f7e955a62afa361", [id_privacy_consenso]
            "consentInformationId":"490e651e3ed62db8ada1edfdf2d62138", [id_privacy_informativo_consenso]
            "consentInformationRef":"10000.1", // [PID].[VERSIONE]
            "time":"2018-06-13 12:18:50" // time utilizzato per l'inserimento
        }    
    }
}