Persistent Storage
Overview
By default, script variables retain their value only while the Lens is active. When a user closes and reopens a Lens, all script variables are reset. The Persistent Storage system enables you to create Lenses that can selectively read and write data between Lens sessions. This is perfect for keeping track of a high score in a game, for example.
In this guide, we'll write a simple script that increments a score every time the user opens their mouth, and then saves that count.
Please visit the High Score Template Guide for a more detailed example
Writing Data To Persistent Storage
First, create a variable that refers to the Persistent Storage system's data store.
var store = global.persistentStorageSystem.store;
Next, create a key which you'll use to read and write the score value. In this case, we'll name our key totalScore
.
var scoreKey = 'totalScore';
Using this key, we can create an integer variable in the Persistent Storage system's data store.
Since we haven’t yet placed any data in the store, the first time we retrieve totalScore
its value will be the default integer value of 0.
var currentGameScore = store.getInt(scoreKey);
print('Loaded score: ' + currentGameScore);
For a full list of supported data types, please visit the GeneralDataStore API Reference.
Next, we'll write a function that increments the score and updates our variable in the Persistent Storage store.
function incrementScore() {
currentGameScore += 1;
store.putInt(scoreKey, currentGameScore);
print('Current score: ' + currentGameScore);
}
And bind the new function incrementScore
to the MouthOpenedEvent
:
script.createEvent('MouthOpenedEvent').bind(incrementScore);
Now, each time the user opens their mouth, they will increment the integer value stored at the persistent key totalScore
.
Once a value is stored in Persistent Storage, it stays there even after the user closes the Lens. In Lens Studio, a notification appears in the Preview panel to remind you that there is data in Persistent Storage.
Snapchat will clear the Lens' persistent storage 60 days after the user does not touch the Lens.
Printing and Clearing Keys
In Lens Studio, you can print and clear the Persistent Storage system's keys in the Preview Panel.
Printing Keys
You can print the keys and values you have stored in Persistent Storage in the Preview Panel
by selecting ... > Print Persistent Storage
The result will be printed in the Logger Panel
.
Clearing Keys
You can clear Lens Studio's Persistent Storage in the Preview Panel
by selecting ... > Clear Persistent Storage
You can clear Persistent Storage in Snapchat by going to Settings > Clear Lens Data
Storage Capacity
Persistent Storage has a limited capacity. Once it’s full, no new data keys can be added until it's cleared.
onStoreFull
is a callback function called every time Persistent Storage is full. We can call clear
each time this happens to add new values.
store.onStoreFull = function () {
store.clear();
print('Storage cleared');
};
The Final Script
Below you'll find the completed script from this guide:
// Create key for the score variable
var store = global.persistentStorageSystem.store;
var scoreKey = 'totalScore';
// Retrieve the score from persistent storage
var currentGameScore = store.getInt(scoreKey);
// Print the score
print('Loaded score: ' + currentGameScore);
// Function that increments the score
function incrementScore() {
// Increment the score by 1
currentGameScore += 1;
// Store the current score in persistent storage
store.putInt(scoreKey, currentGameScore);
// Print the current score
print('Current score: ' + currentGameScore);
}
// Bind the incrementScore function to the "Mouth Opened" event
script.createEvent('MouthOpenedEvent').bind(incrementScore);
// If persistent storage is full, clear it
store.onStoreFull = function () {
store.clear();
print('Storage cleared');
};