Live API Documentation

Table of Contents

Using the API

Using the API is a simple three-step process:

  • Step 1 - request a session token (server-side).
  • Step 2 - use the token to start a browser (client-side).
  • Step 3 - embed the the browser in your application (client-side).

You can also try the Live API Demo and see Live API introduction (with a demo video).

Session access tokens

Every browser session requires an access token. You should request the access token server-side and use it on the client-side. Every session token can only be used once. If unused, a session token expires in 1 hour.

You can request a token by GET-ting the following URL and using your Browserling's username and password for basic authentication:

https://api.browserling.com/v1/token

You can also specify the username and password as a query string:

https://api.browserling.com/v1/token?username=login@gmail.com&password=password

If the request succeeds, it will return a JSON string with status set to success and with the token:

{
  "status" : "success",
  "token" : "5ab98da02b5f3b9947f6eb7c97f3e24d"
}

The token is 32 byte lowercase string that matches the [a-f0-9]{32} regular expression.

If the request fails, the HTTP return code will be a failure. The request's status will be error and the error field will contain the message describing the error:

{
  "status" : "error",
  "error" : "incorrect password",
}

For quick testing you can use curl to request a new token:

curl -u username@gmail.com:password https://api.browserling.com/v1/token

Using access tokens

Once you've the access token, you can embed the browser in your application! To do that, first include the browserling.js in your code:

<script src="https://api.browserling.com/v1/browserling.js"></script>

This library exports just one function called Browserling. Create a new Browserling object and pass it the token:

var browserling = new Browserling(token);

You can now choose a browser and embed the browser in your application. You can create and embed as many Browserling objects in your application as you want. Each object requires its own token.

Configuring the browser

Call the configure method to configure the browser:

browserling.configure({
  platformName : 'win',
  platformVersion : 'vista',
  browser : 'ie',
  version : '9',
  url : 'http://www.catonmat.net'
});

In this example we're setting up Internet Explorer 9 on Windows Vista and making it navigate to http://www.catonmat.net.

We currently support Android and Windows platforms, but we're soon adding OSX, iOS and Linux. Valid platforms are:

win
android

Valid Windows platform versions are:

xp
vista
7
8
8.1

Valid Android platform versions are:

4.4
5.0
5.1
6.0

Valid Windows browsers are:

ie
firefox
chrome
safari
opera

Valid Windows versions for the browsers are: 

ie:      6, 7, 8, 9, 10, 11
firefox: 3, 3.5, 3.6, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, nightly
chrome:  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, canary
safari:  4, 5.0.5, 5.1
opera:   10, 10.5, 11, 11.5, 11.6, 12, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, next

Valid Android browsers are:

browser

(This is the default Android browser.)

The configure method also provides a way to hide your browser's cursor:

browserling.configure({
  myCursor : false
});

This hides your native cursor and only displays system's cursor.

You can also make sessions expire after inactivity (no mouse movement or key presses) by setting idleTimeout property:

browserling.configure({
  idleTimeout : 60 * 1000 // timeout after 60 seconds of idling
});

You can limit session length to specific time by setting sessionTimeout property:

browserling.configure({
  sessionTimeout : 5 * 60 * 1000 // session times out after 5 minutes
});

The library also provides several convenience functions to configure platform, platform's version, browser, browser's version and URL separately.

Setting platform:

browserling.setPlatformName(platformName);

Setting platform's version:

browserling.setPlatformVersion(platformVersion);

Setting browser:

browserling.setBrowser(browser);

Setting browser's version:

browserling.setVersion(version);

Setting URL:

browserling.setUrl(url);

Setting idle timeout:

browserling.setIdleTimeout(milliseconds);

Setting session timeout:

browserling.setSessionTimeout(milliseconds);

Setting whether to display your own cursor:

browserling.setMyCursor(show); // boolean

If show is true (default), then your cursor is shown (and also cursor in the VM is shown). If set to false then only cursor in the VM is shown (and your cursor is hidden).

Setting resolution:

browserling.setResolution(resolution); // For example 800x600
Changes screen resolution of the VM to WidthxHeight.

Embedding the browser in your application

You can embed Browserling's browsers anywhere in your application through an iframe. Here's an example. Add a div HTML element with id set to browserling on your page:

<!-- your app -->
<div id="browserling"></div>

Next, find this element using document.querySelector:

var div = document.querySelector('#browserling');

And now use the iframe method to return the iframe DOM element containing just the browser:

var iframe = browserling.iframe();
div.appendChild(iframe);

This will append the iframe containing the browser to your div. The default size of the iframe is 1024x768. You can now interact with the browser!

You can dynamically resize the iframe via resizeIframe method:

browserling.resizeIframe(width, height);

For example, if screen's resolution is 1024x768 but you resize the iframe to 800x600, then the screen will be scaled down to iframe's size and screen's aspect ratio will get preseved.

Navigating

Once you've embedded the browser, you can navigate to a new URL by calling navigate(url) function: 

browserling.navigate(url)

This function will close the current browser, clean the session and restart the browser with the new URL.

