Documentazione sviluppatore | API e Guida all'Integrazione - Implementazione standard

Esempi di implementazione

Go.cam fornisce due esempi standard di implementazione, disponibili in PHP e JavaScript.

Verifica tramite libreria di reindirizzamento

Questa implementazione genera un URL di verifica Go.cam basato sulle tue chiavi di accesso.

Può essere utilizzata in modalità standalone se la verifica dell’età deve essere eseguita in una nuova finestra del browser o tramite reindirizzamento.

Questo metodo è progettato per essere chiaro e facile da seguire. Di seguito trovi una guida dettagliata.

Suggerimento: Un esempio di implementazione può essere scaricato dal tuo account Go.cam.

Passaggio 1: Includere l’SDK PHP


require_once 'avsPhpSdkV1.php';

Passaggio 2: Inizializzare l’SDK

Recupera le credenziali necessarie dal tuo account Go.cam e modifica il file config.php.


$config['partnerId'] = 0;
$config['cipherKey'] = '';
$config['hmacKey']   = '';

Inizializza la classe SDK nel file index.php.


$avsInstance = new AvsPhpSdkV1(
	$config['partnerId'],
	$config['cipherKey'],
	$config['hmacKey']
);

Passaggio 3: (Opzionale) Impostare la lingua

Per impostazione predefinita, la pagina di test viene visualizzata in inglese. Lingue supportate:

Inglese, francese, tedesco, olandese, italiano, portoghese, spagnolo


$avsInstance->setLanguage(AvsPhpSdkV1::LANGUAGE_EN);

Passaggio 4: Definire il payload della richiesta

Go.cam utilizza la crittografia AES-256-CBC per una comunicazione sicura.

Per ogni sessione, devi definire il payload, che può includere parametri obbligatori e opzionali.

Esempio:


$avsInstance->fillRequest([
        'userData' => [
        // obbligatorio: id utente interno del partner, utilizzato per tracciare l’utente
        'userId' => $userId,
        // opzionale: alcuni dati personalizzati che il partner desidera includere in questa sessione di verifica
        'someCustomData' => true,
        // opzionale: colori personalizzati per l’interfaccia del processo di verifica Go.cam
        'colorConfig' => [
			'body' => [
				'background' => $colorConfigBodyBackground,
				'foreground' => $colorConfigBodyForeground,
				'button' => [
					'background' => $colorConfigButtonBackground,
					'foreground' => $colorConfigButtonForeground,
					'foregroundCallToAction' => $colorConfigButtonForegroundCTA,
					'backgroundFailure' => $colorConfigButtonBackgroundFailureInput,
					'foregroundFailure' => $colorConfigButtonForegroundFailureInput,
					'foregroundCallToActionFailure' => $colorConfigButtonForegroundCTAFailureInput,
				]
			],
		] // opzionale
    ],
    'http' => [
        'userAgent' => $userAgent,
        'websiteHostname' => $websiteHostname,
        'paramList' => [
			// opzionale: un modo per controllare se il numero dell’età rilevata viene mostrato sullo schermo durante il processo di verifica dell’età tramite selfie
			'showDetectedAgeNumber' => $showDetectedAgeNumber,
			// opzionale: il tipo di verifica che vuoi mostrare all’utente
			// se non viene specificato come parametro o è vuoto tutti i tipi saranno visibili
			'verificationTypeList' => array('creditCard', 'selfie', 'scanId', 'email'),
			// opzionale: il tipo di verifica che vuoi selezionare come predefinito
			'verificationTypeDefault' => 'selfie',
			// opzionale: usare la verifica email come fallback nel caso in cui la prima verifica scelta fallisca
			'useEmailAsFallbackVerification' => true,
			// opzionale: un modo per controllare se il rilevamento selfie utilizzerà un liveness avanzato (usa vari controlli per rilevare se la persona davanti alla webcam è reale)
			'advancedLiveness' => $advancedLiveness,
        ]
    ],
	// opzionale: la versione di verifica Go.cam
	'verificationVersion' => AvsPhpSdkV1::VERIFICATION_VERSION_STANDARD_V1,
	// obbligatorio: l’URL per tornare al sito del partner dopo una verifica
	'linkBack' => $linkBack,
	// opzionale: IP dell’utente
	'ipStr' => $userIp,
	// opzionale: codice paese ISO dell’utente
	'countryCode' => $countryCode,
	// opzionale: codice stato ISO dell’utente (utilizzato principalmente per gli USA)
	'stateCode'  => $stateCode,
]);

