Ce guide explique comment réaliser une intégration API de base côté serveur.

Cela permet de valider que l'utilisateur de votre site web a le droit d'accéder à l'URL actuel et de le rediriger vers une salle d'attente si ce n'est pas le cas.

Ce guide est destiné aux développeurs. Il suppose une certaine familiarité avec les API, etc.

Cette intégration utilise les ressources publiques de l'API CrowdHandler, en utilisant la clé publique. Elle est disponible pour tous les plans, y compris le plan gratuit.

1. Connexion à l'API

Vous aurez tout d'abord besoin de votre clé publique. Lisez notre introduction à l'API pour accéder à votre clé d'api.

2. Passer votre premier appel

POST /requêtes/

Nous utilisons Postman ici pour démontrer les appels. C'est un excellent moyen de faire des appels à l'API, de tester les paramètres d'envoi et de comprendre ce qui revient lorsque vous mettez en place votre intégration.

Nous utilisons l'authentification de base pour envoyer notre clé. Postman nous permettra de la saisir une seule fois dans l'onglet d'autorisation et de l'enregistrer pour tous les appels que nous effectuerons. La clé est saisie dans le champ Username (nom d'utilisateur). Le mot de passe est ignoré. 

Maintenant que nous avons mis en place notre en-tête d'authentification, nous allons commencer par faire un appel POST à https://api.crowdhandler.com/v1/requests. Cet appel est utilisé pour initier une nouvelle requête vers une URL sur votre site, pour voir si cet utilisateur doit avoir accès ou être redirigé. 

L'appel post attend la charge utile JSON suivante :

{
    "url": "https://test.crowdhandler.com/some-url",
    "ip": "127.0.0.1",
    "agent": "Just testing",
    "lang": "Just testing"
}

Passons en revue ces paramètres :

  • url - Il s'agit de l'url à laquelle l'utilisateur tente d'accéder. L'origine de cette url dépend de votre application, de votre langage et de votre structure. Il peut s'agir d'une variable CGI ou d'une sorte de contrôleur/routeur frontal. L'URL doit être complète, y compris le protocole. CrowdHandler ne supporte que HTTPS. 
  • ip - Il s'agit de l'adresse IP de la requête de l'utilisateur. Là encore, l'endroit où vous récupérez cette information dépendra de votre langue et de votre cadre de travail. L'adresse IP est obligatoire. Elle est utilisée pour la prévention des fraudes et la détection des robots.
  • agent - il s'agit de la chaîne de l'agent utilisateur. Elle est également obligatoire. Vous devez la récupérer à partir de l'en-tête HTTP User-Agent.
  • lang - il s'agit de la langue préférée de l'utilisateur. Il s'agit d'un paramètre facultatif qui peut aider à identifier les agents frauduleux. Vous pouvez l'obtenir à partir de l'en-tête HTTP Accept-Language.

Si tout va bien et que l'adresse URL que vous avez fournie est protégée par une salle d'attente, vous devriez recevoir une réponse qui ressemble à ceci :

{
    "result": {
        "status": 1,
        "token": "tok_6ihQ7XNw0GmS",
        "title": "Queen Victoria Hall",
        "position": 648,
        "promoted": 0,
        "urlRedirect": null,
        "onsale": "2020-10-21T15:11:11Z",
        "message": "Our website is very busy right now. Sorry to keep you waiting, we will redirect you as soon as possible.",
        "slug": "queen-victoria-hall",
        "priority": null,
        "priorityAvailable": 0,
        "logo": null,
        "responseID": "1dc0784ea988c4139f406061f39edd39",
        "ttl": 0
    }
}

La marche à travers la sortie :

  • token token est l'identifiant de l'utilisateur. Nous n'en avions pas au départ, nous avons donc effectué une requête POST, qui n'en nécessite pas, ce qui signifie que nous avons reçu un nouveau jeton lors de notre première requête.
  • promoted est l'attribut principal qui nous intéresse. Une valeur de 0 signifie que l'utilisateur possédant ce jeton doit faire la queue pour l'url spécifiée. Une valeur de 1 signifie que l'utilisateur n'a pas besoin de faire la queue. Ce jeton a une valeur promue de 0, ce qui indique que l'utilisateur doit faire la queue. 
  • slug le slug, indique l'adresse de la salle d'attente. L'adresse complète de la salle d'attente sera https://wait.crowdhandler.com/your-slug
  • responseID est un identifiant unique qui identifie la réponse que vous venez de recevoir. Nous pourrons l'utiliser ultérieurement pour enregistrer les performances de cette demande avec l'API CrowdHandler.
  • les autres attributs sont intéressants et peuvent faciliter le dépannage et le débogage, mais vous n'avez pas besoin de les utiliser pour une simple intégration. Si vous souhaitez les utiliser pour d'autres raisons, vous pouvez consulter leur signification dans la documentation de l'API. 


Ainsi, si notre intégration reçoit cette réponse particulière, nous voudrions rediriger cet utilisateur vers la salle d'attente : https://wait.crowdhandler.com/queen-victoria-hall. 

Vous voyez autre chose ?

Il se peut que vous n'obteniez pas le modèle de réponse ci-dessus. Si votre réponse est très différente, il se peut que l'une des choses suivantes ait mal tourné, en fonction de ce que vous voyez : 

  • Une erreur ? Cela indique que quelque chose ne va pas avec les paramètres de la demande. L'erreur devrait vous indiquer ce qui ne va pas.
  • Pas d'informations sur les salles d'attente ? Si vous envoyez des URL qui n'entrent dans le champ d'application d'aucune de vos salles d'attente, vous recevrez un jeton et la promotion aura la valeur 1, mais vous n'obtiendrez pas d'informations sur la salle d'attente en retour. Vous pouvez essayer de mettre en place une salle d'attente "fourre-tout" pour faciliter vos tests.
  • Pas de token ? Si vous essayez de tester l'appel en utilisant des URLs sur des noms de domaines qui ne sont même pas enregistrés avec votre compte CrowdHandler, vous recevrez toujours 1 comme valeur promue (nous ne sommes pas responsables de la protection de ce domaine, donc en ce qui nous concerne, vous êtes bon pour aller de l'avant !) Mais vous ne recevrez pas de jeton. 
  • Si vous recevez le statut 3, cela signifie que votre IP a été bloquée. Cela peut se produire lorsque vous effectuez de nombreuses demandes d'API publiques à partir de la même IP, et c'est fréquent lorsque vous testez une intégration. Connectez-vous au panneau d'administration, trouvez votre IP (sous domaines > IPs) et changez le statut de votre IP en ignorer. 

