Lifecycle
installed, updated, uninstalled and run, the initialize convention, pausing, and what happens on code updates.
The hub calls four optional top-level functions at fixed moments. Define the ones you need by these exact names.
| Hook | When | Typical body |
|---|---|---|
installed() | once, right after the installer saves the preferences for the first time | initialize() |
updated() | every time the preferences are saved again | unsubscribe(); unschedule(); initialize(); |
uninstalled() | when the instance is removed | usually nothing; the hub drops subscriptions, timers and state |
run() | when a person presses Run on the instance | whatever "run it now" means for the app |
function installed() {
console.log('installed');
initialize();
}
function updated() {
unsubscribe(); // every subscription of this instance
unschedule(); // every schedule and pending timer
initialize();
}
function initialize() {
subscribe(door, { to: 'unlocked' }, onUnlock);
runDaily('23:00', lockUp);
}The initialize convention
There is no built-in initialize hook; it is a convention. Both installed and updated end up
needing the same subscriptions and schedules, so put them in one function and call it from both.
Because updated runs on every settings change, tear down first or a changed device picker leaves
the old subscription firing into the new code.
run
run is a one-shot manual trigger: the Run button in the app and, for apps that opt into one,
a companion input_button entity press. It does not touch subscriptions or the running state; it just
calls your function. Use it for "test it now" or for apps whose whole purpose is an action a person
starts (a scene-like routine).
Paused instances
A person (or another smart app, via pauseSmartApp) can pause an instance. While paused the hub
skips every handler the instance would run; subscriptions and schedules stay registered and resume
firing when the instance is resumed. Pausing a parent pauses its children. A pause with a duration
auto-resumes, but that timer is not durable across a hub reboot.
Errors
A handler that throws does not stop the instance. The hub logs the error to the instance's log and increments its exception count, which the app shows on the instance. Repeated failures are a signal to look at, not a circuit breaker.
Code updates
Updating a definition's source (in the admin console) stores a new version number for it; the hub
assigns these integers itself. Existing instances pick up the new code on their next handler run,
because every run evaluates the current source. Their settings and state are untouched; if the new
code expects different inputs, instances need their preferences saved again so updated runs.