Passaggio 5: Generare l’URL di verifica


$verificationUrl = $avsInstance->toUrl();

Passaggio 6: Aggiungere un link sul tuo sito web


"$verificationUrl; ?>" target="_blank">Avvia la verifica dell’età

L’URL di postback deve puntare al tuo backend, dove gestirai i dati di callback inviati da Go.cam. Consulta la Riferimento dei dati di callback backend per i dettagli.

Verifica tramite libreria iframe

La libreria iframe si basa sulla libreria di reindirizzamento ma consente a Go.cam di essere eseguito come iframe in overlay. Inoltre fornisce il controllo del ciclo di vita e la gestione degli eventi per il processo di verifica.

Suggerimento: Un esempio di implementazione può essere scaricato dal tuo account Go.cam.

Passaggio 1: Generare l’URL iframe

Invece di toUrl(), chiama:


$verificationUrl = $avsInstance->toIframeUrl();

Passaggio 2: Includere l’SDK frontend

Passaggio 3: Aggiungere un pulsante di attivazione

Passaggio 4: Inizializzare l’SDK frontend


var openVerificationIframeButton = document.querySelector('#openVerificationIframeButton');
var iframeUrl = ''; // generato dal PHP sopra

AvsJsSdk.V1.Config.create({ iframeLocationUrl: iframeUrl });

var avsInstance = new AvsJsSdk.V1.Core();
avsInstance.init();

Passaggio 5: Gestire gli eventi dell’SDK

L’SDK attiva eventi durante il processo di verifica. Puoi ascoltarli e reagire di conseguenza:


avsInstance.onMessage = function (eventMessage) {
	switch (eventMessage.name) {

		// fase di controllo: l’iframe è stato caricato
		case AvsJsSdk.V1.Config.EVENT_ON_CHECK_IFRAME_LOADED:

			// invia un evento all’iframe per avviare la fase di controllo del processo di verifica
			avsInstance.emit(AvsJsSdk.V1.Config.EVENT_STATUS_REQUEST);

			break;

		// fase di controllo: la verifica dell’età è andata a buon fine in un processo precedente, l’utente è già verificato
		case AvsJsSdk.V1.Config.EVENT_ON_INITIAL_VERIFICATION_SUCCESS:

			// il payload di verifica è valido
			if (eventMessage.data.isPayloadValid) {
				// disabilita il pulsante "avvia verifica"
				openVerificationIframeButton.disabled = true;
				return;
			}

			// il payload di verifica non è valido, procedi con il processo di verifica
			avsInstance.emit(AvsJsSdk.V1.Config.EVENT_RESOURCE_PRELOAD);

			break;

		// fase di controllo: la verifica dell’età non è andata a buon fine in un processo precedente oppure non è mai stata eseguita
		case AvsJsSdk.V1.Config.EVENT_ON_INITIAL_VERIFICATION_NOT_FOUND:

			// la fase di controllo è fallita, procedi alla fase di verifica, invia un evento per avviare il precaricamento delle risorse
			avsInstance.emit(AvsJsSdk.V1.Config.EVENT_RESOURCE_PRELOAD);

			break;

		// fase di verifica: le risorse iframe sono state caricate
		case AvsJsSdk.V1.Config.EVENT_ON_RESOURCES_LOADED:

			// abilita il pulsante "avvia verifica"
			openVerificationIframeButton.disabled = false;

			// aggiungi un evento click al pulsante "avvia verifica"
			openVerificationIframeButton.addEventListener('click', function () {
				// mostra l’iframe di verifica come overlay
				avsInstance.iframeInstance.expand();
			});

			break;

		// fase di verifica: è stato cliccato il pulsante di chiusura dell’iframe overlay
		case AvsJsSdk.V1.Config.EVENT_ON_CLOSE_IFRAME:

			// nasconde l’overlay dell’iframe di verifica (continua comunque a funzionare in background)
			avsInstance.iframeInstance.collapse();

			break;

		// fase di verifica: il processo di verifica è andato a buon fine
		case AvsJsSdk.V1.Config.EVENT_ON_VERIFICATION_SUCCESS:

			// disabilita il pulsante "avvia verifica"
			openVerificationIframeButton.disabled = true;

			break;

		}

	}

