Asirra — Installation Instructions

Protecting your web site with Asirra is easy. It just takes a few lines of code in whatever language your web service is written in. See these complete working examples:

There are four basic steps, described below. First, add a call to our JavaScript from your web form. Second, wire your "submit" button to our Asirra validation function. Third, write your own JavaScript function that submits the form once you get a callback saying the Asirra challenge has been successfully solved. Finally, add a call to our web service from your server form processor, to ensure that you are not getting a request from a cheating client.

Step 1. Call our JavaScript from your web form.

Somewhere in your form, import Asirra's client JavaScript. The point at which you include the script will have a div added containing the challenge. This must be inside a form.
<script type="text/javascript" src="http://challenge.asirra.com/js/AsirraClientSide.js"></script>
Optional: If you'd like to customize the look of the Asirra challenge, also include the code below. A complete example can be found by performing view-source on our Example Service.
<script type="text/javascript">
// You can control where the big version of the photos appear by
// changing this to top, bottom, left, or right
asirraState.SetEnlargedPosition("top");

// You can control the aspect ratio of the box by changing this constant
asirraState.SetCellsPerRow(6);
</script>

Step 2. Arrange for your form to validate using onsubmit().

Here is a typical form arrangement, where the form's onsubmit property calls a site-specific validation function MySubmitForm(). In the next step, we'll modify the validation function to include a call to Asirra.
<form action="ExampleService.py" method="get" id="mainForm" onsubmit="return MySubmitForm();">
      User Name: <input type="text" name="UserName">
      Favorite Color: <input type="text" name="FavoriteColor">
      <script type="text/javascript" src="http://challenge.asirra.com/js/AsirraClientSide.js"></script>
      <input type="submit" value="Submit">
</form>

Step 3. Write a JavaScript function that submits the form if the user is human.

The callback function that you passed as an argument to Asirra_CheckIfHuman() will get called once the Asirra server has determined if the user has passed the challenge. Your callback should take one argument, which will be either true or false, depending on if the user is human.

Because the callback gets called asynchronously, we have to restart the form submission process once the HIP is passed. To prevent an infinite loop, we use a state variable passThroughFormSubmit to disable the check on the second submission.

If the user is human, submit the form. If not, notify the user that they should try the HIP again. Our example below uses an alert(), but feel free to do something more elegant.
<script type="text/javascript">
var passThroughFormSubmit = false;
function MySubmitForm()
{
     if (passThroughFormSubmit) {
          return true;
     }
     // Do site-specific form validation here, then...
     Asirra_CheckIfHuman(HumanCheckComplete);
     return false;
}
function HumanCheckComplete(isHuman)
{
     if (!isHuman)
     {
          alert("Please correctly identify the cats.");
     }
     else
     {
          passThroughFormSubmit = true;
          formElt = document.getElementById("mainForm");
          formElt.submit();
     }
}
</script>

Step 4. Have your back-end form processor validate that the challenge has been passed.

This is a critical step; without it, clients can simply bypass Asirra by disabling or circumventing the Asirra JavaScript.

If a client successfully passes an Asirra challenge, our JavaScript will set a hidden input field in your form called Asirra_Ticket. The value of this field will be a special string that your form processor can use to verify that the client has actually passed the challenge.

When your processor receives form data, pass the contents of the Asirra_Ticket field to the following URL (replace FORMDATA with the value of Asirra_Ticket):
http://challenge.asirra.com/cgi/Asirra?action=ValidateTicket&ticket=FORMDATA

The result will be a bit of XML that either indicates the ticket is valid:
<AsirraValidation>
    <Result>Pass</Result>
    <Debug></Debug>
</AsirraValidation>
...or that it isn't:
<AsirraValidation>
    <Result>Fail</Result>
    <Debug>exceptions.Exception: invalid ticket format</Debug>
</AsirraValidation>
Note that a ticket can only be redeemed once. Any subsequent attempt to validate the same ticket will result in failure.

See our example form processors written in Python, PHP, and Perl, all of which have links to the source code of the back-end form processor. Asirra can be invoked from other languages, as well.
ProjectsASIRRA > Asirra — Installation Instructions