Questa guida descrive i problemi più comuni e le soluzioni da adottare quando si realizza un'integrazione basata su API. È necessario adattare questi consigli alla propria applicazione e al proprio framework.
Non siamo in grado di fornire assistenza per le integrazioni personalizzate attraverso i normali canali di supporto, poiché ci sono molti fattori al di fuori del nostro controllo. Scrivere un'integrazione personalizzata è relativamente semplice, ma è necessario essere uno sviluppatore esperto con una buona conoscenza degli elementi essenziali di HTTP.
Per vedere esempi di integrazioni testate nel mondo reale che affrontano tutti i problemi descritti di seguito, potete consultare le nostre integrazioni su GitHub:
- https://github.com/Crowdhandler/crowdhandler-cloudflare-integration
- https://github.com/Crowdhandler/crowdhandler-php-sdk
Problemi di esclusione degli URL
Se la vostra applicazione ha un front controller, potreste instradare tutte le richieste alla vostra applicazione attraverso un'integrazione che effettua il check-in con CrowdHandler per consentire o meno le singole richieste di URL. Questo può causare i due problemi seguenti:
1. Controllo degli URL non necessari
Quando un utente carica una pagina, il browser carica tutte le risorse della pagina associate sul vostro dominio ed è possibile che queste richieste passino attraverso il vostro front-controller. Questo può causare controlli non necessari, che aggiungono tempo di caricamento e, in ultima analisi, carico del server all'applicazione. Si consiglia di escludere almeno queste estensioni di file comuni prima di controllare un URL:
.css. gif .ico .jpg .jpeg .js .json .mov .mp4 .mpeg .mpg .png .svg .ttf .otf .eot .woff .woff2
È inoltre necessario escludere qualsiasi altro percorso nelle applicazioni che si riferisca a contenuti che non richiedono la protezione della sala d'attesa. Ad esempio, se si memorizzano tutte le risorse statiche in una sottodirectory chiamata /static, è possibile escludere tale percorso dai controlli.
2. Blocco dei servizi di terze parti in coda
Se si utilizza un front controller come sopra e si dispone di servizi di terze parti che chiamano API sul dominio protetto, è probabile che questi servizi vengano bloccati nella coda e non avanzino perché è improbabile che accettino i cookie. I servizi di terze parti più comuni che possono essere bloccati sono:
- Servizi, plugin o applicazioni che consumano API sul vostro dominio (RPC, REST)
- Servizi di pagamento che effettuano callback lato server al vostro dominio per confermare le transazioni.
Se i servizi utilizzano un intervallo IP strettamente definito, è possibile consentirne il passaggio aggiungendo l'intervallo IP con una regola di bypass. Tuttavia, di solito è preferibile escludere questi URL dai controlli.
3. Blocco degli URL dell'amministratore
Se si accede all'applicazione di backend o al CMS attraverso url come /admin, si consiglia di escludere anche questi url. Potrebbe essere altrettanto efficace impostare gli IP dell'ufficio o della VPN in modo da escluderli.
Problemi con i cookie
Forse il problema più grande che riscontriamo con le integrazioni personalizzate è la mancata impostazione di un cookie per tenere traccia del token CrowdHandler dell'utente.
È possibile che si utilizzino i cookie o un'altra forma di memorizzazione della sessione da parte del browser o del server. In questa sede utilizziamo i cookie come termine generico per indicare qualsiasi metodo di memorizzazione utilizzato per tracciare il token CrowdHandler dell'utente, ma è necessario prestare attenzione a qualsiasi mezzo si utilizzi per registrare le sessioni.
1. Mancata impostazione di un cookie leggibile
L'integrazione deve memorizzare il token CrowdHandler dell'utente quando viene reindirizzato per la prima volta al sito. Non si può fare affidamento sul fatto che il token sia presente nell'URL dopo il primo accesso dopo il reindirizzamento dalla sala d'attesa. È necessario assicurarsi che il cookie sia impostato. Assicurarsi di impostare un cookie che l'applicazione possa leggere dai percorsi successivi che l'utente potrebbe visitare.
2. Mancata impostazione del cookie a causa di un reindirizzamento HTTP
Il motivo più comune per cui un'integrazione non riesce a impostare un cookie è che un reindirizzamento HTTP cattura l'utente prima ancora che l'integrazione venga eseguita e lo reindirizza a un nuovo percorso senza passare il token nell'URL. Queste regole di reindirizzamento possono trovarsi nella configurazione del server web o essere eseguite all'inizio del percorso del codice per gestire i reindirizzamenti della lingua o del login. Quindi, se si ha a che fare con un sito multilingue o si protegge un percorso che prevede il login dell'utente, occorre prestare particolare attenzione. La soluzione è assicurarsi che i reindirizzamenti includano la stringa di query con il token, oppure assicurarsi di non inviare gli utenti direttamente dalla sala d'attesa a un URL che verrà immediatamente reindirizzato.
Esiste un articolo della Knowledge Base dedicato a questo problema. Leggetelo per capire meglio. Sebbene questo articolo sia rivolto principalmente agli utenti dell'integrazione JavaScript, è possibile ricreare questo problema nella propria integrazione.
3. Mancato aggiornamento del cookie
Ci sono ragioni legittime per cui un utente può trovarsi a passare attraverso la coda più di una volta, o può avere la sessione scaduta e ricevere un nuovo token. Per questo motivo, è importante aggiornare il cookie ogni volta che viene visualizzato un token crowdhandler nell'URL o quando viene restituito un nuovo token dall'API. In caso contrario, l'integrazione potrebbe utilizzare un token scaduto, rimandando l'utente alla coda.
Quindi, nel codice di integrazione, cercate un token nell'URL. Se ne trovate uno, fate la chiamata con il token nell'URL a favore di qualsiasi token possiate trovare in un cookie. Quindi, in entrambi i casi, fidatevi del token ben formato che viene restituito dall'API e impostate il cookie.
4. Eliminazione del cookie o impostazione di un valore malformato
Quando si esamina l'URL o si analizza la risposta dell'API per vedere se è necessario aggiornare il cookie dell'utente, bisogna fare attenzione a non lasciare che un bug da qualche parte nel codice imposti accidentalmente un valore nullo, vuoto o falso. Alcuni framework lo interpreteranno come una cancellazione del cookie e, in ogni caso, se l'utente invia un token non valido alla sua prossima richiesta, gli verrà rilasciato un nuovo token, che lo manderà in fondo alla coda.
5. La mancata impostazione di un cookie quando si reindirizza l'utente alla sala d'attesa.
A rigore, non è necessario impostare un cookie se si intende reindirizzare l'utente alla sala d'attesa. Tuttavia, la vostra integrazione sarà molto più robusta se impostate sempre un cookie. Questo perché l'utente potrebbe tornare sul sito in qualche modo prima di aver completato il suo viaggio attraverso la sala d'attesa. Se lo riconoscete ancora, verrà rimandato alla sala d'attesa, mantenendo la sua posizione originale. In caso contrario, l'utente verrà rimandato nella sala d'attesa con una nuova posizione in fondo alla coda. Se un utente rimane a lungo in una sala d'attesa, non è insolito che provi di nuovo il sito, magari in una nuova scheda. Soprattutto se ha ricevuto un link via e-mail alla pagina protetta.
6. Impostare una data di scadenza inappropriata per il cookie o affidarsi alla memorizzazione temporanea della sessione.
Considerando lo scenario precedente, il tipico timeout di 20 minuti associato all'archiviazione di sessione incorporata fornita da framework come .Net o PHP potrebbe non essere abbastanza robusto per questo scenario. In caso di dubbio, impostare un cookie di sessione o un cookie permanente.
Problemi API
Prendete tempo per capire i parametri che state inviando e le risposte che potreste ricevere. Questi sono i problemi principali che riscontriamo con le richieste e le risposte API:
1. Invio dell'IP sbagliato all'API
Quando si invia l'IP alla risorsa di richiesta, assicurarsi di inviare l'IP dell'utente e non l'IP del proprio server o l'IP di un server proxy intermedio. Se si invia più volte lo stesso IP, è probabile che venga identificato e bloccato. Se si verifica questo problema dal vivo, è possibile impostare l'IP o l'intervallo in questione su "ignora", per evitare il blocco automatico, ma è necessario testare e correggere l'integrazione per identificare l'IP corretto. In genere, se il server web si trova dietro un proxy, è possibile rilevare l'IP reale dall'intestazione HTTP X-Forwarded-For. Questa guida può essere utile.
2. Presumendo che l'API risponda
La ragion d'essere di CrowdHandler è quella di essere disponibile anche quando il sito dell'utente non lo è. Tuttavia, ci sono molte ragioni legittime per cui il server potrebbe essere temporaneamente incapace di connettersi all'API di CrowdHandler, tra cui problemi generali di routing su Internet o problemi con il centro dati. Se il codice presume di ricevere sempre una risposta ben formata, è probabile che l'utente visualizzi un brutto errore se e quando si verificano queste situazioni. Soluzioni:
- Quando si effettua la chiamata API, specificare un timeout breve (2 secondi è ottimale).
- Se la chiamata va a vuoto o la risposta non è ben formata, bisogna considerare cosa si vuole fare. Nella maggior parte dei casi si vorrà fidarsi dell'utente e consentirgli l'accesso all'url, perché in questo modo, se l'interruzione si verifica mentre non si sta gestendo una coda, l'utente non sarà interrotto. In scenari di scarsa fiducia, si potrebbe voler inviare l'utente alla sala d'attesa: la sala d'attesa di CrowdHandler tenterà di stabilire una connessione API e farà del suo meglio con l'utente finché non riceverà una risposta ben formata dall'API.
3. Presupponendo il formato della risposta
Nella maggior parte dei casi riceverete una risposta dettagliata, che include la messaggistica della sala d'attesa, ecc. Ecco un esempio:
{
"result": {
"status": 1,
"token": "tok_7pDi5dRB2nUi",
"title": "The Herb Girls Reunited!",
"position": 964,
"promoted": 0,
"urlRedirect": null,
"onsale": "2021-12-06T12:20:00Z",
"message": "Booking is very busy right now. We appreciate your patience and will forward you shortly.",
"slug": "herb-girls",
"priority": null,
"priorityAvailable": 1,
"logo": "https://crowdhandler-templates.s3.amazonaws.com/public/94ea09f553bf57af84c21427c68b3c89fc64e2044c347522ba4ca01363ffaf8b/Queen Victoria Hall-logo-2.png",
"responseID": "e0abd8dbb8d2810fad16855622dcd45f",
"captchaRequired": 0,
"rate": 50,
"hash": null,
"ttl": 55
}
}
Tuttavia, alcuni stati forniscono una piccola quantità di informazioni.
Ad esempio, se si controlla una richiesta per un URL che non è protetto da alcuna sala d'attesa CrowdHandler.
{
"result": {
"status": 0,
"token": null,
"responseID": null,
"promoted": 1
}
}Altre risposte che si possono vedere sono se la chiave non è valida (errore 401 HTTP), se la stanza è piena (stato: 5) o se l'IP che si sta inviando è stato inserito nell'elenco dei bloccati (stato: 4).
Soluzioni:
- Prendetevi un po' di tempo per capire il significato dei codici di risposta che vi vengono restituiti. Si tratta di situazioni che potrebbero essere prese in considerazione.
- Per sapere se all'utente deve essere concesso l'accesso o se deve essere mandato in sala d'attesa, è sufficiente controllare l'attributo booleano promoted che, a meno che non ci sia un errore, sarà sempre presente e avrà valore 0 o 1. Se l'integrazione è molto semplice e si guarda solo a questo attributo, non è necessario capire le varie risposte e gli stati, perché se promoted è 0, si può inviare l'utente alla sala d'attesa e la sala d'attesa saprà cosa fare.
- Se si è costruita un'applicazione o si utilizza un framework che richiede che l'oggetto risposta sia sempre coerente per motivi OO, si dovrebbe iniziare con un oggetto o una classe di base per rappresentare la risposta, specificando valori predefiniti ragionevoli, e quindi impostare solo i valori che ritornano dalla risposta dell'API.