Lifecycle
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.
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.
There are two ways that a Snapchatter will enter this state:
- 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.
Being in a Session
Once in a session, you will have additional APIs to manage your experience.
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
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.
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
Shared Persistent Storage
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
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 (e.g. it’s 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.