Dépannage des intégrations d'API personnalisées

Ce guide décrit les problèmes courants et les solutions à adopter lors de la mise en place manuelle d'une intégration basée sur une API. Vous devrez adapter ces conseils à votre application et à vos frameworks spécifiques.

Nous ne sommes pas en mesure d'assurer l'assistance pour les intégrations personnalisées via les canaux d'assistance habituels, car de nombreux facteurs échappent à notre contrôle. La création d'une intégration personnalisée est relativement simple, mais elle nécessite d'être un développeur expérimenté maîtrisant bien les principes fondamentaux du protocole HTTP.

Pour découvrir des exemples d'intégrations testées en conditions réelles qui répondent à tous les enjeux décrits ci-dessous, vous pouvez consulter nos intégrations sur GitHub :

liés à l'exclusion d'URL#

Si votre application dispose d'un contrôleur frontal, il se peut que vous acheminiez toutes les requêtes vers votre application via une intégration qui interroge CrowdHandler afin d'autoriser ou de refuser des requêtes URL spécifiques. Cela peut entraîner les deux problèmes suivants :

1. Vérification des inutiles#

Lorsqu'un utilisateur charge une page, le navigateur charge tous les ressources associées à cette page hébergées sur votre domaine, et il est possible que ces requêtes transitent par votre contrôleur frontal. Cela peut entraîner des vérifications inutiles, ce qui allonge le temps de chargement et, au final, augmente la charge du serveur de votre application. Il est donc recommandé d'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 de vos applications tout autre chemin d'accès correspondant à du contenu ne nécessitant pas de protection par « salle d'attente ». Par exemple, si vous stockez toutes vos ressources statiques dans un sous-répertoire nommé /static, vous pouvez exclure ce chemin d'accès des vérifications.

2. Blocage des services tiers dans la file

Si vous utilisez un contrôleur frontal comme indiqué ci-dessus et que vous disposez de services tiers qui appellent des API sur votre domaine protégé, ces services risquent d'être bloqués dans la file d'attente et ne pourront pas aboutir, car ils sont peu susceptibles d'accepter les cookies. Parmi les services tiers courants susceptibles d'être bloqués, on peut citer :

  1. Services, plugins ou applications qui utilisent les API de votre domaine (RPC, REST)
  2. Services de paiement qui effectuent des rappels côté serveur vers votre domaine afin de valider les transactions.

Si les services utilisent une plage d'adresses IP bien définie, vous pouvez éventuellement les autoriser en ajoutant cette plage à une règle de contournement. Cependant, il est généralement préférable d'exclure d'emblée ces URL de vos vérifications.

3. Bloquer vos d'administration#

Si vous vous connectez à votre application backend ou à votre CMS via des URL telles que /admin, vous souhaiterez peut-être exclure ces URL également. Il peut être tout aussi efficace de configurer les adresses IP de votre bureau ou de votre VPN pour qu'elles ne soient pas bloquées.

liés aux cookies#

Le principal problème que nous constatons avec les intégrations personnalisées est peut-être l'impossibilité de définir correctement un cookie permettant de suivre le jeton CrowdHandler de l'utilisateur.

Vous utilisez peut-être des cookies, ou bien une autre forme de stockage de session côté navigateur ou côté serveur. Dans ce document, nous utilisons le terme « cookies » de manière générique pour désigner toute méthode de stockage que vous utilisez pour suivre le jeton CrowdHandler des utilisateurs, mais vous devez faire attention, quel que soit le support que vous utilisez pour le suivi des sessions.

1. Absence de définition d'un lisible

Votre intégration doit enregistrer le jeton CrowdHandler de l'utilisateur lors de sa première redirection vers votre site. Vous ne pouvez pas compter sur la présence du jeton dans l'URL après la première visite suivant la redirection depuis la salle d'attente. Vous devrez vous assurer que le cookie est bien défini. Veillez à définir un cookie que votre application pourra lire à partir des chemins d'accès suivants que l'utilisateur est susceptible de parcourir.

