Skip to main content

Session Versioning

How Connected Lenses on SPECS keep players on incompatible versions of your Lens out of the same session, and how the Build Version you publish decides who can play together.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
1 platform note
  • SnapchatNot supported
  • SPECSFully supported
  • Camera Kit WebNot supported
  • Camera Kit MobileNot supported

Platform details

  • Snapchat — Not supported. See Connected Framework

  • SPECS — Fully supported.

  • Camera Kit Web — Not supported.

  • Camera Kit Mobile — Not supported.

Session Versioning keeps players who run different versions of your Lens out of the same Connected Lens session. Snap OS applies it to every Connected Lens, so you don't need to add code or install a package to get it. What you control is the Build Version you publish with each release.

Why Snap OS separates sessions by version

A Connected Lens runs a copy of your code on every device in the session, and those copies keep shared state and actions in step. When the copies differ, they can disagree about that state in ways that are hard to reproduce and diagnose.

For example, version 1.0.0 of a board game Lens offers Chess. Version 1.1.0 adds Checkers. A player on 1.1.0 starts a Checkers session and invites a friend who still has 1.0.0. The 1.0.0 code has no Checkers game to load, so the session breaks.

Session Versioning avoids this class of bug: players on incompatible versions never share a session, so you don't handle bug reports from mixed-version play.

How Snap OS decides which versions can play together

Every published build of your Lens has a Build Version in major.minor.patch format, such as 1.2.0. Two devices can join the same session when the major and minor parts of their Lens versions match. The patch part can differ.

Version that created the sessionVersion on the joining deviceResult
1.2.01.2.3Can play together: major.minor matches.
1.2.01.3.0Isolated: minor differs.
1.2.02.2.0Isolated: major differs.

This policy applies to all Lenses. You can't configure it per Lens.

What players see

What a player sees depends on which of the two Lens versions is newer.

The session's creator has the newer version. Players with an older version still discover nearby sessions as usual. When they select the session to join, Snap OS updates their Lens to the creator's version, and they join.

Automatic updates apply only to Lenses that a player installed from the store. A Lens that you side-load onto a device from Lens Studio isn't updated when it joins a session created on a newer version. Install the same version on every test device, or the session is incompatible.

The session's creator has the older version. Players with a newer version who discover the session see a message that the session is incompatible, and they can't join it.

Because the store updates installed Lenses in the background, most players have the latest version of your Lens. In practice, the newest players meet each other, and a player on an old version catches up when they join a newer session.

Choose your versions

You set the version in Lens Studio: open Project Settings, select Platform Settings > SPK Settings, and set Build Version. The version must be higher than any you've published. For the full publishing flow, see Publishing Your Lens.

Which part of the version you increase decides who can play together:

  • Increase minor or major for every release that changes Connected Lens behavior. Snap OS keeps players on the previous version out of sessions with players on the new one, so versions never mix. This is the simplest choice, and the one to use unless you have a reason not to.
  • Increase patch only for releases that are safe to run alongside the previous version. Players on the old and new patch versions share sessions, so the two builds must agree on every shared value, networked event, and prefab. Use this for changes that don't affect what devices exchange, such as a fix to a local visual effect.

A patch release that changes what devices send to each other brings back the mixed-version bugs that Session Versioning exists to prevent. If you aren't sure a change is safe across versions, increase minor.