Versioning
What we promise not to change in a widget embed, and how a breaking change would ship.
The rules
Within /widgets/v1/, attribute names, config keys, methods and event names are only ever added to. Breaking changes ship at a new URL. Class names inside the shadow root and the DOM the widget renders are internal and change without notice: if you need to style something we don't expose, ask us to add it.
What is covered
The data-or-* attribute names and their accepted values; the shape of window.OddsRelay and the config object passed to mount(); the custom event names the widget dispatches on your page; and the URLs above. Anything not on that list is internal: class names inside the shadow root, the DOM structure, and the contents of the bundle are all free to change at any time.
What counts as a breaking change
Removing or renaming an attribute, a config key, a method or an event; narrowing the values an attribute accepts; or changing what an existing value does. Adding an attribute, adding an accepted value, adding a method or an event, and fixing a wrong number are not breaking.
Unknown values never throw
An attribute value the runtime does not recognise falls back to the default and the widget still renders. That is what lets us add values without breaking the embeds already on your pages.
How a breaking change ships
At a new major URL, /widgets/v2/, announced before it exists. /widgets/v1/ keeps serving the v1 contract; we do not migrate anyone by changing the bytes under a URL they already published.
How long a version is supported
A major URL is served indefinitely once published. If we ever intend to stop, the notice period starts at twelve months, is announced by email to every account with an active browser key, and never starts before the next major URL has been available for six months.
Checking your version
window.OddsRelay.version reports the exact bundle version running on the page, so you can check a pinned embed from your own console without contacting us.
What each URL promises
| URL | Promise | Who decides when it changes |
|---|---|---|
| /widgets/v1/oddsrelay-widgets.js | The v1 contract, always. The bytes move forward with fixes and additions. | We do. That is the point of it. |
| /widgets/v/<version>/oddsrelay-widgets.js | These exact bytes, forever. Verifiable with a Subresource Integrity hash. | You do. Nothing reaches this embed until you change the URL. |
| /widgets/oddsrelay-widgets.js | Identical to v1, served permanently so pre-versioning embeds keep working. | We do. Treat it as v1 under its original name. |
The current version is 0.9.0, reported at runtime on window.OddsRelay.version. How each URL is cached is on Widgets.