If you want to navigate to a new platform/os/browse/version, you need get a new token and replace the current iframe with a new one.

Controlling the mouse

You can control the mouse through the API. You can left click, right click, drag, drag and drop, and move the mouse while left or right buttons are clicked.

Move mouse:

browserling.mouseMove(x, y)

Left click:

browserling.leftClick(x, y)

Right click:

browserling.rightClick(x, y)

Mouse wheel click:

browserling.wheelClick(x, y)

Click any mouse button:

browserling.click(x, y, button)

Left click, right click and mouse wheel click are just three of mouse buttons. A mouse can have up to 8 buttons. You can click these extra buttons. Change the button argument from 1 to 8 to click buttons 1 to 8. Left click is 1, mouse wheel is 2, right click is 3. Other buttons are 4 to 8. Default is 1 (left click).

Press a button (and don't release it):

browserling.mouseDown(x, y[, button])

Presses button but doesn't release it. Button is a number 1 to 8. Default is 1 (left button). Mouse wheel is 2. Right button is 3. Any other mouse buttons are 4 to 8.

Release button:

browserling.mouseUp(x, y)

Drag mouse:

browserling.dragMouse(x1, y1, x2, y2[, button])

Presses button and drags mouse from (x1, y1) to (x2, y2). Button is a number 1 to 8. Default is 1 (left button). Mouse wheel is 2. Right button is 3. Any other mouse buttons are 4 to 8.

Inserting a delay between actions:

browserling.delay(milliseconds)

For example:

browserling.mouseMove(400, 100); // move mouse to 400, 100
browserling.delay(100); // delay 100ms
browserling.leftClick(400, 100); // left click at 400, 100
browserling.delay(100); // delay 100ms
browserling.leftClick(400, 110); // left click at 400, 110
browserling.delay(100); // delay 100ms
browserling.drag(400, 120, 400, 130); // drag from 400, 120 to 400, 130
browserling.delay(100); // delay 100ms

Controlling the keyboard

You can also type text, and send keyboard keys to interact with the browser through the API.

Type text:

browserling.typeText(text)

For example:

browserling.typeText("login");

Press and release a key:

browserling.keyPress(key)

For example:

browserling.typeText('login');
browserling.keyPress(Browserling.Keys.Tab);
browserling.typeText('password');
browserling.keyPress(Browserling.Keys.Enter);

Another example:

browserling.keyPress('a'); // types "a"
browserling.keyPress('B'); // types "B"
browserling.keyPress('c'); // types "c"

Press a key (but don't release it):

browserling.keyDown(key)

For example:

browserling.keyDown(Browserling.Keys.Shift); // press shift
browserling.typeText("hello"); // types "HELLO" because shift is down

Another example:

browserling.keyDown(Browserling.Keys.Ctrl); // press control
browserling.keyPress("a"); // presses Ctrl+a
browserling.keyUp(Browserling.Keys.Ctrl); // release control

Release a key:

browserling.keyUp(key)

For example:

browserling.keyUp(Browserling.Keys.Shift); // release shift

All the functions that take a key can take special keys located in Browserling.Keys. These keys include the following:

Browserling.Keys.Backspace
Browserling.Keys.Tab
Browserling.Keys.TAB (alias of Tab)
Browserling.Keys.Enter
Browserling.Keys.Shift
Browserling.Keys.Control
Browserling.Keys.Ctrl (alias of Control)
Browserling.Keys.Alt
Browserling.Keys.Esc
Browserling.Keys.ESC (alias of Esc)
Browserling.Keys.Space
Browserling.Keys.PageUp
Browserling.Keys.PgUp (alias of PageUp)
Browserling.Keys.PageDown
Browserling.Keys.PgDn (alias of PageDown)
Browserling.Keys.End
Browserling.Keys.Home
Browserling.Keys.Left
Browserling.Keys.Up
Browserling.Keys.Right
Browserling.Keys.Down
Browserling.Keys.Del
Browserling.Keys.Delete
Browserling.Keys.WinKey
Browserling.Keys.OptKey
Browserling.Keys.F1
Browserling.Keys.F2
Browserling.Keys.F3
Browserling.Keys.F4
Browserling.Keys.F5
Browserling.Keys.F6
Browserling.Keys.F7
Browserling.Keys.F8
Browserling.Keys.F9
Browserling.Keys.F10
Browserling.Keys.F11
Browserling.Keys.F12

For example: 

browserling.keyPress(Browserling.keys.ESC);

Inserting a delay between actions:

browserling.delay(milliseconds);
For example: 
browserling.leftClick(200, 140);
browserling.delay(1000);
browserling.typeText("login@gmail.com");
browserling.sendKey(Browserling.Keys.TAB);
browserling.typeText("password");
browserling.sendKey(Browserling.Keys.Enter);

Controlling screen resolution

browserling.changeResolution(resolution);
Changes screen resolution to resolution. Resolution has to be WidthxHeight. For example, 800x600.

Support

Please contact us at or use the support forum if you've any issues with the API or have any questions!

Sales

For all sales inquiries, please contact us at or use the contact form.