APIs for Browser Monitoring

⚙️ APIs for Browser Monitoring

GermainUX provides JavaScript APIs that allow developers to control browser monitoring and create application-specific events, metrics, transactions, and diagnostic logs.

Most browser monitoring is automatic and does not require API calls. Use these APIs when the application needs to control monitoring programmatically or send business and technical data that GermainUX cannot detect automatically.

🧩 Component support

📚 API categories

Common use cases

Use the Browser Monitoring APIs to:

• Start or stop monitoring based on consent.

• Clear monitoring state when a user signs out.

• Record an application-specific event such as Payment Failed.

• Record a numeric measurement such as the number of search results.

• Measure the duration of a business operation.

• Add technical context for an error handled by the application.

• Create custom browser KPIs for application-specific behavior.

• Correlate business milestones with user sessions and technical evidence.

Monitoring Control API

Start monitoring

Browser monitoring normally starts automatically after germainapm.js is downloaded and initialized. Calling start() is unnecessary during a standard deployment.

Use it when monitoring was previously stopped or when the application must start monitoring programmatically:

germainApm.start(
  settings: MonitoringSettings,
  onAllTabs?: boolean
): void;

Example:

const settings = germainApm.getDefaultSettings();

germainApm.start(settings);

Stop monitoring

Use stop() to remove the active monitoring instrumentation:

germainApm.stop(onAllTabs?: boolean): void;

Example:

germainApm.stop(true);

Calling stop():

• Stops monitoring immediately.

• Removes the active monitoring instrumentation.

• Does not flush data still waiting in the browser.

• Does not remove the germainApm code from the page.

• Does not necessarily clear the stored monitoring state.

• Allows monitoring to start again after a full page load, hard navigation, or browser refresh.

Use uninstall() instead when pending data must be flushed or the stored monitoring state must be cleared.

Uninstall monitoring

Use uninstall() to stop monitoring, flush data available in the browser cache, and optionally remove the stored monitoring state:

germainApm.uninstall(
  clearSessionState?: boolean,
  onAllTabs?: boolean
): void;

A custom logout handler should use:

germainApm.uninstall(true, true);

This helps prevent the next authenticated user from inheriting monitoring metadata associated with the previous user.

Monitoring can start again after a full page load, hard navigation, or browser refresh.

Multi-tab behavior

The optional onAllTabs parameter uses the browser’s BroadcastChannel capability.

When supported:

• start(..., true) can start monitoring across open tabs.

• stop(true) can stop monitoring across monitored tabs.

• uninstall(..., true) can uninstall monitoring across monitored tabs.

When the browser does not support BroadcastChannel, the operation cannot be propagated to other tabs through this mechanism.

Custom Data API

The Custom Data API captures application-specific information that GermainUX does not collect automatically.

Create a custom event

Use createEvent() to record a discrete application or business event:

germainApm.api.createEvent(
  name: string,
  details?: Record<string, any>
): void;

Example:

germainApm.api.createEvent("Product Added to Wishlist", {
  productId: "SKU-123",
  category: "Shoes"
});

This creates a data point under the Browser Event KPI.

Other examples include:

• Payment Failed

• Checkout Completed

• Search Returned No Results

• User Changed Subscription

• Document Uploaded

Use stable event names so GermainUX can aggregate and analyze occurrences consistently.

Create a custom metric

Use createMetric() to record a numeric measurement:

germainApm.api.createMetric(
  name: string,
  value: number,
  details?: Record<string, any>
): void;

Example:

germainApm.api.createMetric("Search Result Count", 12, {
  category: "Running Shoes"
});

This creates a data point under the Browser Metric KPI.

Other examples include:

• Number of search results.

• Cart value.

• Number of records displayed.

• Queue depth shown to a user.

• Number of validation failures.

Do not send numeric values as formatted strings.

Create a transaction with a known duration

Use createTransaction() when the duration has already been calculated:

germainApm.api.createTransaction(
  name: string,
  duration: number,
  details?: Record<string, any>
): void;

Example:

germainApm.api.createTransaction("Quote Generated", 2.45, {
  quoteType: "Renewal"
});

This creates a data point under the Browser Transaction KPI.

Measure a transaction between start and end

