Greasemonkey How-To

We've put together some simple instructions on how to get our Greasemonkey scripts for mTurk installed and working for you. Follow the steps below and you'll have Turk Berserk scripts improving your mTurk experience in a matter of minutes!

Step 1: Get Firefox

Greasemonkey is an Add-On for the Firefox web-browser, so you'll need to use Firefox (at least for Turking) in order to make use of our scripts. If you already have Firefox, skip this step and go straight to Step 2. If you don't have Firefox, it's easy to install. Just click on the "Get Firefox" button in our sidebar (we get a small fee from Google when you click through this link - it costs you nothing but helps keep us motivated to write cool new Greasemonkey scripts!) and click on the blue install button. Or you can go directly to the Firefox page (but then we get no referral fee.....) and click on the big green download button. Follow the instructions and you'll have Firefox installed!

Download Firefox

Step 2: Get Greasemonkey

Already got Greasemonkey? Then skip to Step 3. Otherwise....

Open the Firefox browser and go to the Greasemonkey add-on page. Click on the green "Add to Firefox" button and a small window will open asking you to confirm that you want to install Greasemonkey. Click "OK" and Greasemonkey will be installed. You'll need to restart Firefox for Greasemonkey to activate.

Install Greasemonkey

Step 3: Install a Script

Head on over to our Scripts page and find a script that you'd like to use - then follow the link to that script's own page. At the top of the page you'll find an "Install Now" link. Click on it, and Greasemonkey will open a window asking you to confirm that you want to install the script. Click OK and the script will be installed.

Step 4: Turk with the power of Turk Berserk scripts

You're all set! Head over to mTurk and you should see the scripts you've installed start to work their magic. We're happy to hear your thoughts on how to improve our scripts, or other features you'd like to see, and if you find any bugs, let us know - we'll try to fix them!

Working with GreaseMonkey

GreaseMonkey is designed to "just work" - so you should be able to install scripts and know that they'll work their magic as required. But, there are a few useful things you should know about GreaseMonkey:

Disabling GreaseMonkey: You can completely disable GreaseMonkey by just clicking on the small monkey-face icon in the tool-bar at the bottom of the browser window. The face will become sad when GreaseMonkey is disabled. To re-enable, just click again. You'll need to reload a page after disabling/re-enabling GreaseMonkey for the change to take effect.

Which Scripts Are Active?: To see which scripts are active on the current page, right click on the monkey-face icon. At the top of the menu you'll see a list of all scripts that are active on this page. (If no scripts are active on the current page you'll see "No scripts installed!" instead).

Disabling a Specific Script: If you need to disable a script that's active on the current page, right click on the monkey-face icon. Scripts that are enabled are listed in the GreaseMonkey menu with a green check mark. To disable a script, just select it from the menu. Disabled scripts show up in the menu with a red "X". You can re-enable a script by clicking on it in the Greasemonkey menu again. If you need to disable a script that isn't active on the current page, use the Manage dialog (see below).

The Manage Dialog: Right click on the monkey-face icon and select "Manage User Scripts...". This will open the Manage dialog (see below). On the left, you'll see a list of all of the scripts that you have installed. You can enable or disable any script by clicking on it and then using the "Enabled" check-box in the lower left corner. When you click on a script in this dialog, the boxes on the right show you which web pages this script will work on, and those that it will ignore (by default all pages are ignored). You can also use this dialog to remove scripts - just select the script and click the "Uninstall" button. Finally, if you want to look at the inner workings of a script click on "Edit" and you'll see the Javascript code that does all of the work. You can even edit the script if you want!

The Manage Dialog

Uninstalling GreaseMonkey: If you want to totally remove GreaseMonkey and all of its scripts open the "Tools" menu from Firefox's menu bar and select "Add-ons". Search down the list of add-ons for GreaseMonkey, click on it and then click the "Uninstall" button. You'll need to restart Firefox for the change to take effect.

Where To Find More Help

There's a lot of Greasemonkey help available online. Here are some of the most useful references that we've found:

• Monkey manual: the official guide to Greasemonkey
• Manage dialog: how to use Greasemonkey's "Manage" dialog to manage your scripts
• userscripts.org: a place to find other Greasemonkey scripts
• Scripts section at Turker Nation: Turker community discussion on using scripts with mTurk

mTurk + Greasemonkey = Better, Faster Turking!

If you Turk regularly, and if you read the forums over at Turker Nation, you'll be familar with the thought "mTurk is great - but it would be even better if.....". Whether it's showing your current balance on the Dashboard, or changing the layout of a HIT so that you can complete it with less scrolling and fewer mouse clicks (more money, faster!) there's an long list of improvements that we'd all like to see.

