Хранение состояния

  1. Первоначальная настройка
  2. Хранение состояния сессии
  3. Хранение состояния между сессиями
  4. Хранение состояния для экземпляра приложения
  5. Полезные ссылки
Внимание. Возможность работает в тестовом режиме и активно развивается, поэтому протокол ее использования может меняться.

API Яндекс.Диалогов позволяет сохранять данные внутри сессии навыка, а если пользователь авторизован на поверхности, на которой работает навык, то и между сессиями.

Первоначальная настройка

Чтобы подключить возможность сохранения состояния:

  1. Откройте страницу настроек навыка в консоли разработчика.
  2. Найдите поле Хранилище в блоке Основные настройки.
  3. Отметьте опцию Использовать хранилище данных в навыке.

Хранение состояния сессии

Чтобы сохранить данные внутри сессии, навык должен отправить свойство session_state в ответе. Записанное значение придёт в следующем запросе в навык. Данные хранятся до конца жизни сессии. Сессия завершается, если:

  • когда пользователь запрашивает выход из навыка;
  • когда навык явно завершает работу ("end_session": true);
  • когда от пользователя долго не поступает команд (таймаут зависит от поверхности, минимум несколько минут).

Максимальный совокупный размер JSON-объекта session_state — 1 КБ:

{
  "response": {
    "text": "Здравствуйте! Это мы, хороводоведы.",
    "tts": "Здравствуйте! Это мы, хоров+одо в+еды.",
    "end_session": false
  },
  "session_state": {
      "value": 10
  },
  "version": "1.0"
}
Важно. Состояние сессии перестанет храниться, если в ответе навыка не вернуть свойство session_state. Поэтому если для конкретного запроса состояние не меняется, но его нужно продолжать хранить, навыку следует вернуть тот же объект session_state, что пришел в запросе.

Пример запроса с сохраненным состоянием:

{
  "meta": {
    "locale": "ru-RU",
    "timezone": "Europe/Moscow",
    "client_id": "ru.yandex.searchplugin/5.80 (Samsung Galaxy; Android 4.4)",
    "interfaces": {
      "screen": { }
    }
  },
  "request": {
    "command": "привет",
    "original_utterance": "привет",
    "type": "SimpleUtterance",
    "markup": {
      "dangerous_context": true
    },
    "payload": {},
    "nlu": {
      "tokens": [
         "привет"
      ],
      "entities": [
      ]
    }
  },
  "session": {
    "new": true,
    "message_id": 4,
    "session_id": "2eac4854-fce721f3-b845abba-20d60",
    "skill_id": "3ad36498-f5rd-4079-a14b-788652932056",
    "user_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC",
    "application": {
      "application_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC"
    },
  },
  "state": {
    "session": {
      "value": 10
    }
  },
  "version": "1.0"
}

Хранение состояния между сессиями

Примечание. Хранить состояние навыка для определенного пользователя можно только для пользователей, которые вошли с Яндекс ID.

Чтобы сохранить данные о пользователе, навык должен отправить в ответе свойство user_state_update. Максимальный совокупный размер JSON-объекта — 1 КБ:

{
  "response": {
    "text": "Здравствуйте! Это мы, хороводоведы.",
    "tts": "Здравствуйте! Это мы, хоров+одо в+еды.",
    "end_session": false
  },
  "session": {
    "session_id": "2eac4854-fce721f3-b845abba-20d60",
    "message_id": 4,
    "user_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC",
    "application": {
      "application_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC"
    },
  },
  "user_state_update": {
      "value": 42
  },
  "version": "1.0"
}

Чтобы удалить поле, ранее записанное в состояние пользователя, навык должен отправить это поле со значением null.

Сохранённое значение придёт в следующем запросе в навык:

{
  "meta": {
    "locale": "ru-RU",
    "timezone": "Europe/Moscow",
    "client_id": "ru.yandex.searchplugin/5.80 (Samsung Galaxy; Android 4.4)",
    "interfaces": {
      "screen": { }
    }
  },
  "request": {
    "command": "привет",
    "original_utterance": "привет",
    "type": "SimpleUtterance",
    "markup": {
      "dangerous_context": true
    },
    "payload": {},
    "nlu": {
      "tokens": [
         "привет"
      ],
      "entities": [
      ]
    }
  },
  "session": {
    "new": true,
    "message_id": 4,
    "session_id": "2eac4854-fce721f3-b845abba-20d60",
    "skill_id": "3ad36498-f5rd-4079-a14b-788652932056",
    "user_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC",
    "application": {
      "application_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC"
    },
    "user": {
      "user_id": "8D7196B4A8AA15CFF3B7B3046738C03F234A7E638FFE33B23F2350BBD940B644"
    }
  },
  "state": {
    "user": {
      "value": 42
    }
  },
  "version": "1.0"
}

Хранение состояния для экземпляра приложения

Примечание. Экземпляр приложения — это конкретное приложение, например Браузер, приложение Яндекс, Навигатор, или устройство. Разрез хранения равносилен session.application.application_id для навыка.

Хранение состояния для экземпляра приложения позволяет сохранить контекст взаимодействия с пользователем для конкретной поверхности, не распространяя его на другие поверхности пользователя.

Если конкретная поверхность Алисы не поддерживает авторизацию или пользователь не авторизован на поверхности, хранение в разрезе экземпляра приложения — единственный способ сохранить контекст между сессиями.

Чтобы сохранить состояние навыка для определенного экземпляра приложения, навык должен отправить свойство application_state в ответе:

{
  "response": {
    "text": "Здравствуйте! Это мы, хороводоведы.",
    "tts": "Здравствуйте! Это мы, хоров+одо в+еды.",
    "end_session": false
  },
  "application_state": {
      "value": 37
  },
  "version": "1.0"
}

Сохраненное состояние придет в следующем запросе в навык:

{
  "meta": {
    "locale": "ru-RU",
    "timezone": "Europe/Moscow",
    "client_id": "ru.yandex.searchplugin/5.80 (Samsung Galaxy; Android 4.4)",
    "interfaces": {
      "screen": { }
    }
  },
  "request": {
    "command": "привет",
    "original_utterance": "привет",
    "type": "SimpleUtterance",
    "markup": {
      "dangerous_context": true
    },
    "payload": {},
    "nlu": {
      "tokens": [
         "привет"
      ],
      "entities": [
      ]
    }
  },
  "session": {
    "new": true,
    "message_id": 4,
    "session_id": "2eac4854-fce721f3-b845abba-20d60",
    "skill_id": "3ad36498-f5rd-4079-a14b-788652932056",
    "user_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC",
    "application": {
      "application_id": "AC9WC3DF6FCE052E45A4566A48E6B7193774B84814CE49A922E163B8B29881DC"
    },
    "user": {
      "user_id": "8D7196B4A8AA15CFF3B7B3046738C03F234A7E638FFE33B23F2350BBD940B644"
    }
  },
  "state": {
    "application": {
      "value": 37
    }
  },
  "version": "1.0"
}
Важно. Состояние для экземпляра приложения продолжает храниться, если в ответе навыка не вернуть application_state. Поэтому если для конкретного запроса состояние навыка для экземпляра приложения не изменяется, то его можно не присылать в ответе или отправить это поле со значением null.

Чтобы очистить ранее сохраненное состояние приложения, навык может отправить это поле со значением {} — пустым словарем.