API | User Tests HOWTO

Browserscope wants to help you store and aggregate your browser test data. Storing your data in our system gives you the benefit of not having to write a complex, scaling backend with a user agent parser built in. You can download all of your data for offline processing, and we provide a stats table widget that you can embed on your page which shows the median results for your tests.

This is definitely a release early/often feature, and we want to be explicit that things may change or break in the API while we're in alpha mode.

Steps to set up your test

1. Write a test page and host it on your server. You'll need to be able to access the results of your test in Javascript in order to send the results to Browserscope.
   Also, you might consider executing your test via a button, and letting your users know that you'll be recording the results (something like what we do for the main categories here on Browserscope).
2. Sign in to Browserscope.
3. Create a record for your test on the settings page.
4. Add the following code to your test page, so that it executes after your test is complete, allowing you to format a _bTestResults object.

   <script>
   // To save data in Browserscope do something like the following.
   // The syntax is 'test_key': 'value' where test_key is some unique
   // identifier for a piece of data you want to store (no = or , allowed)
   // and value is a numeric value from 0 through .
   // Note: You can only send a maximum of  results in a beacon.
   var _bTestResults = {
     'test_one': 1,
     'test_two': 0
   };
   
   // Beacon the results to Browserscope.
   (function(document) {
     var testKey = 'CHANGE-THIS-TO-YOUR-TEST-KEY';
     var newScript = document.createElement('script'),
         firstScript = document.getElementsByTagName('script')[0];
     newScript.src = 'https://www.browserscope.org/user/beacon/' + testKey;
     firstScript.parentNode.insertBefore(newScript, firstScript);
   }(document));
   </script>
   

   * Don't forget to set the _bTestKey in the snippet to your test ID, which you can find on your settings page.
   You can execute a callback Javascript function after the results data is sent to Browserscope by adding the following parameter to newScript.src:
   

   newScript.src += '?callback=YOUR-FUNCTION-NAME';

   You can bypass Browserscope's IP throttling feature (while testing) by adding the the following parameter to newScript.src:
   

   newScript.src += '?sandboxid=YOUR-SANDBOX-ID';

   Just remember not to publish this widely and/or change it after you're done testing so that no one can corrupt your dataset.
   You can specify a window variable name other than _bTestResults by adding the following parameter to newScript.src:
   

   newScript.src += '?test_results_var=YOUR-VAR-NAME';

5. Send your test page link to all your friends!
6. Check out the "Table" and "CSV" links on the settings to see your results in realtime. (We are still working on how to handle CSV downloads for large datasets.)
7. You can embed your results table in a blog post or on your site using a script tag or an iframe.

   <script
     src="https://www.browserscope.org/user/tests/table/YOUR-TEST-ID?o=js"></script>
   
   Parameters:
     v=top: Shows the "Top Browsers" list. (DEFAULT)
     v=top-d: Shows the "Top Desktop Browsers" list.
     v=top-d-e: Shows the "Top Desktop Edge Browsers" list.
     v=top-m: Shows the "Top Mobile Browsers" list.
     v=0: Shows the browser families.
     v=1: Shows the major browser versions.
     v=2: Shows the minor browser versions.
     v=3: Shows all browser versions.
     o=html: The browserscope HTML table (DEFAULT, good for iframe src)
     o=js: Good as a script src value, renders the results table in your page.
     o=json: A JSON encoded response with the tabular median data.
     w=#: Sets the width of the results table (in px).
     h=#: Sets the height of the results table (in px).
     f=test_key_1,test_key_2: Limit result columns to only these test_keys.
     highlight=1: Colors your cells green to red based on detected min/max values.
     callback=yourFnName: When o=json, wraps json output in "yourFnName()".
         When o=js or o=html it will pass a param which is a class on which
         you can call 1 method named "load" to refresh the resultstable.
         For instance, if you had &callback=myCallback:
           var myBrowserscopeTable;
           var myCallback = function(browserscopeTable) {
             myBrowserscopeTable = browserscopeTable;
           }
           var reloadTable = function() {
             myBrowserscopeTable(); // would refresh the data table.
           }

Create a test record with the API

1. Grab your API key from the settings page. You should then be able to create tests programmatically with a GET or a POST request, like:

   /user/tests/create?api_key=YOUR-API-KEY&name=Some test name&description=A longer description&url=https://yourtest.example.com/page.html

2. The response, if everything is successful, is a JSON string with the newly created test_key.

   {"test_key": "thetestkeyforthenewtest"}

We want your feedback!

Please send any feedback and ideas about these features to the Google Group