crackercat / android-webmonkey Goto Github PK

WebMonkey

No-frills light-weight Android web browser with support for Greasemonkey user scripts.

Minor improvement to the WebView GM library demo application.

Background

• the WebView GM library enhances the native Android System WebView with support for Greasemonkey functions and the management of user scripts

Improvements

• an additional Javascript API interface to provide the following functions to user scripts:
  • GM_toastLong(message)
  • GM_toastShort(message)
  • GM_getUrl()
    • returns a String containing the URL that is currently loaded in the WebView
    • use case:
      • allows the userscript to detect whether the page has been redirected
        • server response status codes: 301, 302
    • example:
      • var is_redirect = (GM_getUrl() !== unsafeWindow.location.href)
  • GM_resolveUrl(urlRelative, urlBase)
    • returns a String containing urlRelative resolved relative to urlBase
    • where:
      • [required] urlRelative is a String URL: relative path
      • [optional] urlBase is a String URL: absolute path
        • default value: the URL that is currently loaded in the WebView
    • examples:
      • ('video.mp4', 'http://example.com/iframe_window.html')
      • ('video.mp4')
  • GM_startIntent(action, data, type, ...extras)
    • starts an implicit Intent
    • where:
      • [required, can be empty] action is a String
      • [required, can be empty] data is a String URL
      • [required, can be empty] type is a String mime-type for format of data
      • [optional] extras is a list of String name/value pairs
    • example:
      • ('android.intent.action.VIEW', 'http://example.com/video.mp4', 'video/mp4', 'referUrl', 'http://example.com/videos.html')
  • GM_loadUrl(url, ...headers)
    • loads a URL into the WebView with additional HTTP request headers
    • where:
      • [required] url is a String URL
      • [optional] headers is a list of String name/value pairs
    • example:
      • ('http://example.com/iframe_window.html', 'Referer', 'http://example.com/parent_window.html')
  • GM_loadFrame(urlFrame, urlParent)
    • loads an iframe into the WebView
    • where:
      • [required] urlFrame is a String URL: the page loaded into the iframe
      • [required] urlParent is a String URL: value for window.top.location.href and window.parent.location.href as observed from within the iframe
    • example:
      • ('http://example.com/iframe_window.html', 'http://example.com/parent_window.html')
    • use case:
      • "parent_window.html" contains:
        • an iframe to display "iframe_window.html"
        • other content that is not wanted
      • though a userscript could easily do the necessary housekeeping:
        • detach the iframe
        • remove all other DOM elements from body
        • reattach the iframe
      • this method provides a better solution:
        • removes all scripts that are loaded into the parent window
        • handles all the css needed to resize the iframe to maximize its display within the parent window
        • makes it easy to handle this common case
    • why this is a common case:
      • "iframe_window.html" performs a check to verify that it is loaded in the proper parent window
      • example 1:

          const urlParent = 'http://example.com/parent_window.html'
          try {
            // will throw when either:
            // - `top` is loaded from a different domain
            // - `top` is loaded from the same origin, but the URL path does not match 'parent_window.html'
            if(window.top.location.href !== urlParent)
              throw ''
          }
          catch(e) {
            // will redirect `top` window to the proper parent window
            window.top.location = urlParent
          }

      • example 2:

          const urlParent = 'http://example.com/parent_window.html'
          {
            // will redirect to proper parent window when 'iframe_window.html' is loaded without a `top` window
            if(window === window.top)
              window.location = urlParent
          }

  • GM_exit()
    • causes WebMonkey to close

Settings

• default browser home page
  • Continue where you left off
  • Blank page
  • Userscripts by developer
  • Userscripts at Greasy Fork
• script update interval
  • number of days to wait between checks
  • special case: 0 disables automatic script updates

Caveats

• userscripts only run in the top window
  • they are not loaded into iframes

Legal:

• copyright: Warren Bank
• license: GPL-2.0