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,
C#,
VB,
JScript,
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.
