Risoluzione dei problemi relativi alle integrazioni API personalizzate

Questa guida illustra i problemi più comuni e le relative soluzioni quando si realizza manualmente un'integrazione basata su API. Sarà necessario adattare questi consigli alla propria applicazione e ai propri framework specifici.

Non siamo in grado di fornire assistenza per le integrazioni personalizzate tramite i normali canali di assistenza, poiché vi sono numerosi fattori che esulano dal nostro controllo. Scrivere un'integrazione personalizzata è relativamente semplice, ma è necessario essere uno sviluppatore esperto con una buona padronanza dei fondamenti dell'HTTP.

Per vedere alcuni esempi di integrazioni collaudate sul campo che affrontano tutte le problematiche descritte di seguito, puoi consultare le nostre integrazioni su GitHub:

relativi all'esclusione degli URL#

Se la tua applicazione dispone di un front controller, è possibile che tu stia instradando tutte le richieste verso l'applicazione tramite un'integrazione che si collega a CrowdHandler per autorizzare o negare le singole richieste URL. Ciò può causare i due problemi seguenti:

1. Verifica degli non

Quando un utente carica una pagina, il browser caricherà tutte le risorse associate presenti sul tuo dominio, ed è possibile che tali richieste passino attraverso il tuo front-controller. Ciò può comportare l'esecuzione di controlli superflui, che aumenteranno il tempo di caricamento e, di conseguenza, il carico sul server della tua applicazione. Ti consigliamo di escludere almeno queste estensioni di file comuni prima di verificare un URL:

.css, .gif, .ico, .jpg, .jpeg, .js, .json, .mov, .mp4, .mpeg, .mpg, .png, .svg, .ttf, .otf, .eot, .woff, .woff2

È inoltre opportuno escludere dalle applicazioni qualsiasi altro percorso relativo a contenuti che non richiedono la protezione della "sala d'attesa". Ad esempio, se tutte le risorse statiche sono memorizzate in una sottodirectory denominata /static, è possibile escludere tale percorso dai controlli.

2. Blocco dei servizi di terze parti in coda

Se si utilizza un front controller come descritto sopra e si dispone di servizi di terze parti che effettuano chiamate alle API sul proprio dominio protetto, è probabile che tali servizi rimangano bloccati nella coda e non procedano, poiché difficilmente accetteranno i cookie. Tra i servizi di terze parti che potrebbero essere bloccati figurano:

  1. Servizi, plugin o applicazioni che utilizzano le API del tuo dominio (RPC, REST)
  2. Servizi di pagamento che effettuano callback lato server verso il tuo dominio per confermare le transazioni.

Se i servizi utilizzano un intervallo di indirizzi IP ben definito, potresti riuscire a consentirne l'accesso aggiungendo tale intervallo tramite una regola di esclusione. Tuttavia, di norma è preferibile escludere fin dall'inizio tali URL dai tuoi controlli.

3. Blocco degli di amministrazione

Se accedi alla tua applicazione backend o al tuo CMS tramite URL come /admin, potresti voler escludere anche questi URL. Potrebbe essere altrettanto efficace impostare gli IP del tuo ufficio o della tua VPN come esclusi.

relativi ai cookie#

Forse il problema principale che riscontriamo con le integrazioni personalizzate è l'impossibilità di impostare correttamente un cookie per tenere traccia del token CrowdHandler dell'utente.

Potresti utilizzare i cookie oppure un’altra forma di archiviazione delle sessioni a livello di browser o di server. In questo contesto utilizziamo il termine “cookie” in senso generico per indicare qualsiasi metodo di archiviazione impiegato per tracciare il token CrowdHandler degli utenti, ma devi prestare attenzione a qualunque mezzo tu stia utilizzando per il tracciamento delle sessioni.

1. Mancata impostazione di un cookie leggibile

