Jam.Metadata

Include custom debug data in every bug report!

Your users don’t know what A/B tests they’re in, what their user ID is, what your app version is, or what the last random seed they generated was. But your app does. And this data is essential to reproducing the UI and behaviors of your app.

You may've had to hop on call with a customer or teammate in the past, asked them to open the browser console, and run a command, then show you the output, all in order to get this custom state. Or even worse, you just had to tell them “I’m not sure how to reproduce the bug”.

With one function call, jam.metadata(), you can ensure that every Jam submitted from your website includes the metadata you need to debug the bug.

And that means every Jam. Does your customer support team ask customers to install Jam to submit bugs? Yep, even those bugs will have the metadata you need attached.

Getting Started

1. First, install the Jam SDK into your project:

npm install '@jam.dev/sdk'
# or:
yarn add '@jam.dev/sdk'

Alternatively, you can include a script tag referencing the SDK library:

<script src="https://unpkg.com/@jam.dev/sdk"></script>

2. Once the script is included, you can start using the jam.metadata function to include debug information with every Jam a user files on your site:

// In the root of your app, the place where
// you would initialize your app's stores and
// render React onto your root element
import { jam } from "@jam.dev/sdk";

// We call the jam.metadata function once.
// The function we pass into it is called whenever
// a Jam is captured, so the data inside is always
// live and never stale.

jam.metadata(() => {
  return {
    userId: 5492,
    teamId: 'd3b59ce8-95f1-410c-bb5e-9dc598599336',
    timeSincePageLoad: performance.now(),
    a: { nested: ['object', 'or', 'array'] }
    // and any other debug data you'd need
});

3. Now, your metadata will be shown inside every Jam filed from your site!

What data can you include in Jam.Metadata?

Beyond static values and local variables, you can also pass in:

• State from your app stores (for example: user ID, team ID, the last 5 items in your user's checkout cart, which feature flags are enabled, etc.)

• Values from localStorage

• Whatever data you need to debug your bugs!

Test it out live, Right now!

To see this live, try going to our example site and creating a Jam! This example site already has Jam.Metadata integrated, so as soon as you capture any kind of Jam, we'll include up-to-date debugging info.

Your Jam should include metadata that looks like the following:

Your site's metadata, included! Try creating more todo items to see how todoItemCount changes

Objects provided will be expanded and pretty-printed when you click on them:

Here, we've snapshotted our app's last todo item, in case rendering it caused the bug!

The live code for is here, and the jam.metadata() call is here, for your reference. This demo shows a realistic example of how to include data from a store. In this case, we use MobX for state management, but you can pull from Redux, Zustand, or any other store you prefer.

When is metadata captured?

Metadata is captured when a bug reporter decides to create a Jam.

Limits, Constraints, and Errors

When calling jam.metadata(), keep in mind that the returned metadata object must be:

1. An Object instance (for example, { a: 1, b: 2}, and not window, which is a Window instance)

2. Under 10kb in size, when serialized.

3. Serializable. If JSON.stringify can't stringify it, we can't store it!

If your app throws an error, or the above conditions aren't met, Jam will both log in your browser's live console, and display an error when the Jam is captured:

It says "developers" in monospace, so you know it's for you ;)

As always, if you have suggestions or requests for the Jam.metadata feature, or the direction our SDK should evolve in, our inbox is open at [e-mail]!