OK, nous avons passé notre premier appel, nous connaissons le résultat et nous savons comment nous sommes censés y réagir. Nous parlerons des spécificités de la gestion de ces informations après avoir abordé l'appel suivant.

3. Votre deuxième appel

GET /requests/:token

Dans le premier exemple, nous n'avions pas de jeton d'utilisateur. L'appel POST ne reçoit pas de jeton, il en renvoie un. C'est donc l'appel à faire lorsque l'utilisateur sur votre site n'a pas de jeton. Mais si l'utilisateur a atterri sur votre site parce qu'il était dans la salle d'attente et qu'il a réussi à passer, alors il aura un jeton. Dans ce cas, vous devez vous assurer de l'utiliser et de le conserver pour le vérifier. En effet, si vous lui en donnez un nouveau, il se retrouvera très probablement dans la file d'attente. 

Où puis-je trouver le jeton ?

Lorsque CrowdHandler redirige les utilisateurs vers votre site, il ajoute le jeton à l'url. Il s'agit d'un paramètre de la chaîne de requête appelé ch-id. Par exemple https://yoursite.com/your-url?ch-id=tok_S0mET0k3n. Vous devez donc vérifier la présence d'un jeton dans ce paramètre d'URL. Et si vous le trouvez, vous faites l'appel GET au lieu de l'appel POST.

Mais ce n'est pas tout !

L'utilisateur cliquera ensuite sur de nombreux autres liens de votre site web. Pour vous assurer que l'utilisateur ne se retrouve pas dans la salle d'attente, vous devez définir un cookie de session chaque fois que vous recevez le jeton en retour, et vous devez vérifier le cookie chaque fois que vous ne trouvez pas ch-id dans l'URL. Si vous n'en trouvez toujours pas, envoyez la requête POST.

Les jetons expirent-ils ?