La tua integrazione deve memorizzare il token CrowdHandler dell'utente al momento del primo reindirizzamento al tuo sito. Non puoi fare affidamento sulla presenza del token nell'URL dopo la prima visita successiva al reindirizzamento dalla sala d'attesa. Dovrai assicurarti che il cookie sia impostato. Assicurati di impostare un cookie che la tua applicazione possa leggere dai percorsi successivi che l'utente potrebbe visitare.

2. Impossibilità di impostare il cookie a causa di un HTTP

Il motivo più comune per cui un’integrazione non riesce a impostare un cookie è che un reindirizzamento HTTP intercetta l’utente prima ancora che l’integrazione venga eseguita, reindirizzandolo verso una nuova pagina senza trasmettere il token nell’URL. Queste regole di reindirizzamento potrebbero essere presenti nella configurazione del server web oppure potrebbero essere eseguite nelle prime fasi del percorso di esecuzione del codice per gestire i reindirizzamenti relativi alla lingua o all’accesso. Pertanto, se si ha a che fare con un sito multilingue o si sta proteggendo un percorso che prevede l’accesso dell’utente, è necessario prestare particolare attenzione. La soluzione consiste nell’assicurarsi che i reindirizzamenti includano la stringa di query con il token, oppure nel verificare di non inviare gli utenti direttamente dalla "sala d’attesa" a un URL che effettuerà immediatamente un reindirizzamento.

È disponibile un articolo dedicato nella Knowledge Base su questo problema. Leggilo per comprenderlo meglio. Sebbene l'articolo sia rivolto principalmente agli utenti dell'integrazione JavaScript, potresti riprodurre questo problema nella tua integrazione.

3. Mancato aggiornamento del

Esistono motivi legittimi per cui un utente potrebbe ritrovarsi a passare attraverso la coda più di una volta, oppure potrebbe verificarsi la scadenza della sua sessione e l'emissione di un nuovo token. Per questo motivo, è importante che ogni volta che si nota un token di Crowdhandler nell'URL, o quando l'API restituisce un nuovo token, si aggiorni il cookie di conseguenza. In caso contrario, l'integrazione potrebbe utilizzare un token scaduto, reindirizzando l'utente alla coda.

Quindi, nel tuo codice di integrazione, cerca un token nell'URL. Se ne trovi uno, effettua la chiamata utilizzando il token presente nell'URL anziché quello che potresti trovare in un cookie. In entrambi i casi, considera attendibile il token ben formato restituito dall'API e imposta il cookie.

4. Eliminazione del cookie o impostazione di un non valido

Quando si esamina l’URL o si analizza la risposta dell’API per verificare se è necessario aggiornare il cookie dell’utente, occorre prestare attenzione a non consentire che un bug presente nel codice imposti accidentalmente un valore nullo, vuoto o falso. Alcuni framework interpreteranno questa situazione come una cancellazione del cookie e, in ogni caso, se l’utente invia un token non valido nella richiesta successiva, gli verrà assegnato un nuovo token, con la conseguenza che verrà reindirizzato in fondo alla coda.

5. Mancata impostazione di un cookie quando si reindirizza l'utente alla sala d'attesa.

A rigor di termini, non è necessario impostare un cookie se si intende reindirizzare l’utente alla sala d’attesa. Tuttavia, la vostra integrazione risulterà molto più solida se imposterete sempre un cookie. Questo perché l’utente potrebbe ritrovarsi in qualche modo sul sito prima di aver completato il proprio percorso attraverso la sala d’attesa. Se lo riconosci ancora, verrà reindirizzato alla sala d’attesa, mantenendo la sua posizione originale. In caso contrario, verrà reindirizzato alla 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 nuovamente ad accedere al sito, magari in una nuova scheda. Soprattutto se ha ricevuto un link via e-mail alla pagina protetta.

6. Impostare una data di scadenza inadeguata per i cookie o fare affidamento sulla temporanea della sessione

Considerando lo scenario sopra descritto, il timeout standard di 20 minuti associato alla memorizzazione delle sessioni integrata fornita da framework come .NET o PHP potrebbe non essere sufficientemente affidabile in questo caso. In caso di dubbio, imposta un cookie di sessione o un cookie permanente.

