PuppeteerLite Extension V1

Extensions
1

PuppeteerLite Extension — Documentation

A lightweight Puppeteer-like automation toolkit for Kodular / MIT App Inventor using a built-in Android WebView.
No external libraries, Java 7 compatible.

List Block

The image shows a code script composed of coloured blocks with labelled commands designed to automate web interactions and data extraction using Puppeteer in a visual programming environment. (Captioned by AI)
The image shows a code script composed of coloured blocks with labelled commands designed to automate web interactions and data extraction using Puppeteer in a visual programming environment. (Captioned by AI)1211×743 57.8 KB

Features

  • Goto(url, headers) — navigate with optional request headers
  • Evaluate(js) — run JavaScript, get result via event
  • Click(selector) — click an element (CSS selector)
  • Type(selector, text, clearBefore) — type into inputs/textarea/contentEditable
  • WaitForSelector(selector, timeoutMs) — wait for element to exist
  • SetRequestBlocking(patterns) — block URLs by wildcard patterns (*)
  • SetUserAgent(ua) — override user agent
  • SetViewport(width, height) — control embedded WebView size
  • GetHTML() — get full HTML via event
  • ScreenshotViewport(file.png) & ScreenshotFullPage(file.png)
  • Events for page lifecycle, console messages, network blocks, errors

Requirements

  • Kodular or MIT App Inventor (Companion/Compiler with WebView & JavaScript enabled)
  • Android device with internet access
  • App permissions: INTERNET, ACCESS_NETWORK_STATE (added by extension), optional WRITE_EXTERNAL_STORAGE (for screenshots to app folder)

Installation

  1. Build PuppeteerLite.aix (or use the provided compiled AIX).
  2. In Kodular Creator (or App Inventor):
  • Import Extension → choose PuppeteerLite.aix.
  • Drag PuppeteerLite (non-visible component) onto your project.
  1. Add a VerticalArrangement (or Horizontal) to host the internal WebView.

Quick Start

  1. Screen.Initialize:
  • PuppeteerLite.Attach(VerticalArrangement1, true)
  • PuppeteerLite.SetViewport(1080, 1600) (or 0,0 for MATCH_PARENT)
  • PuppeteerLite.Goto("https://example.com", create empty dictionary)
  1. Listen to events:
  • PageStarted(url) / PageLoaded(url)
  • ProgressChanged(progress)
  1. Automate:
  • WaitForSelector("#login", 10000)
  • On OnSelector("#login"): Click("#login"), Type("#user","name",true), etc.

Blocks Reference

Functions

  • Attach(arrangement, enableDebug)
    • Attach internal WebView to a visible container (Vertical/Horizontal Arrangement).
    • enableDebug=true enables Chrome remote debugging (if device supports it).
  • Goto(url, headers)
    • Navigate to a URL.
    • headers:
      • YailDictionary (key→value), or
      • YailList of pairs: (( "Header-Name" "Value" ) ( "X-Token" "abc" ))
    • If headers is empty/invalid, loads without extra headers.
  • Reload(), Back(), Forward()
    • Basic navigation controls.
  • Evaluate(js)
    • Run JavaScript in the page context.
    • Result emitted via EvaluateResult(result) as JSON-encoded string.
  • Click(selector)
    • Dispatch a click on document.querySelector(selector).
    • Emits ClickResult(boolean ok).
  • Type(selector, text, clearBefore)
    • Focus, (optionally) clear, append text, and fire input/change.
    • Emits TypeResult(boolean ok).
  • WaitForSelector(selector, timeoutMs)
    • Polls until document.querySelector(selector) returns a node or timeout.
    • Emits OnSelector(selector) if found, otherwise WaitTimeout(selector).
  • GetHTML()
    • Emits the entire page HTML via EvaluateResult(htmlString).
  • SetUserAgent(ua)
    • Overrides the UA string for next loads.
  • SetViewport(widthPx, heightPx)
    • Resize the embedded WebView.
    • Use <=0 for MATCH_PARENT.
  • SetRequestBlocking(patterns)
    • patterns = YailList like ("*doubleclick.net*" "*.tracker/*").
    • Blocks matching requests via shouldInterceptRequest.
    • Emits OnRequestBlocked(url, method) per hit.
  • ClearRequestBlocking()
    • Remove all blocking rules.
  • ScreenshotViewport(fileNamePng)
    • Saves PNG of current visible viewport to app files dir.
    • Emits ScreenshotResult(success, path, error).
  • ScreenshotFullPage(fileNamePng)
    • Measures scrollHeight, re-layouts WebView, renders entire page once.
    • Saves PNG to app files dir.
    • Emits ScreenshotResult(success, path, error).
  • SetCookie(url, cookie)
    • Example: SetCookie("https://site.com", "key=value; Path=/;").
  • FlushCookies()
    • Persists cookies.

