WebBrowser API

Version: 1.0.0

Status:

WebBrowser interface for Thunder framework.

(Defined with IWebBrowser in IBrowser.h)

Introduction

Scope

This document describes purpose and functionality of the WebBrowser interface (version 1.0.0). It includes detailed specification about its methods and properties as well as sent notifications.

Case Sensitivity

All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym	Description
API	Application Programming Interface
HTTP	Hypertext Transfer Protocol
JSON	JavaScript Object Notation; a data interchange format
JSON-RPC	A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term	Description
callsign	The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID	Description
HTTP	HTTP specification
JSON-RPC	JSON-RPC 2.0 specification
JSON	JSON specification
Thunder	Thunder API Reference

Description

WebBrowser JSON-RPC interface.

This interface uses legacy lowercase naming convention. With the next major release the naming convention will change to camelCase.

Methods

The following methods are provided by the WebBrowser interface:

WebBrowser interface methods:

Method	Description
collectgarbage	Initiate garbage collection

collectgarbage ^method

Initiate garbage collection.

Parameters

This method takes no parameters.

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.collectgarbage"
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

Properties

The following properties are provided by the WebBrowser interface:

WebBrowser interface properties:

Property	R/W	Description
url	read/write	Page loaded in the browser
visibility	read/write	Browser window visibility state
fps	read-only	Current framerate the browser is rendering at
headers	read/write	Headers to send on all requests that the browser makes
useragent	read/write	UserAgent string used by the browser
localstorageenabled	read/write	Controls the local storage availability
httpcookieacceptpolicy	read/write	HTTP cookies accept policy
bridgereply	write-only	Response for legacy $badger
bridgeevent	write-only	Send legacy $badger event

url ^property

Provides access to the page loaded in the browser.

Value

Name	Type	M/O	Description
(property)	string	mandatory	Page loaded in the browser

Name	Type	M/O	Description
(property)	string	mandatory	Loaded URL

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.url"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "https://example.com"
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.url",
  "params": "..."
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

visibility ^property

Provides access to the browser window visibility state.

Value

Name	Type	M/O	Description
(property)	string	mandatory	Browser window visibility state (must be one of the following: hidden, visible)

Name	Type	M/O	Description
(property)	string	mandatory	Visiblity state (must be one of the following: hidden, visible)

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.visibility"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "visible"
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.visibility",
  "params": "visible"
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

fps ^property

Provides access to the current framerate the browser is rendering at.

This property is read-only.

Value

Name	Type	M/O	Description
(property)	integer	mandatory	Current FPS

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.fps"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": 0
}

headers ^property

Provides access to the headers to send on all requests that the browser makes.

Value

Name	Type	M/O	Description
(property)	opaque object	mandatory	Headers to send on all requests that the browser makes

Name	Type	M/O	Description
(property)	opaque object	mandatory	Single string containing a list of headers

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.headers"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {}
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.headers",
  "params": {}
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

useragent ^property

Provides access to the userAgent string used by the browser.

Value

Name	Type	M/O	Description
(property)	string	mandatory	UserAgent string used by the browser

Name	Type	M/O	Description
(property)	string	mandatory	UserAgent value

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.useragent"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "Mozilla/5.0 (Linux; x86_64 GNU/Linux) AppleWebKit/601.1 (KHTML, like Gecko) Version/8.0 Safari/601.1 WP"
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.useragent",
  "params": "..."
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

localstorageenabled ^property

Provides access to the controls the local storage availability.

Value

Name	Type	M/O	Description
(property)	boolean	mandatory	Controls the local storage availability

Name	Type	M/O	Description
(property)	boolean	mandatory	Controls the local storage availability

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.localstorageenabled"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": false
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.localstorageenabled",
  "params": false
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

httpcookieacceptpolicy ^property

Provides access to the HTTP cookies accept policy.

Value

Name	Type	M/O	Description
(property)	string	mandatory	HTTP cookies accept policy (must be one of the following: always, exclusivelyfrommaindocumentdomain, never, onlyfrommaindocumentdomain)

