Skip to main content

Building Connected Lenses

The Lens Studio tools for building and testing Connected Lenses on SPECS: Sync Kit, session IDs, multiple Previews, the Connected Lens Monitor, testing on several devices, and data that outlives a session.

  • 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.

You build Connected Lenses for SPECS in Lens Studio. Lens Studio has tools for building and testing Connected Lenses in the editor and on SPECS; this page describes each one. A Connected Lens works best with more than one device connected, so test it as several users.

Sync Kit for Connected Lenses

Sync Kit is a Lens Studio package that provides the core logic, APIs, and components for building Connected Lenses on SPECS. Sync Kit's Session Controller creates and manages the session for your Lens, so build your Lens with the Sync Kit APIs. To set up a project with Sync Kit, see the Sync Kit docs. For the lower-level API that Sync Kit is built on, see ConnectedLensModule in the API reference.

Check TypeScript compilation in the TypeScript Status panel

The Sync Kit package is written in TypeScript, which must compile before you can preview your Lens. To confirm that compilation is complete, open the TypeScript Status panel: Window > Utilities > TypeScript Status.

The Window menu open on Utilities, with TypeScript Status highlighted

Set the project's target platform to SPECS

Select File > Project Settings and set Target Platform to SPECS. A project created from a template for Snapchat targets Snapchat: Sync Kit still runs in the Preview panel, but the Lens builds for Snapchat until you change the target platform.

The Target Platform setting in Project Settings, set to SPECS

Set a fixed session ID in Lens Studio and on SPECS

Setting the same session ID in Lens Studio and on SPECS puts them in one session, which makes it faster to develop and test Connected Lenses. You no longer select a session by hand in Lens Studio, and you can test a Connected Lens with a single SPECS device: the device joins the same session as the Preview panels in Lens Studio.

The session ID must be a valid UUID (Universally Unique Identifier), such as 123e4567-e89b-12d3-a456-426614174000. To get a valid UUID, select Randomize in the Connected Lens Monitor: it generates one for you and avoids formatting errors.

Use the session bar of the Connected Lens Monitor to set the session ID for the Preview panels and for SPECS:

  1. Select Window > Utilities > Connected Lens Monitor.
  2. In the session bar, edit the Session ID field, or select Randomize. The Preview panels use the new session ID, which shows at the top of each Preview panel.
  3. Connect the SPECS device to Lens Studio; see Connect Lens Studio to SPECS.
  4. Select Apply next to SPECS. The device now uses the same session ID as the Preview panels.
The Connected Lens Monitor's session bar with its session ID controls outlined

To return the device to its own session ID, select Reset next to SPECS.

Apply the session ID to every SPECS device that should join the session: connect each device to Lens Studio in turn, and select Apply for each one.

To test with several versions of your Lens, or to decide which devices can share a session across releases, see Session Versioning.

Choose where to test a Connected Lens

You can test a Connected Lens in Lens Studio and on SPECS. Which is more helpful depends on what you're working on:

  • Lens Studio: each Preview panel joins a real Connected Lens session as its own user, so you can test syncing between users, get debug information, and iterate quickly. Colocation is simulated in Lens Studio and completes immediately, so test the colocation flow on SPECS.
  • On SPECS: you can run the Lens on several SPECS devices at once and test the data they send each other, including the colocation flow.

Test a Connected Lens with multiple Preview panels

You can test a Connected Lens in Lens Studio with several Preview panels. Each Preview panel is a different user in the same Connected Lens session.

  1. To add a Preview panel to your layout, select Window > General > Preview.

    The Window menu open on General, with Preview highlighted
  2. In the new Preview panel's toolbar, open the device menu (the glasses icon) and select SPECS 27. A new Preview panel doesn't copy the simulation settings of the others; see Preview Lenses for SPECS for the rest of the setup.

    The Preview panel's device menu with SPECS 27 selected

Each Preview panel shows the session ID it is connected to. Compare them to check that the Preview panels joined the same session.

Two Preview panels side by side, both running the Lens on SPECS 27 and showing the same session ID

To leave the session from a Preview panel, select Reset (the circular arrow) in the panel's toolbar. The Lens restarts at the Start Menu. To restart every Preview panel in a fresh session, select Randomize in the session bar of the Connected Lens Monitor instead: a Preview panel that you reset on its own rejoins the session while the others stay connected, so the session state doesn't fully reset.

The Preview panel toolbar with the Reset button circled in red, beside Pause Preview

Move around a Connected Lens in an Interactive Preview room

An Interactive Preview room lets you move around your Connected Lens in a Preview panel, for example to test what happens when a user gets closer to an object in your Lens. To use one, open the environment menu at the left of the Preview panel's toolbar and select a room under Interactive Previews, such as Sunlit Room.

The Preview panel's environment menu listing the Interactive Previews rooms, with Sunlit Room checked

Click the Preview panel to give it focus. Then press W, A, S, and D (or the arrow keys) to move, and E or Q to move up or down. Preview Lenses for SPECS lists every control.

