|
You are browsing the documentation for a deprecated version ('2014-08-15') of the Amazon Mechanical Turk Requester API. This version of the API will be deprecated and will be rendered unusable as of June 1st, 2019. If you request against a legacy API version (https://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI-legacy/Welcome.html) on or after June 1, 2019, you will receive the following response:
The latest version of our API ('2017-01-17') provides you with additional tool choices and enables you to select from nine AWS Software Development Kits This version also updates naming conventions used in the API and adopts the AWS standard of Signature Version 4 to authenticate requests securely. The API uses REST requests and no longer requires that developers be familiar with SOAP protocol. These changes make the MTurk API consistent with AWS APIs, simplifying the on-boarding process for both new and existing AWS developers. The legacy MTurk Command Line Tools and .NET, Java, Ruby, and Perl SDKs were marked as deprecated in January 2018. We will be deprecating the legacy APIs as of June 1, 2019. If you are on a legacy API, you must migrate to the latest
version of our API. You can find documentation for the latest API here and the AWS SDKs here For support, contact requestor-apilegacydeprecation-support@amazon.com |
HTMLQuestion
Topics
Description
The HTMLQuestion data structure defines one or more questions for a HIT using
HTML. The HTMLQuestion data structure is similar to both the
QuestionForm and ExternalQuestion data structures.
The QuestionForm data structure defines, using a special XML language,
how Amazon Mechanical Turk displays HIT questions and collects the answers.
The ExternalQuestion data structure defines, using HTML, questions you host on your own "external" website.
If you want to define your questions using HTML forms without having to host a website, you can use the HTMLQuestion data structure.
A HTMLQuestion HIT is like a cross between a QuestionForm HIT and an ExternalQuestion HIT, for instance:
-
Like a
QuestionFormHIT, you do not need to run a website or run any other infrastructure to have your HIT display on Mechanical Turk. You define your question when you call CreateHIT and then collect worker answers later, after they have been submitted. -
Like an
ExternalQuestionHIT, you can define your HIT in HTML. Your HTML code must contain a form for the Worker to fill out and submit, which is displayed in a frame in the Worker's web browser. The Worker submits results using your form, and your form submits the results back to Amazon Mechanical Turk. Worker answers are processed by Mechanical Turk in the same way asExternalQuestionHITs. If you choose, you can collect or process the results before submitting to Mechanical Turk.
The worker interaction and presentation options available for HTMLQuestion are similar to ExternalQuestion.
HTMLQuestions differ from ExternalQuestions primarily in how they are created.
As with the other question data structures, an HTMLQuestion is a string value that consists of XML data.
This data must conform to the HTMLQuestion schema.
See WSDL and Schema Locations
for the location of this schema.
For more information about using XML data as a parameter or return value,
see Using XML Parameter Values.
Note
You can only use an HTMLQuestion as the question of a HIT. You cannot use an HTMLQuestion with a Qualification test.
The HTMLQuestion data structure is used as a parameter value for the following
operation:
-
CreateHIT
The HTMLQuestion data structure is a value in a
HIT data structure.
All elements in an HTMLQuestion belong to a namespace whose name is identical
to the URL of the HTMLQuestion schema document for the version of the API
you are using.
The HTMLQuestion Data Structure
The HTMLQuestion data structure has a root element of HTMLQuestion.
The HTMLQuestion element contains the following elements:
| Name | Description | Required |
|---|---|---|
|
|
The HTML code of your web form, to be displayed in a frame in the Worker's web
browser. The HTML must validate against the HTML5 specification.
HTML5 is backwards-compatible with a variety of recent HTML document
specifications. For more information, see http://www.w3.org/TR/html5-diff/ Type: String Default: None Amazon Mechanical Turk appends the following parameters to this URL:
|
Yes |
|
|
The height of the frame, in pixels. Type: Integer Default: None |
Yes |
Example
The following is an example of a complete HTMLQuestion data
structure. Remember that to pass this structure in as the value of a parameter to an operation,
XML characters must be escaped as character entities. For more information,
see Using XML Parameter Values.
<HTMLQuestion xmlns="[the HTMLQuestion schema URL]"> <HTMLContent><![CDATA[ <!DOCTYPE html> <html> <head> <meta http-equiv='Content-Type' content='text/html; charset=UTF-8'/> <script type='text/javascript' src='https://s3.amazonaws.com/mturk-public/externalHIT_v1.js'></script> </head> <body> <form name='mturk_form' method='post' id='mturk_form' action='https://www.mturk.com/mturk/externalSubmit'> <input type='hidden' value='' name='assignmentId' id='assignmentId'/> <h1>What's up?</h1> <p><textarea name='comment' cols='80' rows='3'></textarea></p> <p><input type='submit' id='submitButton' value='Submit' /></p></form> <script language='Javascript'>turkSetAssignmentID();</script> </body> </html> ]]> </HTMLContent> <FrameHeight>450</FrameHeight> </HTMLQuestion>
Preview Mode
The question defined by HTMLQuestion displays when a Worker previews the HIT on
the Amazon Mechanical Turk website, before the Worker clicks the Accept
HIT button. When the HIT is being previewed, the URL has a special value
for the assignmentId: ASSIGNMENT_ID_NOT_AVAILABLE. This is the
same mechanism used for ExternalQuestion HITs.
When a Worker previews a HIT, your HTML should show the Worker everything they will need to do to complete the HIT, so they can decide whether or not to accept it. The easiest way to do this is to simply display the form as it would appear when the HIT is accepted. However, you may want to take precautions to prevent a Worker from accidentally filling out or submitting your form prior to accepting the HIT.
You can use JavaScript to check the assignmentId parameter, and
change the display of the form if the HIT is being previewed
(assignmentId=ASSIGNMENT_ID_NOT_AVAILABLE).
The Form Action
For information about form actions for HTMLQuestion, see " The Form Action" in
ExternalQuestion.
The Answer Data
For information about answer data for HTMLQuestion, see " The Answer Data" in
ExternalQuestion.
Guidelines For Using HTML Questions
Tip
Your HTML code can do many things inside the browser frame, but eventually it must cause
the Worker's browser to load the "externalSubmit" URL in the frame with the results
in POST data. The easiest way to do this is with an HTML form whose fields contain
the HIT results, with a submit button that the Worker clicks. If a
HTMLQuestion HIT prevents the Worker from submitting results back
to Amazon Mechanical Turk using the "externalSubmit" mechanism, the Worker may not
be able to claim rewards or continue doing work without restarting their session.
Amazon Mechanical Turk reserves the right to remove any HTMLQuestion
HITs that are not functioning properly.
Note
Your HIT will be rendered inside an IFRAME that has certain limitations.
The IFRAME operates in HTML5 “sandbox” mode that has extra restrictions on the content that can appear in the
frame. This limits your ability to execute certain code and to use technologies such as Adobe Flash.
To ensure your HITs work as expected, we recommend you test them first in the
Requester Sandbox
Tip
All HTMLQuestion HITs are served from the same domain, regardless of requester.
Bear this in mind if you choose to set cookies from JavaScript in your HTML.
