Developers Documentation

This script is capable of being controlled by other scripts. All the helper scripts that are designed for this script uses this special messaging system to control it. I use a localStorage variable to accept commands because it can be used with any script as long as it's on the same domain name. The postMessage way of sending messages is mostly for cross domain messaging so I didn't need that if all scripts are running on mturk.com. At this time I only accept localStorage communication but may accept postMessage in the future.

No questions yet.

Ping and Pong Simple Messages

To communicate with the script you must set a localStorage item with some data. The first Item variable name it looks for is 'JR_message_ping_pandacrazy'. The item value isn't important because it only uses the theTarget and url value from the localStorage. I just set the value to an object which must be a string so I use stringify on the object: {"command":"areYouThere","time":datetime})).

  • To send a ping for attention:
    • localStorage.setItem("JR_message_ping_pandacrazy", JSON.stringify({"command":"areYouThere","time":(new Date().getTime())}));

Once the main script gets the message it will send a pong message which uses a unique variable. The variable starts with 'JR_message_pong_' and ends with '_pandacrazy'. So by adding an event for storage you can find any variables that get changed. Watch for the variables that start with ''JR_message_pong' and you will know that the main script is running. That is how I add buttons to mturk pages with the helper script only if the main script is running.

  • For example this is what I used to receive a pong message.
    • window.addEventListener("storage", mainListener, false);
  • In the mainListener function I would look for the key which starts with the pong string. I also make sure there is a newValue and the location is the location for your script.
    • if ( e.key == 'JR_message_pong_' + gScriptName && e.newValue && gLocation == (JSON.parse(e.newValue).url)) {

Now this is a simple ping and pong messaging which is done for simple things like find out if the main script is running. I do recommend to do this so users won't have buttons that do nothing. In fact you don't have to do a ping for some of the external actions for this script but this is a good beginning of how the process of messaging is done.

No questions yet.

Simple External Actions

Here are some actions that can be sent to the script without a ping and pong process. All of these actions need to be sent some specific data in a specific format.

  • Sending a message to main script with the data it needs. gScriptname = "pandacrazy";
    • localStorage.setItem("JR_message_" + gScriptName, JSON.stringify(data));
  • The data should be in this format with command being the actual action command string from the list below.
    • {"time":(new Date().getTime()),"command":command,"data":objectData}
  • The objectData that it's looking for is different for each action so that will be explained in the action commands below.
  • The jobData that holds the hit info must be in this object data format but not all have to be assigned:
    • {"requesterName":"","requesterId":"","groupId":"","pay":"","title":"","duration":"0","hitsAvailable":0,"timeLeft":"","totalSeconds":0,"hitId":"","continueURL":"","returnURL":"","durationParsed":null,"jobNumber":"","friendlyRName":"","friendlyTitle":"","assignedOn":"","description":"","qual":"","keywords":""};

Here are the simple actions:

  • acceptedhit - Send info about a hit accepted outside of the script.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}
  • returned - Send info about a hit that was returned.
    • This needs the data to have this object: {"hitId":thisHitID}
  • submitted - Send info about a hit that was submitted.
    • This needs the data to have this object: {"hitId":thisHitID}
  • queueData - Send updated queue info to the script. Only uses the number in queue at this time.
    • This needs the data to have this object: {"queueLength":length}
  • projectedEarnings - Send the projected earnings from the dashboard.
    • This needs the data to have this object: {"projectedEarnings":earnings}
  • addOnlyJob - Add info about a hit that needs to be added but don't collect.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}
  • addOnceJob - Add info about a hit that needs to be added and collected now but only one time.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}
  • addJob - Add info about a hit that needs to be added and collected now.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}
  • addSearchJob - Add info about a hit that needs to be added and collected now.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}
  • startcollect - Add info about a hit that needs to be added and collected now.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}
  • stopcollect - Add info about a hit that needs to be added and collected now.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}
  • startgroup - Add info about a hit that needs to be added and collected now.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}
  • stopgroup - Add info about a hit that needs to be added and collected now.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}
  • pause - Add info about a hit that needs to be added and collected now.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}
  • unpause - Add info about a hit that needs to be added and collected now.
    • This needs the jobData object defined above to be sent like this: {"jobData":jobData}

 

  • So for example if I wanted to send the hitID of a hit that I accepted I would use this to send it to the main script:
    • localStorage.setItem("JR_message_" + gScriptName, JSON.stringify(
      {"time":(new Date().getTime()),"command":"acceptedhit","data":
      {"hitId":thisHitID} }));

The time data isn't actually used by the script so that could be left out but in the future I might need it so I just send it anyway. In the advanced messaging in the next topic it uses a unique ID that it gets from the date but it doesn't use it from the received message.

 

No questions yet.