Events

  • Attached() — Fired after Attach() succeeds.
  • PageStarted(url) — Navigation started.
  • PageLoaded(url) — Navigation finished.
  • ProgressChanged(progress 0..100) — Load progress.
  • ConsoleMessage(level, message, line, sourceId) — From page console.
  • OnRequestBlocked(url, method) — URL blocked by pattern.
  • ErrorReceived(code, description, url) — WebView error.
  • EvaluateResult(result) — Result of Evaluate() or GetHTML().
  • ClickResult(ok) — Result of Click().
  • TypeResult(ok) — Result of Type().
  • OnSelector(selector) — WaitForSelector() success.
  • WaitTimeout(selector) — WaitForSelector() timeout.

Usage Recipes

Login flow

  1. Initialize
  • Attach(VerticalArrangement1, true)
  • SetViewport(1080, 1600)
  • Goto("https://example.com/login", empty dict)
  1. When PageLoaded
  • WaitForSelector("#username", 10000)
  1. When OnSelector(“#username”)
  • Type("#username", "myuser", true)
  • Type("#password", "mypassword", true)
  • Click("button[type=submit]")
  1. Optionally wait for post-login selector:
  • WaitForSelector(".dashboard", 15000)

Scrape page HTML

  • Call GetHTML(), then handle EvaluateResult(htmlString).
    Parse the string in your app to extract data.

Block Ads/Trackers

  • On Screen.Initialize:
    • SetRequestBlocking( make list("*doubleclick.net*", "*googletagmanager.com*", "*adservice.google.com*") )
  • Listen to OnRequestBlocked(url, method) for diagnostics.

Screenshots

  • Viewport: ScreenshotViewport("view.png")
  • Full page: ScreenshotFullPage("full.png")
  • Receive path via ScreenshotResult(success, path, error)
    Files are stored in app’s files directory (e.g., /storage/emulated/0/Android/data/<your.package>/files/ or internal equivalent).

Custom headers

  • Build a YailDictionary of headers:
    • keys: "User-Agent", "Authorization", "X-Token", etc.
  • Or a YailList of pairs:
( ( "Authorization" "Bearer abc123" )
  ( "X-Requested-With" "XMLHttpRequest" ) )
  • Call: Goto("https://example.com/api", headers)

Notes & Limitations

  • This is WebView-based (not Chrome DevTools Protocol), so:
    • No native CDP features (network HAR, response bodies, performance tracing).
    • JavaScript executes with evaluateJavascript (async).
  • Click/Type rely on DOM access via CSS selectors; hidden/shadow DOM may require custom JS in Evaluate.
  • Full-page screenshot uses a single re-layout render up to scrollHeight; extremely long pages may consume memory.
  • Some sites may block mobile WebView UAs; use SetUserAgent to mimic desktop if needed.
  • Cookies and storage are WebView-scoped; use SetCookie/FlushCookies to manage.

Troubleshooting

  • Nothing shows in container
    Ensure you used Attach(YourArrangement, true) before Goto().
  • Selectors not found
    • Verify selector correctness in desktop DevTools.
    • Consider waiting for the element: WaitForSelector("#id", 10000).
    • Iframes: you need to execute JS targeting the frame (WebView has limited iframe control).
  • Click/Type does nothing
    • Element may be offscreen/covered; try scrolling via Evaluate("window.scrollTo(0, document.body.scrollHeight)").
    • Use more specific selectors or Evaluate to trigger framework actions.
  • Screenshots fail
    • Check file name ends with .png.
    • Ensure the page finished loading (PageLoaded) before screenshot.
    • Very long pages may trigger OOM — use viewport screenshot or paginate.
  • Headers ignored
    • Only applied on Goto() request. Subsequent subresources are not guaranteed to inherit custom headers.

Download

com.rasitech.puppeteerlite.aix (37.2 KB)

FAQ

Q: Can I run headless (no visible WebView)?
A: Android WebView doesn’t support true headless mode. You can hide the arrangement, but rendering still occurs.

Q: Can I get network response bodies like Puppeteer?
A: Not directly. You can call Evaluate to fetch() resources client-side and return results, or build simple bridges via JS.

Q: XPath support?
A: Not built-in. You can inject a small XPath helper via Evaluate (pure JS). If you want, extend ClickByXPath, TypeByXPath using JS.

Q: File path for screenshots?
A: Extension saves to the app’s files directory. The exact path is returned in ScreenshotResult.

Changelog

  • v4
    • Java 7 compliance; no external libs.
    • Removed YailDictionary.getMap() usage — header building via keySet() / YailList pairs.
    • Added full descriptions to eliminate compile warnings.
  • v3
    • Initial public release with request blocking & screenshots.

License

  • Source is provided “as is.” You may include it in your apps/extensions.
  • Please keep credit: PuppeteerLite by rasi tech.
2 Likes