Ils le font. Mais si vous passez un token invalide, CrowdHandler ignorera ce token, traitera la demande comme si aucun token n'avait été défini, et vous renverra un nouveau token tout en vérifiant votre demande. Cela signifie que les jetons se nettoient d'eux-mêmes et que vous n'avez pas à vous soucier du suivi et de l'expiration des jetons. Mais cela signifie également que le jeton que vous recevez en retour n'est pas nécessairement celui que vous avez envoyé. Vous devez faire confiance au jeton que vous recevez plutôt qu'à celui que vous avez envoyé, c'est pourquoi vous devez activer le cookie à chaque fois.

Dois-je vérifier d'abord le cookie ou le paramètre URL ?

Le paramètre URL. Dans des situations complexes, il est possible que votre utilisateur ait un nouveau jeton dans la salle d'attente, mais qu'il ait encore un ancien cookie stocké sur votre site. Si l'utilisateur est renvoyé de la salle d'attente, le nouveau jeton sera dans l'URL, et vous devriez faire confiance à ce jeton, plutôt qu'au jeton potentiellement obsolète que vous avez précédemment défini comme cookie. 

Bien entendu, l'absence du paramètre ch-id ne doit pas être interprétée comme une instruction d'effacer un cookie existant. Vérifiez donc soigneusement.

Et puis... l'appel :

La charge utile est la même que pour la requête POST, mais comme il s'agit d'une requête GET, nous envoyons les paramètres en tant que paramètres GET, et non en tant que JSON brut. L'URL a changé. Cette fois, le jeton fait partie de l'URL.

La réponse ressemble beaucoup à la requête POST. Sauf que cette fois-ci, nous pouvons voir que le jeton que nous avons reçu est le même que celui que nous avons envoyé. Les décisions que notre intégration doit prendre, sur la base de ces données, sont exactement les mêmes que pour la requête POST.

En conclusion

Les appels POST et GET renvoient les mêmes informations. Vous faites l'appel POST lorsque vous n'avez pas reçu de jeton de la part de l'utilisateur, et vous faites l'appel GET lorsque vous l'avez reçu. Ces appels ne se font pas dans l'ordre, ce sont des alternatives. Dans les deux cas, la réponse aura le même format et l'action que vous entreprendrez sera la même. 

Vous devez stocker le jeton dans un cookie, ou dans votre objet de session, afin de pouvoir valider l'utilisateur à plusieurs reprises lorsqu'il accède à différentes URL sur votre site.

Prenez soin de définir votre cookie ou votre session, car un utilisateur en attente peut essayer d'accéder à d'autres URL sur votre site et vous ne voulez pas lui donner une nouvelle position à la fin de la file d'attente. Pour cette raison :

1. nous recommandons de stocker le jeton dès que possible, sans attendre de savoir si l'utilisateur doit attendre ou non. 
2. Faites attention à l'expiration de la session. Votre application peut disposer d'un magasin de session avec un délai d'expiration de 20 minutes, mais l'utilisateur peut rester dans la salle d'attente pendant des heures. Un cookie de session qui n'expire que lorsque l'utilisateur ferme son navigateur est une bonne solution. Un cookie permanent peut être encore mieux.

4. Quand passer le premier appel

L'objectif de CrowdHandler est de protéger votre site d'une charge excessive. L'objectif du contrôle de validation est de s'assurer que l'utilisateur de votre site accède bien à cette URL à ce moment-là. Vous devez donc effectuer ces appels le plus tôt possible dans le chemin d'exécution de votre code. L'objectif est d'économiser le temps d'exécution et les ressources du serveur. Dès que vous connaissez la demande d'URL et que vous êtes en mesure d'effectuer l'appel, vous devez le faire.