Riferimento eventi SDK frontend

Quando utilizzi la libreria iframe, l’SDK può attivare i seguenti eventi:

EVENT_ON_CHECK_IFRAME_LOADED – Documento iframe pronto.
EVENT_STATUS_REQUEST – Richiedere lo stato corrente della verifica.
EVENT_ON_INITIAL_VERIFICATION_SUCCESS – Verifica precedente trovata (cookie presente).
EVENT_ON_INITIAL_VERIFICATION_NOT_FOUND – Nessuna verifica trovata.
EVENT_RESOURCE_PRELOAD – Inizia il caricamento delle risorse di verifica.
EVENT_ON_INITIAL_VERIFICATION_FATAL_ERROR – Chiavi non valide o errore nel caricamento delle risorse.
EVENT_ON_START_PAGE_LOADED – Pagina di verifica caricata (le risorse stanno ancora caricando).
EVENT_ON_RESOURCES_LOADED – Risorse di verifica completamente caricate.
EVENT_ON_CLOSE_IFRAME – Overlay iframe chiuso.
EVENT_ON_VERIFICATION_SUCCESS – Verifica riuscita.
EVENT_ON_VERIFICATION_ERROR – Verifica fallita.

Dati URL di callback backend

Dopo ogni tentativo di verifica (successo o fallimento), Go.cam invia un postback server-to-server per notificare al tuo backend il risultato.

Il postback viene inviato come array con campi che descrivono la sessione di verifica e il suo esito.

Esempio di payload


[
    'userData' => [
        'userId' => 123,
        'colorConfig' => [
            'body' => [
                'background' => '#900',
                'foreground' => '#fff',
                'button' => [
                    'background' => '#fb0',
                    'foreground' => '#333',
                    'foregroundCallToAction' => '#700',
                    'backgroundFailure' => '#fb0',
                    'foregroundFailure' => '#333',
                    'foregroundCallToActionFailure' => '#700',
                ]
            ]
        ]
    ],
    'state' => 'Success',
    'stateInt' => 2,
    'sessionId' => 12345,
    'errorCode' => 0,
    'deviceType' => 1,
    'stepId' => 2,
    'websiteHostname' => 'your-site-name.cam',
    'ip' => '127.0.0.1',
]

Riferimento campi

state

Indica se la verifica è andata a buon fine.

Valore possibile	Significato
Success	la verifica è andata a buon fine
Fail	la verifica è fallita

stateInt

Rappresentazione numerica dello stato della verifica.

Valore possibile	Significato
0	sconosciuto
1	Test non avviato o interrotto
2	Successo
3	Fallito
4	Link scaduto
5	Link già utilizzato

sessionId

Identificatore univoco della sessione di verifica.

Esempio: 12345

errorCode

Codice di errore se la verifica è fallita.

