Register a version
A version registration records a specific (product, version) pair in your tenant, optionally with the date that version was released to users. Versions are how Beacon groups events for trends, comparisons, and release-window analytics.
When you need to register a version
By default, Beacon auto-registers versions the first time an event with a new source_version arrives. You don’t have to do anything — keep shipping, and the version appears in selectors and filters once the first event for it lands.
There are two cases where manual registration matters:
- Strict version mode is on for the product. Strict mode rejects events whose
source_versionisn’t already registered. In that mode, you must register the version before sending events. See Strict version mode for the why and how. - You want to record a
release_date. Auto-registration leavesrelease_datenull. If you want the field populated — for future release-window analytics, for audit trail, or for the Latest tie-breaker in the version selector — you need to register manually.
How to get there
In the sidebar, expand Settings → Products, click the product whose version you want to register, then click the Versions tab. The page lists every version currently associated with this product. The top-right Register new version button opens the registration modal.
Requires the manage_products permission. Users without it see the page but not the button.
Fill in the form
| Field | Required | Notes |
|---|---|---|
| Version | Yes | A free-text version string, matching what your SDK is sending as source_version. Each version is unique per product — re-submitting a (product, version) pair that already exists is rejected. |
| Release date | No | The date the version was made available. Format YYYY-MM-DD. Leave blank if you don’t have one or don’t need one. Can be set later by editing the version. |
Click Register version to submit. The new version appears in the list immediately.
What gets recorded
Beacon stores the version as active under the chosen product, along with the optional release date. Every Beacon surface that filters or groups by version — Event Explorer, Property Explorer, Sessions, the version selector — picks it up from there.
release_date — what it’s used for today
A registered release_date is captured today but is not yet used by most analytics surfaces. The version selector uses it as a tie-breaker when resolving the Latest option (most recent release_date wins). No other current Beacon surface consumes it — Dashboard release annotations are driven by allowlist activations, and Usage Insights does not segment by release date today.
Why register one anyway?
- Future-proofing. Release-window analytics is in active development. Once it ships, surfaces will read this field. Setting it today means your historical releases already have metadata when those features go live.
- Audit trail. Having an authoritative record of “when was v1.4 released?” is useful for support conversations and post-incident reviews even if no analytics consumes the value yet.
If neither applies, skip the field. The version still works fine.
Common questions
I registered the wrong release date — can I fix it? Yes. The version row has an edit affordance on the Versions page. Change the date and save.
Duplicate registration?
Re-submitting the modal with a (product, version) that already exists returns 409 version_already_registered. To change a value on an existing version, use the edit affordance, not the registration modal.
What if I’m sending events for a version I haven’t registered?
If strict mode is off (default), the version is auto-registered with release_date = null. If strict mode is on, the event is rejected with UNREGISTERED_VERSION — see Strict version mode for the SDK behavior on rejection.
Do I need a registered version to create an allowlist? No. Allowlists are governed independently. See Create your first allowlist.