2. Échec de la création d'un cookie en raison d'une HTTP

La raison la plus courante pour laquelle une intégration ne parvient pas à définir un cookie est qu’une redirection HTTP intercepte l’utilisateur avant même que votre intégration ne s’exécute, et le redirige vers une nouvelle route sans transmettre le jeton dans l’URL. Ces règles de redirection peuvent figurer dans la configuration de votre serveur web, ou être exécutées en début de votre chemin d’exécution pour gérer les redirections liées à la langue ou à la connexion. Si vous gérez un site multilingue ou si vous protégez un chemin impliquant la connexion de l’utilisateur, soyez donc particulièrement vigilant. La solution consiste à vous assurer que les redirections incluent la chaîne de requête contenant le jeton, ou à veiller à ne pas envoyer les utilisateurs directement depuis la salle d'attente vers une URL qui les redirigera immédiatement.

Il existe un article dédié à ce sujet dans la base de connaissances. Nous vous invitons à le consulter pour mieux comprendre le problème. Bien que cet article s'adresse principalement aux utilisateurs de l'intégration JavaScript, vous pouvez reproduire ce problème dans votre propre intégration.

3. Non-mise à jour du

Il existe des raisons légitimes pour lesquelles un utilisateur peut se retrouver à passer par la file d'attente plusieurs fois, ou voir sa session expirer et se voir attribuer un nouveau jeton. C'est pourquoi il est important, chaque fois que vous repérez un jeton « crowdhandler » dans l'URL, ou lorsqu'un nouveau jeton est renvoyé par l'API, de mettre à jour le cookie en conséquence. Sinon, votre intégration risque d'utiliser un jeton expiré, ce qui renverrait 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, effectuez l'appel en utilisant ce jeton dans l'URL plutôt que celui que vous pourriez trouver dans un cookie. Ensuite, dans les deux cas, faites confiance au jeton correctement formé renvoyé par l'API et définissez le cookie.

4. Suppression du cookie ou définition d'une incorrecte

Lorsque vous examinez l'URL ou que vous analysez la réponse de l'API pour déterminer si vous devez mettre à jour le cookie de l'utilisateur, veillez à ce qu'un bug présent quelque part dans votre code ne provoque pas accidentellement l'attribution d'une valeur nulle, vide ou fausse. Certains frameworks interpréteront cela comme une suppression du cookie ; de toute façon, si l'utilisateur envoie un jeton non valide lors de sa prochaine requête, un nouveau jeton lui sera attribué, ce qui le renverra en fin de file d'attente.

5. Ne pas créer de cookie lors de la redirection de l'utilisateur vers la salle d'attente.

À proprement parler, il n’est pas nécessaire de définir un cookie si vous comptez rediriger cet utilisateur vers la salle d’attente. Cependant, votre intégration sera bien plus robuste si vous définissez systématiquement un cookie. En effet, l’utilisateur pourrait 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é vers la salle d'attente en conservant sa position initiale. Dans le cas contraire, il sera renvoyé vers la salle d'attente avec une nouvelle position, à la fin de la file d'attente. Lorsqu'un utilisateur reste longtemps dans une salle d'attente, il n'est pas rare qu'il tente à nouveau d'accéder au site, éventuellement dans un nouvel onglet. C'est particulièrement vrai s'il a reçu par e-mail un lien vers la page protégée.

6. Définir une date d'expiration inappropriée pour votre cookie, ou recourir au temporaire de session

Compte tenu du scénario décrit ci-dessus, le délai d'expiration standard de 20 minutes associé au stockage de session intégré fourni par des frameworks tels que .NET ou PHP pourrait ne pas être suffisamment fiable dans ce cas de figure. En cas de doute, définissez un cookie de session ou un cookie permanent.

liés à l'API#