Valore possibile	Significato
0	Nessun errore
25001	Il dispositivo non è supportato
25032	Precaricamento delle risorse di verifica fallito (risorse face api)
25033	Precaricamento delle risorse di verifica fallito (risorse tesseract)
25034	Impossibile recuperare l’elenco delle fotocamere del dispositivo (fase di selezione fotocamera per rilevamento selfie)
25055	Impossibile rilevare un numero sufficiente di volti dal video del dispositivo (età rilevata pari a 0)
25056	Controllo di somiglianza facciale fallito (confronto di tutti i volti selfie)
25057	Impossibile rilevare un numero sufficiente di volti dal video del dispositivo (0 volti rilevati)
25070	Nessun volto rilevato
25061	Impossibile rilevare un numero sufficiente di volti dal video del dispositivo (errore controllo espressione)
25062	Controllo di somiglianza facciale fallito (confronto volti espressione)
25047	Errore di inizializzazione webcam (fase di rilevamento selfie)
25035	Impossibile inizializzare le librerie di rilevamento (fase selfie -> rilevatore face api)
25036	Impossibile inizializzare le librerie di rilevamento (fase selfie -> modello età face api)
25037	Impossibile inizializzare le librerie di rilevamento (fase selfie -> modello riconoscimento face api)
25038	Impossibile inizializzare le librerie di rilevamento (fase selfie -> modello landmarks face api)
25058	Impossibile inizializzare le librerie di rilevamento (fase selfie -> modello espressione face api)
25067	Controllo corrispondenza facciale liveness fallito
25069	Controllo corrispondenza facciale liveness fallito
25085	Controllo corrispondenza facciale liveness fallito
25086	Controllo corrispondenza facciale liveness fallito
25068	Controllo liveness fallito
25039	Impossibile recuperare l’elenco delle fotocamere del dispositivo (fase di selezione fotocamera per rilevamento documento)
25040	Impossibile inizializzare le librerie di rilevamento (fase scan id -> worker tesseract)
25041	Impossibile inizializzare le librerie di rilevamento (fase scan id -> modello lingua tesseract)
25042	Impossibile inizializzare le librerie di rilevamento (fase scan id -> inizializzazione lingua tesseract)
25043	Impossibile inizializzare le librerie di rilevamento (fase scan id -> configurazione worker tesseract)
25044	Impossibile inizializzare le librerie di rilevamento (fase scan id -> rilevatore face api)
25045	Impossibile inizializzare le librerie di rilevamento (fase scan id -> modello riconoscimento face api)
25091	Impossibile inizializzare le librerie di rilevamento (fase scan id -> modello yolo)
25051	Impossibile estrarre un volto dalla tua carta d’identità
25052	Il volto del selfie non corrisponde a quello trovato sulla carta d’identità
25053	L’età rilevata è inferiore a 18 anni (fase scan id)
25075	L’età rilevata è inferiore a 18 anni (fase selfie)
25054	Impossibile estrarre la tua età dalla carta d’identità corrente
25090	Impossibile estrarre la tua età dalla carta d’identità corrente (fase yolo)
25046	Errore di inizializzazione webcam (fase scan id)
20056	Dati inviati non validi per la verifica dell’età via email
20051	Risposta captcha non valida
20052	Controllo captcha fallito
20053	Email non idonea
20058	Errore nella risposta di idoneità email
20054	Invio del codice di verifica età via email non riuscito
20057	Dati inviati del codice di verifica non validi
20055	Controllo codice di verifica fallito
20061	Indirizzo email non valido
20002	Tempo massimo consentito per il test scaduto (callback successo test)
20004	Step id non valido (callback successo test)
20000	Token non valido (callback successo test)
20034	Risposta curl xcore api non valida (callback successo test)
20003	Tempo massimo consentito per il test scaduto (callback fallimento test)
20005	Step id non valido (callback fallimento test)
20001	Token non valido (callback fallimento test)
20035	Risposta curl xcore api non valida (callback fallimento test)
20036	L’età rilevata è inferiore a 18 anni
18001	Errore interno verifica carta di credito
18002	Errore MaxMind verifica carta di credito

deviceType

Tipo di dispositivo utilizzato.

Valore possibile	Significato
0	sconosciuto
1	mobile
2	desktop

stepId

Fase del processo di verifica.

Valore possibile	Significato
0	sconosciuto
1	Test non avviato o interrotto
2	Successo
3	Fallito
4	Link scaduto
5	Link già utilizzato

idCountry

Codice paese ISO del documento di identità fornito.

Esempio: FR

idState

Codice stato ISO del documento di identità fornito (utilizzato principalmente per gli USA).

Esempio: TX

idType

Tipo di documento di identità.

Valore possibile	Significato
1	Carta d’identità
2	Passaporto
3	Patente di guida

websiteHostname

Hostname del sito web in cui è stata avviata la verifica.

Esempio: your-site-name.cam

ip

Indirizzo IP del dispositivo dell’utente.

Esempio: 127.0.0.1

Proteggi la tua attività, i tuoi utenti e la tua reputazione

Scegli GO.cam, la soluzione semplice e certificata per la verifica dell'età di cui si fidano gli operatori di siti web di oggi.
Inizia oggi!