5. Que faire du résultat ?

  • Si la valeur promue est 1 ?, quittez le code de contrôle et revenez à votre flux d'application standard. Servez l'URL comme vous le feriez normalement.
  • Si la valeur promue est 0 ?, redirigez l'utilisateur vers la salle d'attente en utilisant le slug. Utilisez une redirection HTTP 302 au cas où l'"utilisateur" est un robot légitime, ce qui indique au robot que la redirection de l'url est temporaire.
  • Si vous obtenez une réponse malformée, ou si l'appel à l'API échoue... CrowdHandler dispose de nombreuses couches de protection, mais il y a sont Il y a plusieurs raisons pour lesquelles cela peut se produire et vous devez réagir. Il peut s'agir d'un problème de réseau temporaire dans votre centre de données ou sur une dorsale Internet. Si le processus d'appel à l'API échoue, ou si le processus d'analyse d'un résultat légitime échoue, ou si l'évaluation de l'élément promu échoue, vous devez traiter cela comme une exception et la gérer. La manière dont vous la traitez est laissée à votre discrétion :
    • La redirection en cas d'échec suppose que, si vous ne savez pas mieux, l'utilisateur doit être mis en file d'attente. Si vous connaissez le nom de votre salle d'attente standard (vous pouvez avoir un fourre-tout par défaut avec un nom stable), vous pouvez y envoyer l'utilisateur. Si vous ne le savez pas, vous pouvez envoyer l'utilisateur à https://wait.crowdhandler.comoù l'utilisateur recevra un modèle générique, sera interrogé régulièrement pour obtenir de meilleures informations et sera renvoyé sur votre site ou dans la salle d'attente appropriée lorsque le service normal sera rétabli.
    • Confiance en cas d'échec - vous pouvez décider de laisser l'utilisateur accéder à la page si l'appel à l'API échoue. Cela dépendra de la régularité du trafic sur votre site et de la prévisibilité des schémas. Si vous avez installé CrowdHandler uniquement pour une utilisation occasionnelle et planifiée, avec des salles d'attente spécifiques à un événement, vous préférerez peut-être faire confiance aux utilisateurs au cas où vous ne recevriez pas de réponses bien formées de la part de l'API CrowdHandler.

6. Redirection d'un utilisateur

Lorsque vous redirigez un utilisateur, vous devez fournir les paramètres url-encodés suivants dans l'URL de redirection.

  1. ch-id: le jeton renvoyé par l'API.
  2. url: l'url demandée par l'utilisateur. Si les paramètres de la chaîne de requête sont importants pour vous (que ce soit pour des raisons de marketing/tracking ou parce que vous les utilisez pour les identifiants de produits et autres), vous devez vous assurer qu'ils sont également transmis en tant que paramètre de l'url. 
  3. ch-public-key : si vous ne connaissez pas le slug de la salle d'attente de vos utilisateurs, peut-être parce que vous avez reçu une réponse malformée, ou pas de réponse, alors vous pouvez envoyer votre clé publique au lieu d'un slug, en utilisant ce paramètre. Cela permettra à la salle d'attente du réseau de sécurité de CrowdHandler d'utiliser votre clé pour trouver le bon slug, et de le traiter de manière appropriée.

7. Le dernier appel. Enregistrement des performances des pages

PUT /réponses/:id

L'enregistrement des performances de votre page permet à CrowdHandler de surveiller les performances de votre domaine. Ceci est utile lors de la surveillance d'un trafic important, et critique pour activer la fonction d'autotune.

Cet appel est un PUT. et il va vers une nouvelle ressource /responses/:id. L'ID vous a été fourni en tant que responseID dans le résultat du premier appel que vous avez effectué.

La charge utile de cet appel ressemble à ceci :

{
    "code": 200,
    "time": 2000
}
  • est la réponse HTTP à la page que vous proposez à l'utilisateur. Il s'agit généralement de 200, mais si vous êtes en mesure de piéger les codes d'erreur http, vous devriez les envoyer. Cela aidera CrowdHandler à identifier quand votre site web est en difficulté*, permettant à autotune d'agir. Si vous omettez ce paramètre, CrowdHandler enverra par défaut 200.
  • temps est le temps de chargement de votre page en millisecondes. Vous pouvez le calculer comme suit :
    • à partir du moment où vous recevez votre demande pour la première fois (a)
    • en prenant le temps juste avant de soumettre ce PUT (b)
    • en soustrayant b de a et en veillant à ce que la différence de temps soit exprimée en millisecondes (millièmes de seconde).

      Bien que cela semble assez simple, vous devez faire preuve d'une certaine prudence. Il peut y avoir des différences ou des problèmes de performance selon que vous utilisez des machines virtuelles ou des serveurs nus, et selon les types de processeurs. Certains frameworks disposent d'API spécifiques pour le suivi des performances des pages. Si vous êtes confiant, vous pouvez fournir une lecture très précise à CrowdHandler. Si vous êtes moins confiant, vous pouvez simplement omettre ce paramètre. Dans ce cas, CrowdHandler fera ses propres calculs en se basant sur le temps écoulé entre la requête initiale et le PUT suivant. L'estimation du temps de chargement de la page peut être quelque peu affectée par les temps de réseau, et a une résolution plus faible, mais l'information est suffisante pour un bilan de santé et est meilleure que la valeur sauvagement inexacte qui pourrait être fournie si vous vous trompez dans votre calcul.


