Metadata Effects

Metadata allows you to store viewer specific data for use in Firebot.

You can use metadata by using the Set User Metadata and Remove User Metadata effects, found in the “Select New Effect” box when adding a new effect. They’re listed under the “ALL” and “Scripting” tabs. Metadata works by storing data (basically text) associated with a specific viewer's username.

Using Metadata you can tailor interactive experiences to individual viewers like tracking stats, preferences, or progress within a game or loyalty system. It works similarly to Custom Variables, but custom variables are not associated with a single viewer, and unless you have changed the settings do not persist when you close Firebot, meaning that when you close Firebot all data is deleted. Metadata on the other hand is stored for each user persistently and can be used across Firebot sessions.

Configuring Metadata Effects

Username

Specify the username for who you want to configure or modify the metadata. This should generally be the $user variable to affect the user triggering the event.

Metadata Key

This is where you define the name of the specific piece of information you want to store. Choose a descriptive key without spaces (e.g., favoriteColor, level, totalPoints). A common practice is using camelCase.

Data

This is the actual value you want to store under the specified Metadata Key. This can be static text, numbers, or any other data, or you can reference Firebot's built-in variables using the $vars button to create dynamic values.

Advanced (Optional)

You can click on the blue "Advanced" text to open the Property Path section. This enables you to directly access or modify specific parts of complex data structures, such as arrays or objects, already saved under the Metadata Key.

Note: If the metadata key does not already contain an object or array, entering a Property Path will do nothing.

When creating a Property Path, use dot notation to define which specific property or index you want to update:

• Array Example: ["apple", "banana", "cherry"]
  To target "banana", the Property Path is: 1

• Object Example: {"fruit":"apple", "color":"red"}
  To target "apple", the Property Path is: fruit

• Array of Objects Example: [{"fruit":"apple"}, {"fruit":"banana"}]
  To target "apple" in the first object, the Property Path is: 0.fruit

Accessing and Using Metadata

Metadata is accessed using the $userMetadata replace variable.

• $userMetadata[username, metadataKey] Get the metadata associated with the user.

Other examples

• $userMetadata[username, metadataKey, defaultValue] Provide a default value if one doesn't exist for the user.

• $userMetadata[username, metadataKey, null, propertyPath] Provide a property path (using dot notation) or array index as a second argument.

Example: Tracking Viewer Stats

Premise: Suppose you want to keep track of how many times a viewer has checked into your stream.

1. Add Set User Metadata Effect to Check In: Set up your check in, either with a new command or a channel reward, and add a "Set User metadata" effect.

2. Set Up The Metadata Effect:

   • Username: $user (This ensures the metadata is stored for the user who triggered the command/reward)
   • Metadata Key: checkInCount
   • Data: $math[$userMetadata[$username, checkInCount] + 1]

   Every time this event is triggered, the user's checkInCount will increase by one.

3. Display the Stat: In a chat message or overlay effect, use the following:

   • $userMetadata[$username, checkInCount]

   This will display the number of times the user has triggered the command or reward.

Removing User Metadata

If you need to clear data for a specific user (for example, resetting a viewer's stats or clearing a specific preference), you can use the Remove User Metadata effect.

Configuring the Effect

Username

Specify the username of the viewer whose metadata you want to remove. Use $user to affect the user currently triggering the command or event.

Metadata Key

Enter the specific Key of the metadata you wish to delete.

Viewing and Managing Metadata

You can view and manage metadata stored for a user by going to the "VIEWERS" tab in Firebot, selecting a viewer and looking at the "METADATA" table available there. You can see what metadata has been stored on the viewer, what the keys are to that data, and the data itself. You can also edit or delete metadata directly from this table.