Lifecycle
- Snapchat: not supported
- SPECS: partially supported
- Camera Kit Web: not supported
- Camera Kit Mobile: not supported
- SnapchatNot supported
- SPECSPartially supported
- Camera Kit WebNot supported
- Camera Kit MobileNot supported
A Connected Lens is able to receive and send information to other Snapchatters by being connected to a "session." It is important to keep in mind that users must voluntarily join a session before the connected experience work.
A Connected Lens on SPECS receives and sends information to the other users wearing SPECS in the same session. Users choose to join a session before the connected experience starts.
This guide provides some information around what you can expect in a Connected Lens experience.
In almost all cases, you will want to start your project from the Connected Lens template as the template provides helpers and UI to deal with sessions and inviting others to your experience.
Lens Open (without Invite)
When the user first swipes into a Lens, the Lens acts as any other Lens and is not connected. In this state, usually you would display a splash screen to introduce the Snapchatter to the experience, or when possible, create an interactive preview ("demo mode") for the experience.
When a ConnectedLensModule is in the Lens, a call to action button will be shown at the bottom of the screen. When the user presses the Call to Action button, they will be brought into a Connected Lens state.
Connected Lens State
The next state in the experience is actually being inside the Connected Lens State.
A Snapchatter will enter this state in one of two ways:
- A Snapchatter will enter this state either by pressing the Connected Lens Call to Action
- A Snapchatter entered this Lens via an invitation (see next section)
The Snapchatter will know they are in this state as they will enter a full screen experience where:
- They will not have access to any camera mode, except to change between front and rear camera.
- Instead of a carousel of Lenses, you will have an Action bar (similar to what you see in Snap Games). The Action Bar will allow the user to see who else is in the session.
More importantly, the “ConnectedLensEnteredEvent” event will be emitted. After this event has occurred, you may call the following APIs:
createSession:create a session and return it via callbacksshareSession:shares a session by allowing the user to share the session via chat (remote), or provides a callback with a texture for others to scan (colocated)
In remote Connected Lenses, your friends can invite their friends (who are not your friends) to join the session. In colocated, however, only the creator of the session can invite, and all participants must be a friend of the creator.
Invitation Flow
In most cases, this state is taken care by the Invitation Flow provided by the Connected Lens Template. This flow allows the Snapchatter to choose what kind of Connected Lens experience they would like to have:
- Solo mode
- Colocated Mode
- Remote Mode
The invitation flow will take care of leveraging the createSession and shareSession API, where you as the Lens developer will take care of the actual experience behind each mode.
Take a look at the Template guide to learn how you can hook your experience into the Invitation Flow provided by the template.
Colocated Invitation Flow
In this mode, one person would follow the prompt to scan the room. After scanning for a certain amount of time, they would be provided with a Snapcode that others can join. When others scan the Snapcode, they will be brought into the same colocated session
Remote Invitation Flow
In this mode, one person would be prompted to invited friends to join them through chat. Others are then free to accept the invitation to join the session.
When building for SPECS, start your project from Sync Kit: the package creates and manages the session and provides the joining flow.
How a Connected Lens session starts on SPECS
When building for SPECS, Sync Kit's Session Controller creates the session for your Lens: it calls createSession on the Connected Lens Module itself. When a user enters the Lens, the Sync Kit Start Menu offers Multiplayer and Singleplayer. Multiplayer takes the user into the colocated joining flow; Singleplayer puts them directly into the Lens. Start Menu and Player Mode covers the menu, and Using Connected Lenses shows how users start and join a session on SPECS.
Sync Kit then sets up the session in a fixed order. Lifecycle in the Sync Kit docs lists the steps and when the Session Controller, each SyncEntity, and each Instantiator are ready to use.
Being in a Session
Once in a session, you will have additional APIs to manage your experience.
Once in a session, you will have additional APIs to manage your experience. The session is a MultiplayerSession, and its callbacks are set on the ConnectedLensSessionOptions the session was created with.
In a session, you may:
- Get information about whether the session is colocated (user was invited via Snapcode), or remote (user was invited via chat)
- Get information about whether the current user created the session, or they are entering a session from an invite.
getServerTimestamp: Returns the server timestamp (in milliseconds) that can be used for experience logicsendMessage: Sends a message to everyone in sessionsendMessageWithTimeOut: Sends a message to everyone in session with timeout
- Get information about whether the current user created the session, or they are entering a session from an invite:
onSessionCreatedreceives aConnectedLensSessionOptions.SessionCreationTypeofNew,MultiplayerReceiver, orNewSoloMode. getServerTimestamp: Returns the server timestamp (in milliseconds) that can be used for experience logicsendMessage: Sends a message to everyone in sessionsendMessageWithTimeout: Sends a message to everyone in session with a timeout in milliseconds, after which the message can be dropped from the outgoing queue
You can get notified:
onSessionCreated: When a session is createdonConnected: When a real time connection is established. At this point server calls can be madeonDisconnected: When a real time connection is lostonUserJoinedSession: When a new participant joins the session. Existing participants will get info on the new participant, while the new participant receives info on existing participants.onUserLeftSession: When a new user leavesonMessageReceived: When someone in the session broadcasts a messageonError: When some error has occurred in the session. Here are some useful error codes:"LensStudioConnectionError"- Connecting to a session is not support from within Lens Studio. It's useful to ignore this error when developing inside Lens Studio, but be aware that some features won't work."MatchJoinRestrictedToFriendOnly"- Joining a colocated session (through Snapcode) is only supported when the host is a friend of the joining user. If this error occurs, you should message to the user that they must be friends before connecting.
onSessionCreated: When a session is createdonConnected: When a real time connection is established. At this point server calls can be madeonDisconnected: When a real time connection is lostonUserJoinedSession: When a new participant joins the session. Existing participants will get info on the new participant, while the new participant receives info on existing participants.onUserLeftSession: When a user leavesonMessageReceived: When someone in the session broadcasts a messageonError: When some error has occurred in the session.
User Info
In order to facilitate a connected experience, you may get some basic information about participants of a Connected Lens session.
When a user joins a session, you can get their:
userId: Unique identifier for each user per LensdisplayName: Display name of the user. Note that this is an optional field in a Snapchat account, so you may get an empty string in return.
During a session you may also get:
getLocalUserId: Get the UserId of the current user
getLocalUserId: Get the UserId of the current user
When building for SPECS, Sync Kit gives your scripts this information as UserInfo; User Information in the Sync Kit docs describes each field.
Shared Persistent Storage
The MultiplayerSession storage methods (getStoredValue, setStoredValue, listStoredValues, and deleteStoredValue) are deprecated. Use Realtime Stores instead, created with createRealtimeStore; Sharing Data Between Participants describes them.
In addition to making your experience work in real time, you can make it asynchronous by storing data in a session to a shared persistent storage. This allows you to build experiences that users can come back to.
You may store next data types:
string, number, vec2, vec3, vec4, quat, mat2, mat3, mat4
string, number, boolean, vec2, vec3, vec4, quat, mat2, mat3, mat4
For each value, you may have the value be scoped to the:
- User: visible/writable only by the current user
- Session: visible/writable by any user in the session
You can interact with the Shared Persistent Storage by:
- Storing a value
- Getting a value
- Listing stored values (based on scope)
- Delete a stored value (based on scope)
Since a session is tied to other mechanisms, so will the Lens ability to access the shared persistent storage. That is:
- A remote session can be rejoined as long as the chat conversation exists (for example, its retention is based on the conversation’s settings)
- A colocated session can be rejoined as long as you have access to the Snapcode that was generated to enter the session.
If you store data from your "solo mode" in the User scope, you would be able to read that even once the user has joined a session. You can even use the local Persistent Storage and pass that information to the session storage. This means it’s possible to create a trial experience, or individual experience that would feed into the full Connected Lens experience.
User scope data is available across different sessions of the same Lens. This means that you can store information about the Snapchatter's overall progress, and progress within a chat group or session.
When building for SPECS, store data that must survive after a session ends in a Snap Cloud database: the Persist option for Sync Kit's Realtime Stores is deprecated. Sync Entity describes the move to Snap Cloud.
Next Steps
- Development Workflow: test a Connected Lens in Lens Studio and on devices.