When someone reports a bug through Marker.io, a lot of useful context is automatically captured, including:

Browser details
Screen size
Console logs
Session replay video

This technical background information helps your team understand the environment in which the bug occurred. But now, with custom metadata, you can also attach additional details that are specific to your application and business logic. By adding information like user roles, environment flags, or cart details, you help your dev team quickly reproduce and fix issues without guesswork.

Why Use Custom Metadata?

Even with all the automatic technical data, a short description like “The page froze” might still leave your team guessing. Custom metadata fills in the gaps by letting you add contextual data that’s directly relevant to your business logic, such as:

User account status
App version
Experiment flags
Current user flow (e.g., checkout step, lesson page, or campaign ID)

This extra layer of information makes your bug reports more actionable and reduces the need for back-and-forth clarifications. It ensures everyone has the data they need from the start.

Types of Custom Metadata Supported

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 with multiple properties, like a full user profile.

Examples for Different Teams

Your team might work in many fields, but the idea is the same: figure out what details are most helpful for your kind of bug reports.

E-Commerce Teams: Include “orderStatus: getOrderStatus()” or “paymentMethod: getPaymentMethod()” so you know what the buyer was doing when the error happened.
Marketing Teams: Add “campaignId: getCampaignId()” or “adPlacement: getAdPlacement()” to understand which promos the user saw.
Product Teams: Include “userRole: getUserRole()” and “appVersion: getAppVersion()” to see which features the user had access to.
Support Teams: Add “ticketId: getTicketId()” or “customerSegment: getCustomerSegment()” for extra help context.
Education Teams: Include “courseId: getCourseId()” or “lessonPage: getLessonPage()” to track which part of the learning material had issues.

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(),
    paymentMethod: getPaymentMethod(),
    orderStatus: getOrderStatus()
  }
};
</script>

In this example, the functions getUserID(), getUserStatus(), getAppVersion(), getPaymentMethod(), and getOrderStatus() are placeholders. They represent the code in your own application that returns real data. When the code runs in your website, these functions will return actual values, such as:

getUserID() might return 123abc
getUserStatus() might return Enterprise Customer
getAppVersion() might return v2.3.1
getPaymentMethod() might return Visa
getOrderStatus() might return Pending

Final Metadata Example (After Your Functions Run):

UserID: 123abc
UserStatus: Enterprise Customer
AppVersion: v2.3.1
PaymentMethod: Visa
OrderStatus: Pending

By using these functions, you keep your code neat and let your app control what data to send to Marker.io.

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

Sometimes you need to add or update metadata while the user is navigating your site. Maybe you learn more about them after they log in, or maybe the order status changes as they move through your checkout process. In these cases, you can use the Marker.io SDK to update metadata at any time.

Example:

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

If your functions return something like userRole: 'Editor' and featureFlags: ['newMenu', 'betaSearch'], then your metadata might end up looking like this:

UserRole: Editor
FeatureFlags: [newMenu, betaSearch]

This makes your bug reports even more flexible. You can make sure the details are always up-to-date and reflect the current situation.

How to View Custom Metadata

When someone reports an issue, the custom metadata you’ve set will appear right in the Marker.io dashboard and in the connected tool you’re using (like Jira). That means no more digging through logs or asking around for details. Everything you need is right there, making it much easier to find and fix the problem.

Example of Custom Metadata in Marker.io issue page.

Example of Custom Metadata in Trello

Tips for Keeping Metadata Clear

Use Short Names: Instead of something very long, use “UserID” instead of “UserIdentificationNumberString.”
Keep It Organized: If you have lots of metadata, consider grouping related info or using objects.
Don’t Overdo It: Add the details that help solve bugs, not every single piece of data you can think of.

Before and After Example

Before (Hard-Coded and Hard-to-Read):

user:("id":"123abc", "UserStatus":"Enterprise Customer", "CreatedAt":"2024-02-02", "PaymentMethod":"Visa")

After (Dynamic and Easier to Understand):

<script>
window.markerConfig = {
  project: 'your_project_id',
  source: 'snippet',
  customData: {
    userID: getUserID(),
    userStatus: getUserStatus(),
    createdAt: getCreatedAtDate(),
    paymentMethod: getPaymentMethod(),
  }
};
</script>

If those functions return real values, you might see:

UserID: 123abc
UserStatus: Enterprise Customer
CreatedAt: 2024-02-02
PaymentMethod: Visa

This makes the details clearer and lets you control the data from your code. It’s more flexible and easier for everyone on your team to understand.

Summary

By including details from functions in your code, you make sure the data is always accurate, up-to-date, and useful to the people trying to solve the problem.

Need Help?

If you have any questions, comments, or corrections, chat with us at the bottom right of our web pages.

Console Logs

Webhooks Integration

How to integrate Marker.io into your web app

Integrate Marker.io with Remix

How to Use a Custom Button