relativi alle API

Prenditi il tempo necessario per comprendere i parametri che stai inviando e le risposte che potresti ricevere. Questi sono i principali problemi che riscontriamo nelle richieste e nelle risposte delle API:

1. Invio di un indirizzo IP errato all'

Quando invii l'IP alla risorsa richiesta, assicurati di inviare l'IP dell'utente e non quello del tuo server o di un server proxy intermedio. Se invii lo stesso IP più volte, è probabile che tale IP venga identificato e bloccato. Se ti trovi in questa situazione in un ambiente di produzione, puoi impostare quell’IP o quell’intervallo di indirizzi su “ignora”, il che impedirà il blocco automatico, ma dovresti testare e correggere la tua integrazione per identificare l’IP corretto. In genere, se il tuo server web si trova dietro un proxy, puoi rilevare l’IP reale dall’intestazione HTTP X-Forwarded-For. Potresti trovare utile questa guida.

2. Supponendo che l'API risponda

La ragion d’essere di CrowdHandler è quella di essere disponibile quando il tuo sito non lo è. Tuttavia, esistono molte ragioni legittime per cui il tuo server potrebbe essere temporaneamente impossibilitato a connettersi all’API di CrowdHandler, tra cui problemi generali di routing su Internet o problemi relativi al data center. Se il tuo codice presuppone che riceverai sempre una risposta ben formata, è probabile che, qualora si verifichino queste situazioni, venga visualizzato un brutto messaggio di errore all’utente. Soluzioni:

  • Quando si effettua la chiamata all'API, specificare un timeout breve (2 secondi è l'ideale)
  • Se la chiamata va in timeout o la risposta non è correttamente formattata, valuta come procedere. Nella maggior parte dei casi sarà opportuno fidarsi di questo utente e consentirgli l'accesso all'URL, poiché ciò significa che, se l'interruzione si verifica mentre non è in esecuzione alcuna coda, l'utente non subirà alcun disservizio. In scenari di bassa affidabilità, potresti voler indirizzare 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 fino a quando non riceverà una risposta corretta dall'API.

3. Presupponendo il della risposta

Nella maggior parte dei casi riceverai una risposta dettagliata, che include messaggi da inviare nella 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 poche informazioni.

Ad esempio, se si verifica una richiesta relativa a un URL che non è protetto da alcuna sala d'attesa di CrowdHandler.

{
    "result": {
        "status": 0,
        "token": null,
        "responseID": null,
        "promoted": 1
    }
}

Altre risposte che potresti ricevere sono: la tua chiave non è valida (errore HTTP 401), la sala è piena (Stato: 5) oppure l'indirizzo IP da cui stai inviando la richiesta è stato inserito nell'elenco dei blocchi (Stato: 4).

Soluzioni:

  • Prenditi un po’ di tempo per capire il significato dei codici di risposta che ricevi. Si tratta di situazioni che potresti dover prendere in considerazione.
  • Per stabilire se all'utente debba essere concesso l'accesso o se debba essere indirizzato alla sala d'attesa, è sufficiente verificare l'attributo booleano "promoted", che, a meno che non si verifichi un errore, sarà sempre presente e assumerà il valore 0 o 1. Se la tua integrazione è molto semplice e ti limiti a controllare questo attributo, non è necessario comprendere le varie risposte e gli stati, poiché se "promoted" è pari a 0, puoi indirizzare l'utente alla sala d'attesa, che saprà come gestire la situazione.
  • Se hai sviluppato un'applicazione o utilizzi un framework che, per ragioni legate alla programmazione orientata agli oggetti, richiede che l'oggetto di risposta sia sempre coerente, dovresti partire da un tuo oggetto o classe di base che rappresenti la risposta, specificando valori predefiniti ragionevoli, e poi impostare solo i valori restituiti dalla risposta dell'API.