Ce guide décrit les problèmes courants et les solutions à apporter lors de l'élaboration manuelle d'une intégration basée sur une API. Vous devrez adapter ces conseils à votre application et à vos cadres particuliers.
Nous ne sommes pas en mesure de fournir une assistance pour les intégrations personnalisées par le biais des canaux d'assistance habituels, car de nombreux facteurs échappent à notre contrôle. L'écriture d'une intégration personnalisée est relativement simple - mais vous devez être un développeur expérimenté ayant une bonne connaissance des éléments essentiels du protocole HTTP.
Pour voir des exemples d'intégrations testées dans le monde réel qui traitent de tous les problèmes décrits ci-dessous, vous pouvez consulter nos intégrations sur GitHub :
- https://github.com/Crowdhandler/crowdhandler-cloudflare-integration
- https://github.com/Crowdhandler/crowdhandler-php-sdk
Questions relatives à l'exclusion de l'URL
Si votre application dispose d'un contrôleur frontal, il se peut que vous acheminiez toutes les requêtes vers votre application par le biais d'une intégration qui vérifie avec CrowdHandler pour autoriser ou interdire les requêtes URL individuelles. Cela peut entraîner les deux problèmes suivants :
1. Vérifier les URL inutiles
Lorsqu'un utilisateur charge une page, le navigateur charge toutes les ressources associées à la page sur votre domaine, et il est possible que ces requêtes passent par votre contrôleur frontal. Il est possible que ces requêtes transitent par votre contrôleur frontal, ce qui peut entraîner des vérifications inutiles, qui augmenteront le temps de chargement et, en fin de compte, la charge du serveur de votre application. Vous devez exclure au moins ces extensions de fichiers courantes avant de vérifier une URL :
.css. gif .ico .jpg .jpeg .js .json .mov .mp4 .mpeg .mpg .png .svg .ttf .otf .eot .woff .woff2
Vous devez également exclure tous les autres chemins d'accès de vos applications qui se rapportent à des contenus ne nécessitant pas la protection de la salle d'attente. Par exemple, si vous stockez toutes les ressources statiques dans un sous-répertoire appelé /static, vous pouvez exclure ce chemin des contrôles.
2. Blocage des services tiers dans la file d'attente
Si vous utilisez un contrôleur frontal comme ci-dessus et que vous avez des services tiers qui appellent des API sur votre domaine protégé, ces services seront probablement pris dans la file d'attente et ne progresseront pas car il est peu probable qu'ils acceptent les cookies. Les services tiers les plus courants susceptibles d'être bloqués sont les suivants :
- Services, plugins ou applications qui consomment des API sur votre domaine (RPC, REST)
- Services de paiement qui effectuent des rappels côté serveur vers votre domaine pour confirmer les transactions.
Si les services utilisent une plage d'adresses IP étroitement définie, vous pouvez les autoriser à passer en ajoutant la plage d'adresses IP à une règle de contournement. Toutefois, il est généralement préférable d'exclure d'emblée ces URL de vos contrôles.
3. Bloquer les URL d'administration
Si vous vous connectez à votre application backend ou à votre CMS via des urls telles que /admin, vous pouvez également souhaiter exclure ces urls. Il peut être aussi efficace de paramétrer votre bureau ou les IP VPN pour qu'elles soient contournées.
Questions relatives aux cookies
Le problème le plus important que nous rencontrons avec les intégrations personnalisées est l'impossibilité de définir un cookie pour garder une trace du jeton CrowdHandler de l'utilisateur.
Vous pouvez utiliser des cookies ou une autre forme de stockage de session côté navigateur ou serveur. Ici, nous utilisons les cookies comme un terme fourre-tout pour toute méthode de stockage que vous utilisez pour suivre le jeton CrowdHandler de l'utilisateur, mais vous devez faire attention quel que soit le support que vous utilisez pour enregistrer les sessions.
1. Ne pas mettre en place un Cookie lisible
Votre intégration doit stocker le jeton CrowdHandler de l'utilisateur lorsqu'il est redirigé pour la première fois vers votre site. Vous ne pouvez pas compter sur le fait que le jeton se trouve dans l'URL après le premier clic après la redirection depuis la salle d'attente. Vous devrez vous assurer que le cookie est activé. Assurez-vous que vous définissez un cookie que votre application peut lire à partir des chemins d'accès ultérieurs que l'utilisateur peut visiter.
2. Échec de la définition des cookies en raison d'une redirection HTTP
La raison la plus fréquente pour laquelle une intégration ne parvient pas à définir un cookie est qu'une redirection HTTP attrape l'utilisateur avant même que votre intégration ne s'exécute, et redirige l'utilisateur vers une nouvelle route sans passer le jeton dans l'URL. Ces règles de redirection peuvent se trouver dans la configuration de votre serveur web, ou peuvent être exécutées au début de votre chemin de code pour gérer les redirections de langue ou de connexion. Par conséquent, si vous avez affaire à un site multilingue ou si vous protégez un chemin qui implique la connexion de l'utilisateur, faites preuve d'une grande prudence. La solution est de s'assurer que les redirections incluent la chaîne de requête avec le jeton, ou de s'assurer que vous n'envoyez pas les utilisateurs directement de la salle d'attente vers une url qui sera immédiatement redirigée.
Un article de la base de connaissances est consacré à ce problème. Lisez-le pour mieux le comprendre. Bien que cet article s'adresse principalement aux utilisateurs de l'intégration JavaScript, vous pouvez recréer ce problème dans votre propre intégration.
3. Absence de mise à jour du cookie
Il existe des raisons légitimes pour lesquelles un utilisateur peut se retrouver dans la file d'attente plus d'une fois, ou que sa session expire et qu'il reçoive un nouveau jeton. Pour cette raison, il est important que chaque fois que vous voyez un jeton crowdhandler dans l'URL, ou qu'un nouveau jeton revient de l'API, vous mettiez à jour le cookie pour qu'il corresponde. Sinon, votre intégration peut utiliser un jeton expiré, renvoyant l'utilisateur dans la file d'attente.
Dans votre code d'intégration, recherchez donc un jeton dans l'URL. Si vous en trouvez un, faites l'appel avec le jeton dans l'URL en faveur de tout jeton que vous pourriez trouver dans un cookie. Ensuite, dans les deux cas, faites confiance au jeton bien formé qui revient de l'API et définissez le cookie.
4. Suppression du cookie ou définition d'une valeur malformée
Lorsque vous regardez l'URL ou que vous analysez la réponse de l'API pour voir si vous devez mettre à jour le cookie de l'utilisateur, veillez à ne pas laisser un bogue quelque part dans votre code définir accidentellement une valeur nulle, vide ou fausse. Certains frameworks interpréteront cela comme une suppression de cookie et, dans tous les cas, si l'utilisateur soumet un jeton invalide lors de sa prochaine demande, il recevra un nouveau jeton, ce qui le renverra à la fin de la file d'attente.
5. Ne pas définir de cookie lorsque vous redirigez l'utilisateur vers la salle d'attente.
Strictement parlant, il n'est pas nécessaire d'installer un cookie si vous allez rediriger cet utilisateur vers la salle d'attente. Toutefois, votre intégration sera beaucoup plus solide si vous placez toujours un cookie. En effet, l'utilisateur peut se retrouver sur le site d'une manière ou d'une autre avant d'avoir terminé son parcours dans la salle d'attente. Si vous le reconnaissez toujours, il sera renvoyé dans la salle d'attente, conservant ainsi sa position initiale. Dans le cas contraire, il sera renvoyé dans la salle d'attente avec une nouvelle position à la fin de la file d'attente. Si un utilisateur reste longtemps dans une salle d'attente, il n'est pas rare qu'il réessaie le site, éventuellement dans un nouvel onglet. Surtout s'il a reçu par courriel un lien vers la page protégée.
6. Fixer une date d'expiration inappropriée pour votre cookie, ou s'appuyer sur un stockage temporaire de la session
Si l'on considère le scénario ci-dessus, le délai typique de 20 minutes associé au stockage de session intégré fourni par des cadres tels que .Net ou PHP peut ne pas être suffisamment robuste pour ce scénario. En cas de doute, définissez un cookie de session ou un cookie permanent.
Questions relatives à l'API
Prenez le temps de comprendre les paramètres que vous envoyez et les réponses que vous pouvez recevoir. Voici les principaux problèmes que nous rencontrons avec les demandes et les réponses de l'API :
1. Envoi d'une mauvaise adresse IP à l'API
Lorsque vous envoyez l'IP à la ressource demandée, assurez-vous que vous envoyez l'IP de l'utilisateur et non l'IP de votre serveur ou l'IP d'un serveur proxy intermédiaire. Si vous envoyez plusieurs fois la même adresse IP, celle-ci risque d'être identifiée et bloquée. Si vous êtes confronté à ce problème dans un environnement réel, vous pouvez définir cette IP ou cette plage comme "ignorée", ce qui empêchera le blocage automatique, mais vous devez tester et corriger votre intégration afin d'identifier l'IP correcte. Généralement, si votre serveur web se trouve derrière un proxy, vous pouvez détecter l'IP réelle à partir de l'en-tête HTTP X-Forwarded-For. Ce guide peut vous être utile.
2. En supposant que l'API répondra
La raison d'être de CrowdHandler est d'être disponible lorsque votre site ne l'est pas. Cependant, il existe de nombreuses raisons légitimes pour lesquelles votre serveur peut être temporairement incapable de se connecter à l'API de CrowdHandler, y compris des problèmes de routage Internet général ou des problèmes de centre de données. Si votre code suppose que vous recevrez toujours une réponse bien formée, il est probable que vous affichiez une vilaine erreur à l'utilisateur si et quand ces situations se produisent. Solutions :
- Lors de l'appel à l'API, spécifiez un délai d'attente court (2 secondes est le délai optimal).
- Si l'appel n'aboutit pas ou si la réponse n'est pas bien formée, réfléchissez à ce que vous voulez faire. Dans la majorité des cas, vous voudrez faire confiance à cet utilisateur et autoriser l'accès à l'url, car cela signifie que si la panne survient alors que vous ne gérez pas de file d'attente, l'utilisateur ne sera pas perturbé. La salle d'attente CrowdHandler tentera d'établir une connexion API et fera de son mieux avec l'utilisateur jusqu'à ce qu'elle reçoive une réponse en bonne et due forme de l'API.
3. Présumer le format de la réponse
Dans la majorité des cas, vous recevrez une réponse détaillée, y compris la messagerie de la salle d'attente, etc. En voici un exemple :
{
"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
}
}
Toutefois, certains statuts ne fournissent que peu d'informations.
Par exemple, si vous vérifiez une demande pour une URL qui n'est pas protégée par une salle d'attente CrowdHandler.
{
"result": {
"status": 0,
"token": null,
"responseID": null,
"promoted": 1
}
}D'autres réponses peuvent apparaître si votre clé n'est pas valide (erreur 401 HTTP), si la salle est pleine (Statut : 5) ou si l'adresse IP que vous envoyez a été placée sur la liste des adresses bloquées (Statut : 4).
Solutions :
- Prenez le temps de comprendre la signification des codes de réponse qui vous sont renvoyés. Il s'agit de situations que vous devrez peut-être envisager.
- Pour savoir si l'utilisateur doit se voir accorder l'accès ou être envoyé dans la salle d'attente, il suffit de vérifier l'attribut booléen promoted qui, sauf erreur, sera toujours présent et égal à 0 ou 1. Si votre intégration est très simple et que vous ne regardez que cet attribut, vous n'avez pas vraiment besoin de comprendre les différentes réponses et les différents statuts, car si promoted vaut 0, vous pouvez envoyer l'utilisateur dans la salle d'attente, et cette dernière saura quoi faire.
- Si vous avez construit une application ou si vous utilisez un cadre qui exige que l'objet de la réponse soit toujours cohérent pour des raisons d'OO, vous devriez commencer par créer votre propre objet ou classe de base pour représenter la réponse, en spécifiant des valeurs par défaut raisonnables, puis définir uniquement les valeurs qui proviennent de la réponse de l'API.