Here at Turk Berserk, we're big fans of Greasemonkey - an extension for the Firefox web browser which lets you change the way websites look and function to your own liking. In the early days of mTurk there used to be lots of Greasemonkey scripts. However, those scripts have either never been maintained or they are for obsolete HITs. The old scripts just don't function any more. It's time to resurrect the joy of Turking with Greasemonkey! We've been using Greasemonkey for some time to improve our own mTurk experience and we want to share the joy with you! So read on, and we'll explain what this Greasemonkey thing is all about.....

What is Greasemonkey?

Greasemonkey is an Add On for the Firefox web browser. On its own, it does nothing - its power comes from small "scripts" (Javascript for the geeks; a bunch of computer instructions that you don't have to worry about for the non-geeks). It works in the background every time you load a web page and allows those scripts to change the appearance and function of that page. All those changes are made after the web page is loaded, on your own computer.

A Greasemonkey script could do something as simple as changing the colors of the web page (to remove that shade of purple that you just can't stand to look at), or something as complicated as reorganizing information in the page, adding buttons and grabbing information from other pages and displaying it. Scripts only work on the pages they're told to - you don't want it trying to put your mTurk balance on cnn.com right....

This is really useful for mTurk! For example, lots of people want the Current Balance (i.e. the amount of money that you actually have available to spend) shown on the Dashbord, which currently just shows your total earnings. There are two ways to get this:

1. E-mail Amazon and beg them to add Current Balance to the Dashboard......

2. Write a short Greasemonkey script that does it automatically every time you view your Dashboard.

Even better, you can install a Greasemonkey script from right here at Turk Berserk that will do exactly this! Interested? At the end of this post we'll explain how to get this Greasemonkey script installed (it will only take a few minutes...). But first, a word about our philosophy.

Our Script Philosophy

We want to make it very clear that the scripts that we make available on Turk Berserk will never allow you to cheat at mTurk. We don't create "bots" that try to complete HITs automatically.

Instead, our scripts are designed to either improve your Turking experience (for example, by giving you the extra information you need to keep track of your work) or to allow you to complete HITs more easily (maybe by reorganizing the layout of a HIT so that it takes fewer mouse clicks to complete). You still have to do the real work of the HIT though!

Amazon is quite explicit about allowing disallowing scripts that complete a HIT for you. In their Conditions of Use they state:

3.b. "(i) you will not use robots, scripts or other automated methods to complete the Services."

The important word here is "complete" - the script must not do the work of the HIT for you, but a script which merely allows you to do the work of the HIT more efficiently is OK.

And, from the horse's mouth: In December, 2005, Jeff Barr (a developer on the AWS side) posted on the official Amazon Web Services Blog

A few Workers are trying to run "bots", which you can think of as mindless HIT robots. While we do recognize that some high performance Workers use a variety of scripts to simplify and increase the efficiency of the Mechanical Turk workflow, we do need to point out that the use of fully automated bots runs counter to the Mechanical Turk Participation Agreement.

We (and apparently Amazon too) don't consider using scripts of this type to be "cheating" - although there has been debate about this in the past and a clearer position on this issue from Amazon would be very welcome. We will gradually be making all of our scripts publicly available - so the playing field remains level (if one of our scripts allows you to complete HITs faster, then it allows everyone to complete them faster). The only thing we ask is that you don't publish our scripts on other websites -- please direct folks here to Turk Berserk.

The bottom line: We want to improve your Turking experience and make mTurk faster and more efficient. That can only help to get more requesters using mTurk and help us all make more money!

OK, Sounds Good. So How Do I Get Your Scripts?

Now that we've convinced you that using Greasemonkey is the way to Turking Zen you'll want to head on over to our Greasemonkey How-To to learn how to get Greasemonkey running. You should also check out our post, How Safe Is Greasemonkey Anyway? (If you already know all about Greasemonkey and have it installed, you can skip the How-To and surf right on over to our Scripts page.)

Resources Beyond mTurk

There are several places beyond mTurk that may help you in your Turking quests:

1. Turker Nation: A mature, well-established forum for Workers.
2. Mechanical Turk Sandbox: The official test & development site. Everything looks and acts as if it’s the regular mTurk, but you don’t get paid for doing or posting HITs. It’s like monopoly money. It will prompt you to create an account on the Sandbox if you want to play around. However, you just use your Amazon login yet again.
3. Amazon Web Services Developer Connection -Mechanical Turk Forum: The official forum for mTurk Requesters. Very technical discussions about how to post HITs, the mTurk APIs, and other Requester coding issues. Amazon responds to technical questions here very quickly. Also, Amazon posts update notifications here. Useful for workers to get an understanding of what Requesters go through.
4. Turkers Forum: A new forum created at the end of February 2007. Doesn’t have too many discussion threads yet, but it’s worth keeping an eye on. Appropriately enough, this Forum advertised and started populating threads via a HIT on mTurk.

Don’t forget as well, that many HITs on mTurk are through companies whose business models rely on mTurk. These Requesters might have more resources and information on their home pages.

If you’re thinking of posting your own HITs, these resources are specifically for the Requester side:

1. AWS Developer Forum: (mentioned above)
2. Command Line Tools: Open source toolkit to make writing HITs much easier. Download through svn.
3. mTurk API Tools in Other Languages: PHP, Perl and Java.
   
4. HIT-Builder.com: Hit-Builder offers more features than the standard mTurk requester interface. You can also hire them to help develop your HITs.
5. von Kempelen: Company offers HIT designing and posting services.
6. Dolores Labs: Offers HIT data collection services. Has many examples of test HITs.
   

If you know of any other useful Turking resources, post a comment, and if it’s worthy, we’ll add it to our list!

Glossary

Like all popular pastimes, mTurk has its own lingo. Here’s a little guide.

As new topics come up, I will add more terms to the glossary. If you have any to add, feel free to let me know!

To open hyperlinked terms in a new tab, hold down the CTRL key and left-click the name.)

URL for Google Spreadsheet: http://spreadsheets.google.com/pub?key=pxpTLP5OADPhuuDGV0UDiFg

The six categories of HITs

There are numerous Requesters on mTurk. However, only a few types of HITs appear over and over again.

I have categorized HITs into 6 categories:

1. Decision: In these HITs, the worker is asked to make a judgment call or to take a poll. Decision HITs usually contain radio buttons or a check list and are quick to perform. Examples of decision HITs are: Amazon's Are these items different, Powerset's Evaluate Search Results, and Content Review's Review User Submitted Images.


2. Research: For research HITs, the worker must search for information, generally on the web. The response is typically a URL, copied reference material, or data. Examples of research HITs are Amazon's NowNow Research Questions, Unspun's Find a URL/Amazon product identifier, and ClayValet's Find a product group of HITs.


3. Image Tagging: Workers interact with the picture in some way. Usually the worker is marking a set of specific features in the image. The two most common Requesters in this sub-type are Geospatial Vision (marking road features) and True Yardage (marking features on golf courses).
   


4. Transcription: Workers are asked to transcribe text from an audio or video file. HITs that ask workers to transcribe text from an image are also included.
   


5. Create: Generally a more involved HIT, these HITs require the worker to create some original content. There are many types of creation HITs. Some ask you to write an article or rewrite a sentence (e.g. ContentSpooling, Paul Pullen), create trivia questions (e.g. UQsoft), or draw something (e.g. draw).
   


6. Traffic Generator: These HITs usually are trying to generate traffic to their website. They might ask the worker to click through some links. Sometimes they require the worker to comment on a blog. Other traffic generator HITs want workers to post links back to their own websites.

These six categories of HITs encompass just about every HIT you encounter on mTurk. I'm sure there are some oddballs out there as well that don't fit these five. I just can't think of any!

You might argue that a few HITs straddle more than one category. For example, rewriting sentences generally means the Requester is using workers for Search Engine Optimization (such as ContentSpooling). Although this has the end result of traffic generation, the actual work performed is mostly a creative process for the worker. Likewise, you could argue that asking a worker to generate a list of tags for an image is a creative process -- as is crafting a response for NowNow questions. However, the former is mostly an image-based process with minimal effort and the latter takes tremendous amounts of research.

In the list of Requesters and HITs, the categories are based on the major type of work a Turker is asked to perform.

Requesters

Here is a list of frequent Requesters, the types of HITs they offer, and roughly how quickly they pay when your HIT is accepted. I will update this list from time-to-time to reflect the current Requesters at mTurk.

note: This is not meant to be a comprehensive list! But it’s a good place to start.

URL for Google Spreadsheet:
http://spreadsheets.google.com/pub?key=pxpTLP5OADPhLyybn0fY_Ag

If you click on a Requester name, you will be taken (within the iframe) to a search page for all HITs currently listed by that Requester ID. To open a new tab with that search, hold down the CTRL button before clicking. Not all Requesters will have HITs listed.

Any cell with "??" indicates missing data. If you have any of the missing information, contact me and I will update the spreadsheet.

The categories listed in the "Type" column are based on the 6 categories of HITs, described here. In addition, the time to payment is an estimate based on my experience. Beware that Requesters may change their time to payment.

Getting Started: A Tour Around mTurk

Here’s a quick primer on how to get started working on mTurk. I will go into details of each of the sections in future blog posts.

Don’t forget to read the official mTurk FAQ on getting started.

Get an Account

Start at the mTurk Introduction page. To work on mTurk, you will need to get an mTurk account. If you already have an account at Amazon.com (i.e. if you’ve purchased products from the US-based Amazon) you can just sign on to mTurk using your existing email address and password. If you don’t already have an Amazon.com account, you will be prompted to create one. You will be prompted to sign in or create an account if you click on the Sign In in the upper right hand corner, if you try to click on Your Account, or if you try to accept a HIT.

Let’s go on a quick tour:

Next, you should explore mTurk. There are three tabs at the top of all mTurk pages: Your Account, HITs, and Qualifications.

Your Account

Under the Your Account tab, you can keep track of your HITs. The Dashboard is the homepage for your stats: summaries of how many HITs you’ve done, cash earned, reject rates, etc. The Status page gives you 45 days of details of your HITs. The Account Settings is the technical details page. It has your account balance and links to the detailed transactions (the actual money transfers from the Requester’s accounts to your own). This is also where you transfer your earned money out of mTurk.

HITs

The HITs tab is where you find HITs to work on. You can look at All HITs available on mTurk, or just the HITs you are qualified to do (HITs Available To You). In addition, if you have any open HITs (you’ve accepted them, but haven’t submitted or returned them), you can find those open HITs on the HITs Assigned To You page.

Qualifications

The Qualifications tab lets you manage and explore qualifications on mTurk. The Qualifications Assigned To You pages gives you a list of all Qualifications that you have earned or have been assigned. Everyone has the HIT abandonment rate (%), HIT approval rate (%), HIT rejection rate (%), HIT submission rate (%), HIT return rate (%), and Location Qualifications. The All Qualifications page lets you browse through a list of all Qualifications you can request or take a test to receive. Finally the Pending Qualifications page shows you the Qualification tests you have taken, but have yet to be graded by the Requester.

Find a HIT

In future posts, I’ll go into the details of how to navigate each of the pages mentioned above. However, I’m sure you’re itching to find a HIT to try!

Go back to the HITs tab, and click on HITs Available To You. You’ll see a list of all the groups of HITs you are qualified for on mTurk. On the upper left, you can sort the HITs in various ways. When you click on the title of the HIT group, the box will expand to show you the description of the HIT, keywords and qualifications. When you click on the “View a HIT in this group”, you are taken to a preview page for the HIT. Read the description, look over the HIT and decide if it’s something you’d like to try. If so, do the HIT! Note that there is a timer in the upper left corner of the HIT page that lets you know how long you’ve been working on the HIT and the total Alloted Time.

Get Approved, Get Paid

Getting your HITs approved by the Requester is one of the biggest variables on mTurk. Some Requesters have a script that verifies your work, and approves or rejects your HIT accordingly. (The Amazon Requester Inc. “Are These Items Different” are this way.) Some Requesters will pay you automatically after a certain number of days. (Amazon Unspun HITs pay automatically after 5-6 days.) And some Requesters have to approve or reject your HIT by hand. It can take anywhere from a few minutes to 2 weeks for the vast majority of HITs to be evaluated and paid, so be patient. Even if a Requester never gets around to evaluating your HIT, Amazon has a policy to auto-approve your hit after 30 days.

Once your HIT is approved, you see the value in the Total Earnings on your Dashboard increase. This amount is not the amount of cash you can transfer out to your bank or Amazon.com balance. Your current balance is quoted on the Account Settings page. There is a delay from the HIT being approved (value on the Dashboard) and the money transfering from the Requester's account to your own. You can see details of these transfers through the View your account balance and transaction history link on the Account Settings page.

Transfer money

Now that your HIT has been approved, you’ve gotten paid, I bet you are eager to get your hands on your earnings! You have several options here, mostly depending on where you are in the world.

If you are in the US, you can choose to either transfer your earnings to a US-based bank account or you can transfer your money to your Amazon.com balance. As of March 18, your earnings are stored in the Amazon Payments system. You can use your earnings to pay for goods wherever Amazon Payments are accepted. In order to transfer your money to your bank account, you will need your account number and routing number from your bank. Both of these options are available from the Account Settings page.

If you are in India, you can have your earnings sent you by check, made out in Rupees. Details of how to do this can be found on the FAQ.

For the rest of the world, things are much more difficult. Unless you have a US-based bank account, your only option is to have your earnings transferred to your Amazon.com balance, then find Sellers on Amazon who will ship products to your country. What’s important here, is that you can NOT transfer your earnings to Amazon.co.uk or Amazon.de, etc. Nor can international Turkers use the Amazon Payments system. The independent Turker Nation forum has a nice thread of Sellers who will ship internationally. Make sure to go to the last page to see the most recent update.

And that’s it for our quick tour! You will learn so much more by getting your hands dirty trying HITs and exploring the mTurk page.

Don’t forget to ready my summary on Pitfalls!