Skip to main content

Custom Metadata

Add Business-Critical Context to Every Bug Report

Updated over a week ago

When a user reports an issue, Marker.io automatically captures essential technical data like browser version, console logs, and a session replay. This is crucial, but it's only half the story. It tells you what happened technically, but not why it happened in the context of your business.

Custom Metadata is the solution. It allows you to attach any data from your own application directly to every bug report.

For developers, it means faster, more accurate fixes. For the business, it means reduced engineering costs, protected revenue, and a better customer experience.


Why Use Custom Metadata?

The Value for Developers: From Guesswork to Precision

Custom metadata transforms a vague bug report into a precise, actionable ticket. It eliminates the need to chase down information and allows you to:

  • Instantly Reproduce Bugs: Automatically capture the user's ID, role, and permissions to replicate their exact environment.

  • Debug Complex Systems: See which feature flags, A/B test variants, or server environments were active for the user during the session.

  • Understand User Actions: Capture application-specific state, like the items in a shopping cart or the search filters a user applied, to understand the full context of their actions.

  • Stop Wasting Time: Receive a complete, pre-filled bug report so you can spend less time on communication and more time coding.


The Value for the Business: Impacting the Bottom Line

Connecting bug reports to business data provides a clear return on investment. This feature directly impacts key business metrics by helping you:

  • Reduce Engineering Costs: By drastically cutting down the time developers spend reproducing bugs, you focus expensive resources on building new features, not fixing old ones.

  • Protect Revenue: Instantly identify and prioritize bugs that block critical user flows, such as checkout failures or sign-up errors, preventing direct revenue loss.

  • Improve Customer Retention: When a high-value customer reports an issue, their subscription tier or "Enterprise" status can be passed as metadata, ensuring the ticket is triaged with the appropriate priority.

  • Make Data-Driven Decisions: See if bugs correlate with specific customer segments, product versions, or marketing campaigns, turning every bug report into a valuable business insight.


Practical Examples Across Industries

Here’s what kind of business-critical data you can add to your bug reports to provide immediate context.

For SaaS Applications

  • Scenario: A user reports that "the dashboard is broken."

  • Key data to capture:

    • User ID

    • User Role (e.g., Account Admin, Editor, Viewer)

    • Subscription Tier (e.g., Free, Pro, Enterprise)

    • Company or Team ID

    • Active Feature Flags (e.g., new-dashboard-ui, beta-analytics-module)

  • Benefit: Instantly tells the developer this is a high-value Enterprise user with a specific beta feature enabled, allowing them to start debugging the right code immediately.

For E-commerce Platforms

  • Scenario: A customer reports, "I can't complete my purchase."

  • Key data to capture:

    • Cart ID or Session ID

    • Total Cart Value

    • Number of Items in Cart

    • Current Checkout Step (e.g., Shipping, Payment, Confirmation)

    • Applied Discount Code(s)

  • Benefit: Your team can immediately see where the user is in the funnel and what actions they took. This helps determine if it's a payment gateway issue, a problem with a promo code, or a bug in the shipping calculator, preventing lost sales.

For Complex Transactional Websites (e.g., Travel, Booking)

  • Scenario: A user reports, "The search results are wrong."

  • Key data to capture:

    • Loyalty Program Status (e.g., Gold Member, Basic)

    • Search Origin (e.g., LHR)

    • Search Destination (e.g., JFK)

    • Dates for Departure and Return

    • Number of Passengers or Guests

  • Benefit: Instead of guessing, the developer can run the exact same search the user performed. This helps determine if the issue is with inventory, pricing rules for a specific route, or a bug affecting certain loyalty tiers.

For Regulated Industries (e.g., Pharma, Finance)

  • Scenario: A professional reports an error while viewing a secure document.

  • Key data to capture:

    • User Type (e.g., Healthcare Professional, Financial Advisor)

    • Document ID or Name

    • Document Version

    • Regulatory Approval Region (e.g., FDA, EMA)

    • User's Authentication Status

  • Benefit: Compliance and IT can instantly verify if the user has the correct credentials to view a specific document version in their region. This helps resolve access issues quickly while maintaining a strict security and audit trail.

For Digital Agencies

  • Scenario: An agency team member reports a bug on a client project.

  • Key data to capture:

    • Client ID or Name

    • Project Name

    • Website Environment (e.g., Staging, Production)

    • CMS Platform and Version (e.g., WordPress 6.5)

    • Name of the Agency Reporter

  • Benefit: The bug report is automatically routed to the correct project team. The developer has all the core technical details without having to ask which of the agency's 50+ clients or projects this issue is for.


How to Add Custom Metadata

There are two main ways to add custom metadata to your Marker.io reports. Pick the one that best fits how your site or app works.

Method 1: Set Metadata in Your JavaScript Snippet

If you have a piece of code that runs when your page loads, you can add your custom metadata right there. This ensures that every bug report includes these details from the start.

Example:

<script>
window.markerConfig = {
project: 'your_project_id', // Replace with your actual Marker.io project ID
source: 'snippet',
customData: {
userID: getUserID(),
userStatus: getUserStatus(),
appVersion: getAppVersion()
}
};
</script>

In this example, functions like getUserID() are placeholders representing the code in your own application that returns real data. When this code runs, these functions will return actual values. For instance:

  • getUserID() might return 123abc

  • getUserStatus() might return Enterprise Customer

  • getAppVersion() might return v2.3.1

This method keeps your code neat and allows your application to dynamically control what data is sent to Marker.io.

Method 2: Update Metadata Later With Marker.setCustomData()

Use this method when you need to add or update metadata as a user navigates your site, such as when their login status changes or they move through a checkout process. The Marker.io SDK allows you to update metadata at any time.

Example:

Marker.setCustomData({
userRole: getUserRole(),
featureFlags: getFeatureFlags()
});

If your functions return userRole: 'Editor' and featureFlags: ['newMenu', 'betaSearch'], this data will be added to the report. This makes your bug reports even more flexible, ensuring the details are always up-to-date.


Supported Data Types

Marker.io allows you to add various types of metadata:

Type

Description

Number

For quantities, like cartItemCount: 3.

Boolean

For yes/no conditions, like isBetaTester: true.

String

For words and codes, like userRole: 'Editor' or language: 'en'.

Array

For lists of values, like availableFeatures: ['darkMode', 'videoChat'].

Objects

For structured info, like a full user profile or search parameters.


How to View Custom Metadata

When someone reports an issue, the custom metadata you’ve set will appear directly in the Marker.io dashboard and in your connected project management tool (like Jira, Trello, etc.). This means no more digging through logs or asking for details—everything you need is right there.

Example of Custom Metadata in Marker.io issue page.

Example of Custom Metadata in Trello

Tips for Keeping Metadata Clear

  • Use Short, Clear Names: Use userID instead of UserIdentificationNumberString.

  • Keep It Organized: For lots of metadata, use objects to group related info (e.g., user: {id: 123, status: 'active'}).

  • Don’t Overdo It: Add details that help solve bugs, not every single piece of data you can think of.


Summary

By attaching business-critical details from your application to every report, you ensure that the data is always accurate, up-to-date, and useful to the people trying to solve the problem. This leads to faster bug fixes, lower development costs, and a better end-user experience.

Did this answer your question?