Firebot v5.62 Viewer Role tracking and User variable changes

In Firebot v5.62, we have changed how some of our username variables and viewer role processing work. To better explain, let's talk about how Twitch stores user data and how Firebot .

How Twitch Stores User Data

Twitch identifies users by three distinct fields:

• User ID: This is a unique identifier that never changes for a user account, no matter what other information changes on that account.
• Username: This is the name you login to Twitch with (e.g. sreject). Per Twitch rules, this may be changed occasionally.
• Display Name: In most instances, this is the same as your username, but can have different capitalization (e.g. SReject vs sreject). However, for users of some languages, Twitch offers localized display names that do not directly correlate to their usernames.

In most cases, Firebot looks up viewers by either their ID or username. Because user IDs never change, Twitch will always return the same user account when the app searches by an ID. When looking up viewers by username in real-time, especially in chat, this usually works fine because viewers don't change usernames often. Apps cannot directly lookup a single user by their display name, but because most users have the same username and display name, sending their display name in as the search criteria for their username works in most instances.

How Firebot Tracks Viewer Roles

For most roles (Firebot roles like Active Viewer, Twitch roles like sub/mod/etc., and Team roles), those are built dynamically when Firebot connects to Twitch or a viewer enters chat. Firebot doesn't store data on those roles long term because they can change frequently and the app can request/rebuild them at any time.

For custom roles, because those are specific to a streamer's Firebot setup, the app stores those as part of the streamer's Firebot data. Prior to v5.62, most roles, including custom roles, were being tracked by display name. This means that when someone changes their username, or their localized display name, that breaks the custom role for that viewer. Also, localized display names have proven to give either false positives or not correctly indicate that a viewer is in a certain custom role. So we need to change how we track roles.

Changes to Role Tracking

In v5.62+, Firebot now tracks viewers in ALL roles by their user ID, which means custom roles will be stored in an updated format that contains not only a viewer's display name, but also their user ID and username. Firebot will also update custom roles on startup to refresh the usernames/display names stored in the custom role database. This ensures that once you add a viewer to a custom role, no matter what changes a viewer makes to their username or display name, roles will always stay current for viewers and whenever you view your custom roles, you'll see the most up-to-date usernames and localized display names (if applicable).

As part of updating to v5.62+, Firebot will detect a legacy custom role file and migrate any valid viewers to the new format.

Please verify your custom roles after updating to v5.62.

Any viewers in custom roles who have changed their usernames or localized display names WILL NOT MIGRATE and you WILL NEED TO ADD THEM AGAIN, as they are already broken today and we will not be able to find their user information on Twitch.

For example, let's say the viewer SRejectsBiggestFan with a user ID of 1234567 currently has the custom role of Fan Club. Prior to v5.62, if the viewer changes their username to SRejectsHugestFan, they will not be automatically updated. The streamer will need to manually remove the viewer's old display name from the custom role and then manually add the new name back to the role in order for the viewer to keep that role. In v5.62+, Firebot will know that the user ID associated with that viewer is 1234567. Because user IDs never change, that viewer will continue to be in that custom role without the streamer needing to change anything, even if the viewer changes their Twitch handle a third time to SRejectsGigaFan.

Changes to User Variables

Prior to v5.62, the $username and $user variables in Firebot would return back a user's display name, not their actual username. This caused problems for viewers with localized display names, as those could not directly be translated to their username. We later added $useridname to account for this, but this also caused some confusion and does not align with standard naming conventions, including Twitch's.

Therefore, the $user/$username variables will now return the actual username, not the display name. In most cases, streamers will not notice a different other than these variables returning values in all lowercase. However, for users who prefer the viewer's formatted display name (e.g. for chat messages or overlays) or want a viewer's localized display name, you will use the new $userDisplayName variable. This variable returns the formatted or localized display name for a viewer.

Because of these changes, $useridname has been deprecated. It will continue to work for now, but it will be removed in a future Firebot version.

Summary

In Firebot v5.62 and later...

• Viewer roles, especially custom roles, will be tracked by a viewer's unchangeable user ID, not their display name/username
• Older custom role databases will be migrated to the new format, but will not migrate invalid/out of date usernames/display names
• $user/$username will now return the viewer's Twitch username
• $userDisplayName will return the formatted/localized display name
• $useridname has been deprecated