Stored values
Stored values allow you to save data between user sessions. Unlike regular variables, stored values are saved on the device and remain available after the app is restarted.
Note
On Web, stored values work only if external storage is passed to the render function in the store parameter, see Parameters of the render function. Without it, the set_stored_value action fails with an error.
Stored value scopes
Stored values support different scopes:
global— values are available in all app cardscard— values are available only in the current card
If the scope is not specified, global is used.
set_stored_value action
To save values, use the typed set_stored_value action:
{
"log_id": "save_theme",
"typed": {
"type": "set_stored_value",
"name": "user_theme",
"value": {
"type": "string",
"value": "dark"
},
"lifetime": 86400,
"scope": "global"
}
}
Action parameters:
name— name of the stored value. Required.value— typed value: an object with thetype(string,integer,number,boolean,color,url,array,dict) andvaluefields. Required.lifetime— value lifetime in seconds. Required.scope— scope:globalorcard.
The same action in the url format:
div-action://set_stored_value?name=<name>&value=<value>&type=<type>&lifetime=<lifetime_in_sec>&scope=<global|card>
|
Parameter |
Description |
|
|
Name of the stored value. Required parameter. |
|
|
The value to be saved. Required parameter. |
|
|
Value type: |
|
|
Lifetime of the value in seconds. After this time, the value is considered expired. Required parameter. |
|
|
Scope: |
Functions for reading stored values
To read stored values, use the getStored<Type>Value functions:
getStoredStringValue(name, fallback)— reads a string value;fallbackis returned when the value is not found;getStoredStringValue(name, scope, fallback)— reads from the specified scope ('global'or'card');getStoredArrayValue(name),getStoredArrayValue(name, scope),getStoredDictValue(name),getStoredDictValue(name, scope)— read an array or a dictionary. These functions have nofallback: if the value is not found, the expression evaluation fails.
Similar functions exist for the integer, number, boolean, color, and url types.
For the full list of functions with signatures, see Built-in functions.
Stored values usage example
{
"log_id": "stored_values_example",
"variables": [
{
"name": "theme",
"type": "string",
"value": "@{getStoredStringValue('user_theme', 'light')}"
}
],
"states": [
{
"state_id": 0,
"div": {
"type": "container",
"items": [
{
"type": "text",
"text": "Current theme: @{theme}",
"actions": [
{
"log_id": "switch_theme",
"typed": {
"type": "set_stored_value",
"name": "user_theme",
"value": {
"type": "string",
"value": "@{theme == 'light' ? 'dark' : 'light'}"
},
"lifetime": 2592000,
"scope": "global"
}
}
]
}
]
}
}
]
}
Example with different scopes
{
"log_id": "stored_values_scopes",
"variables": [
{
"name": "global_setting",
"type": "string",
"value": "@{getStoredStringValue('global_setting', 'global', 'default_value')}"
},
{
"name": "card_setting",
"type": "string",
"value": "@{getStoredStringValue('card_setting', 'card', 'card_default')}"
}
],
"states": [
{
"state_id": 0,
"div": {
"type": "container",
"items": [
{
"type": "text",
"text": "Global setting: @{global_setting}",
"actions": [
{
"log_id": "set_global",
"typed": {
"type": "set_stored_value",
"name": "global_setting",
"value": {
"type": "string",
"value": "new_global_value"
},
"lifetime": 2592000,
"scope": "global"
}
}
]
},
{
"type": "text",
"text": "Card setting: @{card_setting}",
"actions": [
{
"log_id": "set_card",
"typed": {
"type": "set_stored_value",
"name": "card_setting",
"value": {
"type": "string",
"value": "new_card_value"
},
"lifetime": 2592000,
"scope": "card"
}
}
]
}
]
}
}
]
}
Learn more
You can discuss topics of interest in the DivKit user community in Telegram: https://t.me/divkit_community_en.