Solución de problemas en las integraciones de API personalizadas

Esta guía describe los problemas más habituales y sus soluciones a la hora de desarrollar manualmente una integración basada en una API. Deberás adaptar estos consejos a tu aplicación y a tus marcos de trabajo concretos.

No podemos ofrecer asistencia para integraciones personalizadas a través de los canales habituales de asistencia, ya que hay muchos factores que escapan a nuestro control. Crear una integración personalizada es relativamente sencillo, pero es necesario ser un desarrollador con experiencia y tener un buen dominio de los conceptos básicos de HTTP.

Para ver ejemplos de integraciones probadas en la práctica que abordan todas las cuestiones que se describen a continuación, puedes consultar nuestras integraciones en GitHub:

con la exclusión de URL#

Si tu aplicación cuenta con un controlador principal, es posible que estés redirigiendo todas las solicitudes a tu aplicación a través de una integración que consulta con CrowdHandler para permitir o denegar solicitudes de URL concretas. Esto puede dar lugar a los dos problemas siguientes:

1. Comprobación de innecesarias#

Cuando un usuario carga una página, el navegador carga todos los recursos asociados a la página que se encuentran en tu dominio, y es posible que estas solicitudes se redirijan a través de tu controlador principal. Esto puede provocar que se realicen comprobaciones innecesarias, lo que aumentará el tiempo de carga y, en última instancia, la carga del servidor de tu aplicación. Te conviene excluir al menos estas extensiones de archivo habituales antes de comprobar una URL:

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

También debes excluir cualquier otra ruta de tus aplicaciones que esté relacionada con contenido que no requiera protección mediante la sala de espera. Por ejemplo, si almacenas todos los recursos estáticos en un subdirectorio llamado /static, puedes excluir esa ruta de las comprobaciones.

2. Bloqueo de servicios de terceros en la

Si utilizas un controlador frontal como el descrito anteriormente y dispones de servicios de terceros que realizan llamadas a las API de tu dominio protegido, es probable que estos servicios queden retenidos en la cola y no puedan continuar, ya que es poco probable que acepten cookies. Entre los servicios de terceros más habituales que pueden verse bloqueados se incluyen:

  1. Servicios, complementos o aplicaciones que utilizan las API de tu dominio (RPC, REST)
  2. Servicios de pago que realizan llamadas de retorno del lado del servidor a tu dominio para confirmar las transacciones.

Si los servicios utilizan un rango de direcciones IP bien definido, es posible que puedas permitir su acceso añadiendo dicho rango mediante una regla de excepción. Sin embargo, por lo general es preferible excluir estas URL de tus comprobaciones desde el principio.

3. Bloqueo de las de administración

Si accedes a tu aplicación de backend o CMS a través de direcciones URL como /admin, quizá te interese excluir también estas direcciones. Puede resultar igual de eficaz configurar las direcciones IP de tu oficina o de tu VPN para que se salten el bloqueo.

con las cookies#

Quizás el mayor problema que observamos con las integraciones personalizadas es la imposibilidad de establecer correctamente una cookie para realizar un seguimiento del token de CrowdHandler del usuario.

Es posible que estés utilizando cookies o que utilices otro tipo de almacenamiento de sesiones, ya sea en el navegador o en el servidor. Aquí utilizamos el término «cookies» como término genérico para referirnos a cualquier método de almacenamiento que utilices para realizar el seguimiento del token de CrowdHandler de los usuarios, pero debes tener cuidado independientemente del medio que utilices para el seguimiento de las sesiones.

1. No se ha configurado una legible

Tu integración debe almacenar el token CrowdHandler del usuario la primera vez que este sea redirigido a tu sitio web. No puedes dar por hecho que el token vaya a aparecer en la URL tras la primera visita tras la redirección desde la sala de espera. Deberás asegurarte de que la cookie esté configurada. Asegúrate de configurar una cookie que tu aplicación pueda leer desde las rutas posteriores que el usuario pueda visitar.

2. No se ha podido establecer la cookie debido a una HTTP

La razón más habitual por la que una integración no consigue establecer una cookie es que una redirección HTTP intercepta al usuario antes incluso de que se ejecute la integración y lo redirige a una nueva ruta sin pasar el token en la URL. Estas reglas de redirección pueden estar en la configuración de tu servidor web o ejecutarse al principio de la ruta de tu código para gestionar redirecciones de idioma o de inicio de sesión. Por lo tanto, si trabajas con un sitio web multilingüe o proteges una ruta que implica el inicio de sesión del usuario, presta especial atención. La solución consiste en asegurarte de que las redirecciones incluyan la cadena de consulta con el token, o de que no envíes a los usuarios directamente desde la sala de espera a una URL que los redirija de inmediato.

Hay un artículo específico de la base de conocimientos sobre este problema. Léelo para comprenderlo mejor. Aunque este artículo está dirigido principalmente a los usuarios de la integración de JavaScript, puedes reproducir este problema en tu propia integración.

3. No actualizar la

Existen motivos legítimos por los que un usuario puede verse obligado a pasar por la cola más de una vez, o puede que su sesión caduque y se le asigne un nuevo token. Por este motivo, es importante que, cada vez que veas un token de Crowdhandler en la URL, o cuando la API te devuelva un nuevo token, actualices la cookie para que coincida. De lo contrario, tu integración podría utilizar un token caducado, lo que haría que el usuario volviera a la cola.

Así pues, en tu código de integración, busca un token en la URL. Si encuentras uno, realiza la llamada utilizando el token de la URL en lugar del token que puedas encontrar en una cookie. A continuación, en cualquier caso, confía en el token válido que devuelve la API y configura la cookie.

