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

Node.js

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}`);
})();

Python

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.