Setup
Getter and Setter Methods
Set Live Data
The Live State Sync feature allows you to set and update shared data that syncs in real-time across all connected clients.
Params
liveStateDataId
(string
, required): A unique string ID to identify the dataliveStateData
(any serializable type
, required): The data to sync (objects, arrays, strings, numbers)setLiveStateDataConfig
(object
, optional): Configuration objectmerge
(boolean
): Whether to merge the data with existing data (default:false
)
Get Live Data
Get live state data by providing the unique ID used when setting the data.
Params
liveStateDataId
(string
, required) - A unique string ID to identify the data to retrieveliveStateDataConfig
(object
, optional) - Configuration object for controlling data retrieval behaviorlistenToNewChangesOnly
(boolean
, optional) - Whether to only receive new changes from when the client subscribed (default:false
)
If using API, you can unsubscribe from the subscription after you are done:
If using API, you can unsubscribe from the subscription after you are done:
To unsubscribe from the subscription:
Alternative: useLiveState()
The useLiveState()
hook provides a familiar React’s useState()
like API while automatically syncing state changes across all connected clients in real-time.
The hook accepts the following parameters:
id
(string, required): Unique identifier for syncing this state across clientsinitialValue
(any, required): Initial state valueoptions
(object, optional): Configuration object with the following properties:syncDuration
(number, optional): Debounce delay in milliseconds before syncing. Defaults to 50ms.resetLiveState
(boolean, optional): Whether to reset server state when the hook initializes. Defaults to false.listenToNewChangesOnly
(boolean, optional): When true, only receives changes that occur after subscribing and discards historical changes. Defaults to false.
Returns
[value, setValue, connectionState]
value
: Current value of the data you setsetValue
: Function to update the dataconnectionState
: Current server connection status
Server Connection State
The server connection state indicates the current status of the connection to Velt’s servers. The possible states are:
If using API, you can unsubscribe from the subscription after you are done:
If using API, you can unsubscribe from the subscription after you are done:
To unsubscribe from the subscription:
Best Practices
- Keep your state data structures simple and flat when possible
- Use meaningful IDs that reflect the purpose of the data
- If using APIs, clean up subscriptions when components unmount
- Consider network latency when setting
syncDuration
- Sync only what you need, not the entire state
- Use
listenToNewChangesOnly
when appropriate