Prenez le temps de bien comprendre les paramètres que vous envoyez et les réponses que vous pourriez recevoir. Voici les principaux problèmes que nous constatons concernant les requêtes et les réponses API :

1. Envoi d'une adresse IP erronée à l'

Lorsque vous transmettez l’adresse IP à la ressource sollicitée, assurez-vous d’envoyer l’adresse IP de l’utilisateur, et non celle de votre serveur ni celle d’un serveur proxy intermédiaire. Si vous transmettez la même adresse IP à plusieurs reprises, celle-ci risque d’être identifiée et bloquée. Si vous rencontrez ce problème en production, vous pouvez configurer cette adresse IP ou cette plage d’adresses pour qu’elle soit « ignorée », ce qui empêchera le blocage automatique ; toutefois, vous devez tester et corriger votre intégration afin d’identifier la bonne adresse IP. En général, si votre serveur web est derrière un proxy, vous pouvez détecter l’adresse IP réelle à partir de l’en-tête HTTP X-Forwarded-For. Ce guide pourrait vous être utile.

2. En supposant que l'API

La raison d’être de CrowdHandler est d’être disponible lorsque votre site ne l’est pas. Il existe toutefois de nombreuses raisons légitimes pour lesquelles votre serveur peut être temporairement incapable de se connecter à l’API CrowdHandler, notamment des problèmes généraux de routage Internet ou des dysfonctionnements au niveau du centre de données. Si votre code part du principe que vous recevrez toujours une réponse bien formée, vous risquez d’afficher un message d’erreur peu esthétique à l’utilisateur lorsque ces situations se produisent. Solutions :

  • Lors de l'appel de l'API, spécifiez un délai d'expiration court (2 secondes est la durée optimale)
  • Si l'appel expire ou si la réponse n'est pas correctement formée, réfléchissez à la marche à suivre. Dans la plupart des cas, vous aurez intérêt à faire confiance à cet utilisateur et à lui accorder l'accès à l'URL, car cela signifie que si une panne survient alors que vous ne gérez pas de file d'attente, l'utilisateur ne subira aucune interruption. Dans les scénarios où le niveau de confiance est faible, vous pouvez choisir de rediriger l'utilisateur vers la salle d'attente : la salle d'attente de CrowdHandler tentera d'établir une connexion à l'API et fera de son mieux pour gérer l'utilisateur jusqu'à ce qu'elle reçoive une réponse valide de l'API.

3. Supposer le de la réponse

Dans la plupart des cas, vous recevrez une réponse détaillée, comprenant notamment des messages destinés à 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
    }
}

Cependant, certaines publications ne fournissent que peu d'informations.

Par exemple, si vous vérifiez une requête concernant une URL qui n'est protégée par aucune salle d'attente CrowdHandler.

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

D'autres réponses peuvent s'afficher si votre clé n'est pas valide (erreur HTTP 401), si la salle est pleine (statut : 5) ou si l'adresse IP à partir de laquelle vous envoyez la requête figure sur la liste des adresses bloquées (statut : 4).

Solutions :

  • Prenez le temps de comprendre la signification des codes de réponse renvoyés. Voici quelques situations que vous devrez peut-être prendre en compte.
  • Pour déterminer si l'utilisateur doit se voir accorder l'accès ou être redirigé vers la salle d'attente, il vous suffit de vérifier l'attribut booléen « promoted », qui, sauf en cas d'erreur, sera toujours présent et prendra la valeur 0 ou 1. Si votre intégration est très simple et que vous vous contentez d'examiner cet attribut, vous n'avez pas vraiment besoin de comprendre les différentes réponses et états, car si « promoted » vaut 0, vous pouvez envoyer l'utilisateur dans la salle d'attente, et celle-ci saura quoi faire.
  • Si vous avez développé une application ou si vous utilisez un framework qui exige, pour des raisons liées à la programmation orientée objet, que l'objet de réponse reste cohérent à tout moment, 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 pertinentes, puis ne définir que les valeurs renvoyées par la réponse de l'API.