Browser Swarm Docs
  • 🚀Welcome
    • What is Browser Swarm?
  • Understanding Headless Browsers
  • Quickstart Guide
  • Framework Compatibility
  • 🌟 Core Concepts
    • Starting a Browser Task
  • Interacting with Browser Tasks
  • Task Lifecycle Management
  • ⚙️Advanced Features
    • Stealth Automation
  • Proxy Integration
  • Real-Time Monitoring
  • Responsive Viewports
  • Session Debugging & Replay
  • File Handling (Downloads & Uploads)
  • Capturing Screenshots & PDFs
  • Persistent Contexts
  • Extension Support
  • Session Tagging & Metadata
  • 🎯Practical Examples
    • Automating Form Interactions
  • Efficient Data Scraping
  • Automated Web Testing
  • Cost Optimization Strategies
  • Handling Extended Tasks
  • Selecting Execution Regions
  • Monitoring Resource Usage
  • Leveraging Task Metadata
  • Pricing and Subscription
  • Account and Team Management
  • Managing Limits and Concurrency
  • Authentication Automation
  • Security Best Practices
  • 🔌Ecosystem Integrations
    • Integration Overview
  • 💻Developer Resources
    • APIs and SDKs Overview
  • Node.js Integration
  • Python Integration
  • Browser Task API
  • Project Management API
  • Context Management API
  • Browser Extensions API
  • 🙋‍♂️Support & Resources
    • Getting Help
  • Dashboard Overview
  • FAQs & Troubleshooting
Powered by GitBook
On this page
  • 📌 Why Use Session Metadata?
  • 🛠️ Attaching Metadata to Sessions
  • 🔍 Querying Sessions by Metadata
  • ⚠️ Metadata Structure and Limitations
  • 💡 Best Practices

Session Tagging & Metadata

Browser Swarm allows you to attach custom metadata to your browser sessions. This feature enables you to organize, filter, and analyze sessions based on your specific criteria, enhancing the manageability and observability of your automation workflows.


📌 Why Use Session Metadata?

As your automation scales, keeping track of individual sessions becomes crucial. By tagging sessions with metadata, you can:

  • Categorize sessions by project, client, or task.

  • Track session outcomes like success or failure statuses.

  • Associate sessions with specific test runs or user actions.

  • Filter sessions for analysis or debugging purposes.

This structured approach simplifies session management and aids in deriving meaningful insights from your automation activities.


🛠️ Attaching Metadata to Sessions

When creating a new session, you can include a userMetadata object containing your custom key-value pairs. This metadata is stored with the session and can be used for querying and analysis.

Example

import { BrowserSwarm } from 'browser-swarm-sdk';

const bs = new BrowserSwarm({ apiKey: process.env.BROWSER_SWARM_API_KEY });

(async () => {
  const session = await bs.sessions.create({
    projectId: process.env.BROWSER_SWARM_PROJECT_ID,
    userMetadata: {
      testRunId: 'TR-12345',
      feature: 'login',
      status: 'in-progress'
    }
  });
  console.log(`Session ID: ${session.id}`);
})();
from browser_swarm import BrowserSwarm
import os

bs = BrowserSwarm(api_key=os.environ["BROWSER_SWARM_API_KEY"])

session = bs.sessions.create(
    project_id=os.environ["BROWSER_SWARM_PROJECT_ID"],
    user_metadata={
        "testRunId": "TR-12345",
        "feature": "login",
        "status": "in-progress"
    }
)

print(f"Session ID: {session.id}")

This metadata becomes part of the session's data and can be utilized for filtering and analysis.


🔍 Querying Sessions by Metadata

To retrieve sessions based on specific metadata, use the q parameter in your API requests with the following syntax:

user_metadata['key']:'value'

For example, to find all sessions related to the 'login' feature:

user_metadata['feature']:'login'

When constructing these queries, ensure that the query string is URL-encoded. For instance, in JavaScript:

const query = encodeURIComponent("user_metadata['feature']:'login'");

This query can then be used with the sessions listing endpoint to filter sessions accordingly.


⚠️ Metadata Structure and Limitations

When using session metadata, keep in mind the following constraints:

  • Data Type: Only string values are supported. Convert numbers and booleans to strings as needed.

  • Structure: Use a nested JSON object without arrays.

  • Size Limit: The total metadata size must not exceed 512 characters.

  • Querying: Only equality checks are supported in queries.

Example of a valid metadata structure:

{
  "order": {
    "status": "shipped"
  },
  "priority": "high",
  "active": "true"
}

To query sessions with a shipped order status:

user_metadata['order']['status']:'shipped'

Remember to URL-encode the query string when making API requests.


💡 Best Practices

  • Consistent Naming: Use standardized keys for metadata to ensure uniformity across sessions.

  • Descriptive Values: Choose clear and descriptive values to make filtering and analysis more intuitive.

  • Avoid Sensitive Data: Do not include personal or sensitive information in metadata.

  • Efficient Structure: Keep the metadata structure shallow to stay within size limits and simplify querying.

By adhering to these practices, you can effectively leverage session metadata to enhance your automation workflows.


Incorporating session metadata into your Browser Swarm automation enables better organization, tracking, and analysis of your browser sessions, leading to more efficient and insightful automation processes.

PreviousExtension SupportNextAutomating Form Interactions

Last updated 1 month ago