4. Eliminar la cookie o establecer un incorrecto#

Al examinar la URL o analizar la respuesta de la API para comprobar si debes actualizar la cookie del usuario, ten cuidado de no permitir que un error en algún punto de tu código establezca accidentalmente un valor nulo, vacío o falso. Algunos marcos de trabajo interpretarán esto como una eliminación de la cookie y, en cualquier caso, si el usuario envía un token no válido en su siguiente solicitud, se le asignará un nuevo token, lo que hará que pase al final de la cola.

5. No establecer una cookie al redirigir al usuario a la sala de espera.

En sentido estricto, no es necesario establecer una cookie si vas a redirigir a este usuario a la sala de espera. Sin embargo, tu integración será mucho más robusta si siempre estableces una cookie. Esto se debe a que el usuario podría volver al sitio web de alguna manera antes de completar su recorrido por la sala de espera. Si aún lo reconoces, se le redirigirá de nuevo a la sala de espera, manteniendo su posición original. Si no lo reconoces, se le redirigirá de nuevo a la sala de espera con una nueva posición al final de la cola. Si un usuario permanece en la sala de espera durante mucho tiempo, no es raro que vuelva a intentar acceder al sitio web, quizá en una nueva pestaña. Especialmente si ha recibido un enlace por correo electrónico a la página protegida.

6. Establecer una fecha de caducidad inadecuada para la cookie o basarse en temporal de la sesión

Teniendo en cuenta el caso anterior, es posible que el tiempo de espera habitual de 20 minutos asociado al almacenamiento de sesiones integrado que ofrecen marcos de trabajo como .NET o PHP no sea lo suficientemente robusto para esta situación. En caso de duda, configura una cookie de sesión o una cookie permanente.

con la API#

Tómate tu tiempo para comprender los parámetros que estás enviando y las respuestas que puedes recibir. Estos son los principales problemas que observamos en las solicitudes y respuestas de las API:

1. Envío de una dirección IP incorrecta a la

Cuando envíes la dirección IP al recurso solicitado, asegúrate de que estás enviando la dirección IP del usuario, y no la de tu servidor ni la de un servidor proxy intermediario. Si envías la misma dirección IP muchas veces, es probable que esa dirección sea identificada y bloqueada. Si te enfrentas a esta situación en un entorno de producción, puedes configurar esa dirección IP o rango para que se «ignore», lo que evitará el bloqueo automático; no obstante, deberías probar y corregir tu integración para identificar la dirección IP correcta. Normalmente, si tu servidor web está detrás de un proxy, puedes detectar la dirección IP real a partir del encabezado HTTP X-Forwarded-For. Quizás te resulte útil esta guía.

2. Suponiendo que la API

La razón de ser de CrowdHandler es estar disponible cuando tu sitio web no lo está. Sin embargo, existen muchas razones legítimas por las que tu servidor podría no poder conectarse temporalmente a la API de CrowdHandler, entre ellas problemas generales de enrutamiento de Internet o incidencias en el centro de datos. Si tu código da por hecho que siempre recibirás una respuesta bien formada, es probable que se muestre un error antiestético al usuario cuando se produzcan estas situaciones. Soluciones:

  • Al realizar la llamada a la API, especifica un tiempo de espera breve (lo ideal son 2 segundos).
  • Si la llamada agota el tiempo de espera o la respuesta no está bien formada, piensa qué quieres hacer. En la mayoría de los casos, lo más recomendable es confiar en este usuario y permitirle el acceso a la URL, ya que esto significa que, si se produce una interrupción del servicio mientras no hay ninguna cola en ejecución, el usuario no sufrirá ninguna interrupción. En situaciones de baja confianza, quizá prefieras enviar al usuario a la sala de espera: la sala de espera de CrowdHandler intentará establecer una conexión con la API y atenderá al usuario lo mejor posible hasta que reciba una respuesta válida de la API.

3. Suponiendo el de la respuesta

En la mayoría de los casos, recibirás una respuesta detallada, que incluirá mensajes de la sala de espera, etc. A continuación te mostramos un ejemplo:

{
    "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
    }
}

Sin embargo, algunos estados ofrecen una pequeña cantidad de información.

Por ejemplo, si compruebas una solicitud para una URL que no está protegida por ninguna sala de espera de CrowdHandler.

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

Otras respuestas que puedes recibir son: si tu clave no es válida (error HTTP 401), si la sala está llena (Estado: 5) o si la dirección IP desde la que estás enviando el mensaje ha sido incluida en la lista de direcciones bloqueadas (Estado: 4).

Soluciones:

  • Tómate un momento para comprender el significado de los códigos de respuesta que se devuelven. Estas son situaciones que quizá debas tener en cuenta.
  • Para saber si se debe conceder acceso al usuario o enviarlo a la sala de espera, solo tienes que comprobar el atributo booleano «promoted», que, salvo que se produzca un error, siempre estará presente y tendrá el valor 0 o 1. Si tu integración es muy sencilla y solo tienes que fijarte en este atributo, en realidad no necesitas comprender las distintas respuestas y estados, ya que si «promoted» es 0, puedes enviar al usuario a la sala de espera, y la sala de espera sabrá qué hacer.
  • Si has desarrollado una aplicación o utilizas un marco de trabajo que exige que el objeto de respuesta sea coherente en todo momento por motivos de programación orientada a objetos, deberías empezar por crear tu propio objeto o clase base para representar la respuesta, especificando valores por defecto adecuados, y luego establecer únicamente los valores que devuelve la respuesta de la API.