* Une réponse avec un code d'erreur est traitée par CrowdHandler de la même manière qu'une requête dépassant votre temps de réponse maximum. Ainsi, si vous répondez très rapidement à des erreurs 500, mais que le nombre d'erreurs dépasse votre seuil acceptable en %, autotune ralentira le trafic comme si ces requêtes répondaient au-delà de votre seuil acceptable de chargement de page. 

Quand passer l'appel.

Alors que l'appel initial doit être fait le plus tôt possible, cet appel doit être fait le plus tard possible, après que vous ayez présenté votre page à l'utilisateur. De plus, cela semble évident, mais vous ne faites cet appel que si vous avez réellement servi l'URL. Si vous avez redirigé l'utilisateur vers la salle d'attente, vous devez sauter cet appel. Après votre premier appel, il y a donc une branche conditionnelle entre l'envoi de la redirection, ou l'affichage de la page, et l'enregistrement des performances.

8. Tout mettre bout à bout

Le pseudo-code** suivant rassemble tous ces éléments pour décrire une intégration simple, mais complète. Vous verrez qu'il fait passer l'idée plus rapidement que les longues explications que nous avons données jusqu'à présent, mais vous devriez néanmoins vous référer aux notes pour le contexte.

chKey = <your public key>
timeA = Timer.getTimeInMs()
request = Controller.getRequest()
response = Controller.startRresponse()
trustOnFail = true

if request.urlParams["ch-id"] 
    # token in query string. We want to set cookie so we recognise this user
    response.cookies["ch-id"] = request.urlParams["ch-id"]
    # and we'll strip ch-id param and redirect to discourage token sharing
    cleanParams = request.urlParams.unset("ch-id")
    response.redirect(request.url, cleanParams, 302)
    response.end
else
    # set up the API gateway
    crowdhandler = HttpAPI.create(baseURL="https://api.crowdhandler.com/v1/", authentication=chKey)
    params = {"url": request.url, "ip": request.host, "agent": request.userAgent, "lang": request.acceptLang}
    # look for crowdhandler token in the cookie
    token = request.cookies["ch-id"]

    # check this user's request
    try 
        if token 
            # user has token
            result = crowdhandler.get("requests/"+token, params)
        else
            # user needs new token
            result = crowdhandler.post("requests/", params)
        end
    catch
        # api call failed!
        if trustOnFail
            # we do nothing
            break
        else
            # we send user to waiting room
            queryParams = {"url": request.url, "ch-id": token, "ch-public-key": chKey}
            response.redirect("https://wait.crowdhandler.com?", queryParams, 302)
            response.end
        end
end 

# if we got here, we have a valid response. 
# It's possible that the API has responded with a new token.
token = response.token
response.cookies["ch-id"] = token

if result.promoted
    # this token is good for this url
    # render your page / hand back control / you do you
    response.html = "Your Content"
    response.end
    # all done? Now to log the performance
    time = timeA - Timer.getTimeinMs()
    crowdhandler.put("/responses/"+result.responseID, {"code": 200, "time": time})
else
    # the user with this token needs to wait
   response.redirect("https://wait.crowdhandler.com"+result.slug+"?", {"url": request.url, "ch-id": token}, 302)
end

** C'est l'enfant bâtard de ruby et de python, deux langages lisibles, avec des API imaginaires et simples pour émettre des appels d'API, récupérer les données des requêtes et envoyer des réponses. Nous espérons qu'il est facile pour vous de lire entre les lignes.

Consultez notre SDK PHP pour obtenir une bibliothèque de codes entièrement fonctionnelle.