Skip to main content

Live Session Viewer

Use the live session viewer to watch and interact with your Aidolon browser sessions as they happen. Each session provides a unique live viewer URL, which you can easily share or embed into your applications.

What You'll Learn​

  • How to find the Live Viewer URL for a session
  • Embedding the Live Viewer using an HTML iframe
  • Customizing the embedded viewer's appearance and interactivity
  • Common use cases for the Live Viewer
  • Troubleshooting common issues

Prerequisites​

  • An active Aidolon browser session
  • A valid Aidolon API key (or set via environment variables)
  • Basic understanding of HTML and Python

Finding the Live Viewer URL​

When initiating a session with the Aidolon Browser Client, the returned session object will have a live_viewer_url property. Use this URL to view your active session.

Example in Python​

from aidolon_browser_client.browser.browser_session import BrowserSession

# Start a new browser session
with BrowserSession() as browser:
    browser.navigate("https://example.com")

    # Get the live session viewer URL
    live_viewer_url = browser.live_viewer_url
    print(f"Live Session Viewer URL: {live_viewer_url}")

Execute this script, then open the printed URL in a browser to view the session live.

Embedding Live Session Viewer​

To integrate the live session viewer into your app or website, use an iframe in HTML.

HTML Example​

<iframe
  src="{live_viewer_url}"
  style="width: 100%; height: 600px; border: none;"
></iframe>

Make sure to replace {live_viewer_url} with your actual session URL.

Customizing Embedded Views​

Modify the embedded viewer by adding query parameters to the live viewer URL. These parameters let you adjust the viewer's appearance and functionality.

Parameters​

ParameterTypeDefaultDescription
pageIdstring(empty)(Optional) Targets a specific page by its unique identifier.
pageIndexstring(empty)(Optional) Displays a specific tab using its index (e.g., pageIndex=0 for the first tab).
themestring"dark"Sets the visual theme. Choose between "dark" or "light".
interactivebooleantrueTurns session interaction (clicking, scrolling, navigation) on or off.
showControlsbooleantrueShows or hides navigation and session control elements like the URL bar.

Example of Customization​

<iframe
  src="{live_viewer_url}?theme=light&interactive=true&showControls=true"
  style="width: 100%; height: 600px; border: none;"
></iframe>

This sets a light theme, enables full interaction, and makes all control elements visible.

Common Use Cases​

  • Real-time Session Sharing: Easily distribute a live view of your browser session using the provided URL.
  • Integrated Monitoring: Embed the live viewer into internal dashboards or customer support tools.
  • Human-in-the-Loop Automation: Allow remote users to interact with and control automated browser processes in real time.

Troubleshooting​

  • Viewer Appears Blank: Ensure your session is active and that actions (navigation, interactions) have occurred.
  • Interaction Problems: Confirm the interactive parameter is set to true for user interactions.
  • Size Issues: Check that your iframe has clearly defined dimensions (width and height).
  • Session Timeout: Ensure your session remains active, noting that sessions typically expire after a default timeout (e.g., 5 minutes) unless extended.

Best Practices​

  • Secure Embedding: Be mindful that the URL provides access; only embed in trusted environments if interaction is enabled.
  • Performance: Avoid embedding too many live viewers on a single page.
  • Session Length: Keep sessions only as long as needed, especially if embedding for others to view.
  • Use Placeholders: Show a placeholder or loading indicator in your UI while the iframe loads.

Security Notes​

Remember that the live viewer URL does not have authentication. Anyone with the URL can access the session view. Be careful when sharing or embedding in environments accessible to the public.