User Interaction Component

The User Interaction component lets your script ask for input during execution. It provides two separate capabilities: - Web view interactions for displaying web content (showUrl, showHtml). - A simple Continue button for lightweight acknowledgements (showContinueButton). - A text input dialog (requestInput).

All methods are suspend functions and must be called from a coroutine context (e.g., inside onStart, execute, or onFinish).

Web View Interactions (showUrl, showHtml)

When implementing your script's onStart, execute, or onFinish methods, you can access the User Interaction component through the provided ComponentProvider.

suspend fun execute(provider: ComponentProvider) {
    val userInteraction = provider.userInteraction()

    // Show a URL and wait for a specific condition
    val urlResponse = userInteraction.showUrl("Login Page", "https://example.com/login") { request ->
        request.url.contains("success") // Terminates when URL contains "success"
    }

    // Show a URL with custom request headers
    val urlResponse = userInteraction.showUrl(
        "Authenticated Page",
        "https://example.com/dashboard",
        headers = mapOf("Authorization" to "Bearer token123")
    ) { request ->
        request.url.contains("dashboard")
    }

    // Show HTML content and wait for form submission
    val htmlResponse = userInteraction.showHtml("Input Form", htmlContent) { request ->
        request.url.contains("form-submitted")
    }

    // Process the response
    processUserResponse(htmlResponse)
}

Example: HTML form flow

The following example shows how to create a simple HTML form to ask the user for a confirmation code:

val html = """
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Confirmation Code</title>
</head>
<body>
    <h2>Enter Confirmation Code</h2>
    <form action="https://www.cereal-automation.com" method="POST">
        <input type="text" name="confirmationCode" placeholder="Enter code here" required>
        <button type="submit">Submit</button>
    </form>
</body>
</html>
"""

// Show the HTML and wait for the form submission
val request = provider.userInteraction().showHtml("Confirmation Code", html.trimIndent()) {
    it.url.contains("cereal-automation.com")
}

// Extract and use data from the response
provider.logger().info("Form submitted to: ${request.url}")
provider.logger().info("Request method: ${request.method}")
provider.logger().info("Form data: ${request.postData}")

Continue Button

Use showContinueButton() when you only need the user to acknowledge and allow the script to proceed, without navigating to a web page or submitting a form.

Behavior: - Renders a Continue button inside the task row. - Suspends execution until the user clicks the button, then resumes. - Returns: None (suspends until the user clicks Continue).

Example:

// Inform the user about the next step
provider.logger().info("Ready to proceed to the next step. Click Continue when you are ready.")

// Wait until the user clicks Continue
provider.userInteraction().showContinueButton()

// Continue with your logic
performNextStep()

Text Input

Use requestInput to prompt the user for a plain-text string during execution.

val code = provider.userInteraction().requestInput(
    title = "Two-Factor Authentication",
    description = "Enter the 6-digit code from your authenticator app."
)

Processing Responses for showUrl/showHtml

The WebResourceRequest returned by showUrl and showHtml contains information about the interaction that triggered the termination condition:

Property	Type	Description
`url`	`String`	The URL that triggered the termination condition.
`method`	`String`	HTTP method used (GET, POST, etc.).
`requestHeaders`	`Map<String, String>`	Headers included in the request.
`postData`	`Map<String, String>?`	Form data submitted via POST; `null` for non-POST requests.

Error Handling

Exception	When thrown
`UserInteractionCanceledException`	The user dismissed the dialog or web view without completing the interaction.
`WebResourceException`	A web resource failed to load. Contains `failedUrl`, `errorText`, and `errorCode`.

Always handle these exceptions if your script must remain robust against user cancellation:

try {
    val response = provider.userInteraction().showUrl("Login", "https://example.com/login") {
        it.url.contains("success")
    }
} catch (e: UserInteractionCanceledException) {
    return ExecutionResult.Error("Login cancelled by user.")
}

Best Practices

Design simple, clear interfaces for user input
Provide clear instructions within the HTML/web page
Include validation to ensure data quality
Set appropriate termination conditions to detect when user input is complete
Keep UI elements consistent with Cereal's design where possible
Use showContinueButton() for lightweight acknowledgements (e.g., "Press the confirmation link in the email you received, then continue")
Always handle UserInteractionCanceledException to avoid unhandled exceptions when users dismiss the UI