Use startTransaction() and endTransaction() when GermainUX should calculate the duration.

Start the transaction:

germainApm.api.startTransaction(
  name: string,
  details?: Record<string, any>
): void;

End the transaction:

germainApm.api.endTransaction(
  name: string,
  details?: Record<string, any>
): void;

Example:

germainApm.api.startTransaction("Generate Report", {
  reportType: "Weekly Sales"
});

// Application operation

germainApm.api.endTransaction("Generate Report", {
  outcome: "Completed"
});

The same transaction name must be used for the start and end calls. The resulting duration is recorded under the Browser Transaction KPI.

Suitable transactions include:

• Authentication.

• Search.

• Quote generation.

• Document upload.

• Checkout.

• Report generation.

• Record creation.

• Application-specific workflow steps.

Ensure that every started transaction can reach an end call, including failure paths when appropriate.

Create a diagnostic log

Use germainApm.log() to add a custom internal monitoring log:

germainApm.log(
  level: "TRACE" | "INFO" | "WARN" | "ERROR" | "NONE",
  message: string,
  obj?: Object
): void;

Example:

germainApm.log("INFO", "Checkout step completed", {
  step: "Shipping"
});

Logs are available in the browser through:

germainApm.rootWindow.state.debugLog

To send selected logs to GermainUX as data points, configure:

• MonitoringSettings.constants.logLevel

• MonitoringSettings.constants.logLevelToEmitAsFacts

Collected logs are available under the Germain Agent Debug KPI.

Log a handled exception

An exception handled by the application may not be visible to automatic unhandled-error monitoring. Use a custom log when the failure requires diagnostic visibility:

try {
  runApplicationOperation();
} catch (error) {
  germainApm.log(
    "ERROR",
    "Application operation failed",
    error
  );
}

Do not log an exception automatically if it may contain sensitive data that has not been reviewed or sanitized.

Create a trace log

germainApm.log("TRACE", "Application state changed", {
  timestamp: Date.now(),
  state: "WaitingForApproval"
});

Trace logging can generate substantial data. Enable and emit it only when required for a defined diagnostic use case.

From custom data to analytics

Custom events, metrics, and transactions become available for GermainUX analysis:

These data points can be analyzed using measures, pivots, trends, drill-through, user-session context, and applicable custom insights.

A Custom Replay Insight can expose a selected event—such as Payment Failed or Checkout Completed—on the Session Replay timeline whenever it occurs in a user session.

A Watch can notify GermainUX users when an existing event, metric, transaction, or other insight meets conditions of interest. A Watch does not create the underlying insight.

Naming recommendations

Use names that are:

• Stable across application releases.

• Specific enough to identify the business or technical condition.

• Consistent in capitalization and wording.

• Independent of dynamic values.

• Suitable for aggregation.

Recommended:

Payment Failed
Checkout Completed
Quote Generated
Search Result Count

Avoid:

Payment failed for user 18462 at 10:43:19

Place dynamic context in the details object instead of the name.

Privacy and security

Custom API calls can send application data to GermainUX. Before adding custom details or logs:

• Do not collect passwords, access tokens, authentication cookies, secrets, or payment credentials.

• Avoid collecting personal information unless it is required and approved.

• Prefer internal or pseudonymous identifiers.

• Mask, hash, or remove sensitive values.

• Keep detail objects small and relevant.

• Avoid sending complete application objects, responses, or DOM elements.

• Apply the organization’s access-control and retention requirements.

• Validate custom data in a non-production environment before deployment.

The API accepts JavaScript objects, but that does not mean every property should be collected.

Error handling

Custom monitoring must not interfere with the monitored application.

When integrating the API:

• Confirm that germainApm is available before calling it when monitoring may load asynchronously.

• Do not block the user workflow while waiting for a monitoring call.

• Avoid changing application behavior if monitoring is unavailable.

• Keep custom processing lightweight.

• Test consent, logout, multi-tab, and page-navigation behavior.

Example:

if (window.germainApm?.api) {
  window.germainApm.api.createEvent(
    "Checkout Completed"
  );
}

Deployment and configuration

ℹ️ Get Help

The Germain Team can help you set this up. Contact GermainUX Support.