Name	Type	M/O	Description
(property)	string	mandatory	HTTP Cookie Accept Policy Type (must be one of the following: always, exclusivelyfrommaindocumentdomain, never, onlyfrommaindocumentdomain)

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.httpcookieacceptpolicy"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "always"
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.httpcookieacceptpolicy",
  "params": "never"
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

bridgereply ^property

Provides access to the response for legacy $badger.

This property is write-only.

Value

Name	Type	M/O	Description
(property)	string	mandatory	Base64 encoded JSON string response to be delivered to $badger.callback

Example

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.bridgereply",
  "params": "..."
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

bridgeevent ^property

Provides access to the send legacy $badger event.

This property is write-only.

Value

Name	Type	M/O	Description
(property)	string	mandatory	Base64 encoded JSON string response to be delivered to window.$badger.event

Example

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.bridgeevent",
  "params": "..."
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

Notifications

Notifications are autonomous events triggered by the internals of the implementation and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.

The following events are provided by the WebBrowser interface:

WebBrowser interface events:

Notification	Description
loadfinished	Initial HTML document has been completely loaded and parsed
loadfailed	Browser failed to load page
urlchange	Signals a URL change in the browser
visibilitychange	Signals a visibility change of the browser
pageclosure	Notifies that the web page requests to close its window
bridgequery	A Base64 encoded JSON message from legacy $badger bridge

loadfinished ^notification

Initial HTML document has been completely loaded and parsed.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.url	string	mandatory	The URL that has been loaded
params.httpstatus	integer	mandatory	The response code of main resource request

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "loadfinished",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.loadfinished",
  "params": {
    "url": "https://example.com",
    "httpstatus": 200
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.loadfinished.

loadfailed ^notification

Browser failed to load page.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.url	string	mandatory	The URL that has been failed to load

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "loadfailed",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.loadfailed",
  "params": {
    "url": "https://example.com"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.loadfailed.

urlchange ^notification

Signals a URL change in the browser.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.url	string	mandatory	The URL that has been loaded or requested
params.loaded	boolean	mandatory	Loaded (true) or not (false)

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "urlchange",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.urlchange",
  "params": {
    "url": "https://example.com",
    "loaded": false
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.urlchange.

visibilitychange ^notification

Signals a visibility change of the browser.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.hidden	boolean	mandatory	Hidden (true) or Visible (false)

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "visibilitychange",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.visibilitychange",
  "params": {
    "hidden": false
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.visibilitychange.

pageclosure ^notification

Notifies that the web page requests to close its window.

Notification Parameters

This notification carries no parameters.

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "pageclosure",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.pageclosure"
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.pageclosure.

bridgequery ^notification

A Base64 encoded JSON message from legacy $badger bridge.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.message	string	mandatory	Requested action

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "bridgequery",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.bridgequery",
  "params": {
    "message": "..."
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.bridgequery.

WebBrowser API

Table of Contents

Introduction

Scope

Case Sensitivity

Acronyms, Abbreviations and Terms

References

Description

Methods

collectgarbage method

Parameters

Result

Example

Request

Response

Properties

url property

Value

Example

Get Request

Get Response

Set Request

Set Response

visibility property

Value

Example

Get Request

Get Response

Set Request

Set Response

fps property

Value

Example

Get Request

Get Response

headers property

Value

Example

Get Request

Get Response

Set Request

Set Response

useragent property

Value

Example

Get Request

Get Response

Set Request

Set Response

localstorageenabled property

Value

Example

Get Request

Get Response

Set Request

Set Response

httpcookieacceptpolicy property

Value

Example

Get Request

Get Response

Set Request

Set Response

bridgereply property

Value

Example

Set Request

Set Response

bridgeevent property

Value

Example

Set Request

Set Response

Notifications

loadfinished notification

Notification Parameters

Example

Registration

Notification

loadfailed notification

collectgarbage ^method

url ^property

visibility ^property

fps ^property

headers ^property

useragent ^property

localstorageenabled ^property

httpcookieacceptpolicy ^property

bridgereply ^property

bridgeevent ^property

loadfinished ^notification

loadfailed ^notification

urlchange ^notification

visibilitychange ^notification

pageclosure ^notification

bridgequery ^notification