Our Cloudflare integration utilizes Cloudflare's edge code solution Cloudflare Workers to provide you with a waiting room service that works directly from your CDN without the need for you to make any changes to your application code or web servers. 


Introduction


This article will take you through the four steps required to integrate CrowdHandler with Cloudflare. 



If at any point of working your way through the guide you get stuck or have questions then feel free to reach out to us via https://support.crowdhandler.com.


Prerequisites


  1. An active CrowdHandler account. If you haven't signed up already you can do so here.
  2. A Cloudflare account.


Step 1: Create a Cloudflare Worker.


  1. Login to your Cloudflare account.
  2. Select the Workers service.


  3. If this is your first time creating a Cloudflare worker you will be prompted to set up a free Cloudflare worker subdomain and to choose a worker plan. You can name your subdomain whatever you want and proceed to choose your plan.

    For the purpose of working through this setup guide, the free plan will suffice. If required, It is possible to upgrade to the paid, workers' plan once setup is complete (see Step 5).

     
  4. Click create a worker.



  5. Remove the default template code so that the script is empty.


  6. Copy our integration code from GitHub and paste it into the script.


  7. Rename the worker to "crowdhandler-integration".


  8. Click the save and deploy button.



Step 2: Setup the worker variables.


  1. Hit the back button on the script edit page.



  2. Navigate to settings and click the Add Variable button.



  1. Add the following variables and click save.
    1. API_ENDPOINT = https://api.crowdhandler.com/v1
    2. API_KEY = YOUR_PUBLIC_KEY_HERE (Can be found in the Account -> API section of the CrowdHandler administration control panel.)
    3. (Optional) WHITELABEL = false (default) | true
    4. (Optional) NO_BYPASS = YOUR_RANDOM_TOKEN_HERE
    5. (Optional) FAIL_TRUST = false (default) | true
    6. (Optional) SAFETY_NET_SLUG = YOUR_WAITING_ROOM_SLUG_HERE



OPTIONAL VARIABLES
WHITELABEL (default falseBy default, users will be queued on CrowdHandler's wait.crowdhandler.com domain. If WHITELABEL is set to true, users will be queued on the domain CrowdHandler is protecting. For example, if CrowdHandler has been set up to protect www.example.com, users will be queued on the www.example.com/ch/ path. The /ch/ route does not need to exist in your application. Read more about whitelabel waiting rooms here.
The NO_BYPASS value will be sent to your origin as the value of the x-ch-no-bypass header. You can check for this header in your application to verify that the request has traversed through CrowdHandler. Implementation examples can be found in the "Integration Examples" section of this article.

FAIL_TRUST (default trueBy default, users that fail to check in with CrowdHandler's API will be trusted. If set to false, users that fail to check-in with CrowdHandler's API will be sent to a safety net waiting room until CrowdHandler is able to make a decision on what to do with them. Read more about Trust on Fail here.

If SAFETY_NET_SLUG is defined and FAIL_TRUST is set to falsethis waiting room slug will be used as the safety net room. If you do not define a SAFETY_NET_SLUG value and FAIL_TRUST is set to false, a generic waiting room template will be used as the safety net room.

You can find your waiting room slug in the CrowdHandler control panel in the URL field of your room configuration.



Step 3: Configure Routes.


  1. Navigate to the worker's configuration screen for the domain you would like to protect.



  2. Add routes that you would like to protect.


The above pattern will trigger the CrowdHandler worker for all routes on your site except for any excluded routes. We recommend starting off with this pattern unless you're confident that your site won't be flooded with traffic to unprotected routes and will not be vulnerable to the redirect gotcha outlined here. 

You can do further, more granular waiting room route configurations through the CrowdHandler admin console.


        4. Exclude routes that should not have CrowdHandler protection by selecting "None" in the worker dropdown.




Out of the box CrowdHandler will automatically not attempt to queue routes with the following file extensions. 

"avi","css","csv","eot","gif","ico","jpg","js","json","map","mov","mp4","mpeg","mpg","ogg","ogv","ott","pdf","png","svg","ttf","webmanifest","wmv","woff","woff2","xml".

It is your responsibility to ommit patterns and routes that should not be queued.

Common examples are:

* Paths used for storing static assets and media i.e. /wp-includes/*
* Callback URLs made by third party payment providers.
* JSON and RSS feeds.




Step 4: Finalise your configuration.


CrowdHandler is integrated with your Cloudflare account and now it's over to you to customize your CrowdHandler setup through the CrowdHandler administration console. Here are some recommended support articles that cover the basics:


  1. Getting Started (You can disregard the bits about installing the Javascript integration.)
  2. Waiting Rooms
  3. Domain Configuration 


Step 5 (Recommended): Remove Cloudflare Workers Rate Limiting.


At the time of writing the Cloudflare workers free plan is subject to a burst rate limit of 1000 requests per minute and a daily request limit of 100,000 requests. If you think that these limits might be too low for you, we would recommend upgrading to the Cloudflare workers paid plan to remove the limits.