Watch a session in the Connected Lens Monitor

The Connected Lens Monitor gives a real-time view of a Connected Lens session: its users, its messages, and its Realtime Stores.

Open the Connected Lens Monitor and start monitoring

  1. Select Window > Utilities > Connected Lens Monitor.

    The Window menu open on Utilities, with Connected Lens Monitor highlighted
  2. Join the session in every Preview panel, for example by selecting Multiplayer on the Sync Kit Start Menu.

  3. In the Connected Lens Monitor, select Start (its tooltip reads Start Monitoring). Start it after the Preview panels have joined the session: started earlier, the monitor finds nobody in the session and stops, and Lens Studio logs Start Monitor after previews have joined the connected session.

    The Connected Lens Monitor before monitoring starts, with the Start button and the session bar showing Not Monitored yet

While it monitors, the session bar shows the session ID, the User Count, and the Host. The Host can stay empty even in a session that works; check who owns each store in the Realtime Store view instead. To stop, select Stop.

To restart the Lens in every Preview panel without changing the session ID, select the refresh button in the monitor's session bar.

See each user's messages in the Connected Lens Monitor

In the Messages view, the Connected Lens Monitor lists the messages each Preview panel sent, in the order sent, with what each message contained, and how many messages each user sent in the last 5 seconds.

The Connected Lens Monitor while monitoring two Preview panels, with the session bar and each user's recent messages

Check Realtime Store values in the Connected Lens Monitor

In the Realtime Store view, the Connected Lens Monitor lists every Realtime Store in the session with its StoreID, Persistence Type, Owner and Current Value, followed by its history: each change to the store and who made it, starting with the user who created it. A store's values include its network ID (_network_id), so you can match a store, such as the one for a prefab that a Preview panel instantiated, to the object that uses it.

The Connected Lens Monitor showing the Realtime Stores of a session with two Preview panels, each store with its owner and current values

Test a Connected Lens on SPECS

To test your Connected Lens on SPECS devices, connect them to Lens Studio, send the Lens to each device, and then join the session on each device.

Connect SPECS to Lens Studio

  1. Connect each SPECS device to Lens Studio; see Connect Lens Studio to SPECS.
  2. For several SPECS devices, pair each device with the SPECS App, and connect every device to Wi-Fi.

Send a Connected Lens to several SPECS from one computer

Lens Studio connects to one SPECS at a time, so send the Lens to each device in turn:

  1. Send the Lens to the connected SPECS device.
  2. In the menu beside Preview, select Switch to Another SPECS, then send the Lens again.
  3. Repeat for each device.

For more details, see Connect to another SPECS and Send a Lens to SPECS.

If one SPECS device doesn't see the session started on another, try this order:

  1. Send the Lens to the first SPECS device, switch to the second, and send the Lens to it.
  2. Start the Lens on the second device, start a new session, and complete colocation.
  3. On the first device, wait for the session to show in Active Nearby, or launch the Lens from Drafts and join the session.

Send a Connected Lens to several SPECS from several computers

  1. In each computer's Lens Studio, set the same Session ID in the session bar of the Connected Lens Monitor before you send the Lens to SPECS; see Set a fixed session ID in Lens Studio and on SPECS. Lens Studio randomizes the session ID when it opens the project, so set it again each time you open the project.
  2. Send the Lens to each SPECS device from its own computer's Lens Studio.

Test a Connected Lens with SPECS and Lens Studio together

When a session ID is set and the Lens doesn't use a Connected Custom Location, join the session from SPECS first. Lens Studio can't build a map that SPECS can colocate against, so the SPECS device must complete colocation first. Once the SPECS device has colocated and joined the session, the Preview panels in Lens Studio can join with the same session ID for synchronized interactions.

Test a Connected Lens with several SPECS devices

  • To test with several people, start and join a session as described in Using Connected Lenses.
  • To test alone with several SPECS devices, turn on Colocate for Solo Development in the SPECS App's Developer Settings. The devices then colocate through mapping only, so you don't need to look at another person.

Keep data after a session ends

When building for SPECS, the data a Connected Lens shares through Sync Kit lasts only while at least one user is in the session. Sync Kit keeps each Sync Entity's storage properties in a Realtime Store, and the Persist persistence option for Realtime Stores is deprecated.

Keep data that must survive after everyone leaves in a Snap Cloud database. Use each one for a different job:

  • Sync Kit: real-time state that all users share during the session, such as the position of an object. Sync Transform syncs a position for you.
  • Snap Cloud: state that a user comes back to, such as a garden that the user tends every day. Load the state from Snap Cloud when the Lens starts, and apply it to the session's shared data.

To move persisted properties to Snap Cloud, follow the steps in Sync Entity. Databases in the Snap Cloud docs covers how to read and write the data.

APIs that are restricted in Connected Lenses

When you build and use Connected Lenses, some APIs are restricted to protect users' privacy. These APIs are disabled: