Discussed briefly today at the TOK F2F. We weren't able to quickly spot a restriction on access to this API from the top-level frame (and, perhaps, delegation via Feature Policy or sandbox attribute). Is that planned?

Looks like it may have a potential to profile users, and perhaps potential to misuses with conjunction with other APIs. Has this been been deployed already by any chance (chrome canary?)?

Status here: https://www.chromestatus.com/feature/4590256452009984

@samuelgoto, @inexorabletash do you folks have any feedback on the top-level frame restriction noted above?

• Should this be event based instead of observer based? Check our design principles https://w3ctag.github.io/design-principles/#events-vs-observers
• Should events be delivered to tabs in the background - I think they should, as my Hangouts and Slack tabs are seldom in foreground and people still want to know whether I am idle or not
• Are events restricted to top-frame and https? - they should be
• To reduce multiple sites identifying me as the same person due to the time I idle, it might be possible to introduce some fuzziness between reporting to the various observers
• For IM, users usually want to know if a user is available to know whether they can expect a response or not - but often people in meetings/busy cannot respond - maybe we need a API for sites to report business and these should be tied together
• how important is the configuration? I can easily start a timer myself for say 5 minutes idling before I update my UI, and the event is only send infrequently

@lknik any more feedback

@samuelgoto, @inexorabletash do you folks have any feedback on the top-level frame restriction noted above?

It sounds like a reasonable restriction to me. @inexorabletash any concerns?

sgtm!

Has this been been deployed already by any chance (chrome canary?)?

The feature is still under development and an early version can be accessed in canaries through runtime flags (so no, not available by default).

sgtm!

Ok, I'll update the explainer to make this easier to find and report back on this thread here.

@slightlyoff any other feedback that you think is worth paying attention to?

Ok, I'll update the explainer to make this easier to find and report back on this thread here.

Done.

Great feedback @kenchris ! Let me try to address that!

Should this be event based instead of observer based? Check our design principles https://w3ctag.github.io/design-principles/#events-vs-observers

Great question and thanks for pointing out that doc!! Super helpful!!! The following seems to be the general guidance:

In general, start your design process using an EventTarget and only move to Observers if and when events can’t be made to work well.

In the specific case of idle detection, I run into the following:

Instances observe specific targets, using the observe() and unobserve() methods. The callback provided in the constructor is invoked when something interesting happens to those targets.

In that, in the EventTarget formulation, navigator.idle.query({threshold: 60}) takes a configuration object with a threshold. Does that cross a line to tip us towards observers? Or would are there more precedent for configurations to be passed as the creation of EventTargets?

Should events be delivered to tabs in the background - I think they should, as my Hangouts and Slack tabs are seldom in foreground and people still want to know whether I am idle or not

Yes, events are delivered to tabs in the background. That's more or less the point of the API, because when your tab is in the foreground, idle detection can be polyfillable (with detecting gestures and the Page Visibility API).

Are events restricted to top-frame and https? - they should be

Yes.

To reduce multiple sites identifying me as the same person due to the time I idle, it might be possible to > introduce some fuzziness between reporting to the various observers

Ah, good point. That came up on a security/privacy review. Let me digest this a bit more and circle back.

For IM, users usually want to know if a user is available to know whether they can expect a response or not - but often people in meetings/busy cannot respond - maybe we need a API for sites to report business and these should be tied together

Hummmm ... can you walk me through how this would work?

how important is the configuration? I can easily start a timer myself for say 5 minutes idling before I update my UI, and the event is only send infrequently

The only configuration available is a threshold you pass, in seconds, as the criteria for idleness. Without a threshold, you'd have to poll. Does that make sense?

Or would are there more precedent for configurations to be passed as the creation of EventTargets?

There is precedent. Perhaps the most relevant is the generic sensors API: https://w3c.github.io/sensors/

Which also brings up a good point that it seems you could model this with a constructor instead of a navigator.idle() method which returns a non-constructible object.

I might suggest following the generic sensor API as much as possible in naming and usage style. Although probably not by actually subclassing the Sensor class; it seems like you want a subset of that functionality.

Maybe something like (Maybe making threshold not optional to avoid polling?)

[SecureContext, Exposed=Window, Constructor(IdleDetectorOptions options)
interface IdleDetector : EventTarget {
  readonly attribute IdleState state;
  readonly attribute DOMHighResTimeStamp? timestamp;
  void start();
  void stop();
  attribute EventHandler onreading;
};

dictionary IdleDetectorOptions {
  double threshold;
};

enum IdleState {
  "active",
  "idle",
  "locked" 
}

From your explainer it sounds like "locked" means that screen was turned off, and not a locked screen like WakeLock - those need to be aligned.

If you really need a one-shot you can add one like the geolocation sensor: https://www.w3.org/TR/geolocation-sensor/#idl-index

[SecureContext, Exposed=Window, Constructor(IdleDetectorOptions options)
interface IdleDetector : EventTarget {
  static Promise<IdleReading> read(optional ReadOptions readOptions);
  readonly attribute DOMHighResTimeStamp? timestamp;
  readonly attribute IdleState state;
  void start();
  void stop();
  attribute EventHandler onreading;
};

dictionary IdleDetectorOptions {
  double threshold;
};

dictionary ReadOptions : IdleDetectorOptions {
  AbortSignal? signal;
};

enum IdleState {
  "active",
  "idle",
  "locked" 
}

ictionary IdleReading {
  DOMHighResTimeStamp? timestamp;
  readonly attribute IdleState state;
}

Examples:

const reading = await IdleDetector.read({ threshold: 2 * 60 });

const detector = new IdleDetector({ threshold: 2 * 60 });
detector.onreading = () => {
  console.log(detector.timestamp, detector.state);
}
detector.start();

From @samuelgoto's Explainer:

locked - the system has an active screen lock preventing interaction with the user agent

As @kenchris said above, this should indeed be aligned with Wake Lock terms. A type "screen" Wake Lock might still mean the user is idle (or rather: in DND mode, e.g., when presenting or watching a movie). If we think of idle detection use cases, a chat app should probably report "idle" if a screen lock is active (even if it's not the right word) in that case.

Ha, I love IdleDetector @kenchris and thanks for pointing out the sensors API for precedence/inspiration @domenic !

Looking at the Accelerometer for inspiration, here is what it looks like:

let accelerometer = new Accelerometer({ frequency: 10 });
accelerometer.addEventListener('error', event => {
    // Handle runtime errors.
});
accelerometer.addEventListener('reading', () => reloadOnShake(accelerometer));
accelerometer.start();

@kenchris curious: is there a specific reason why you chose a onreading callback EventHandler as opposed to using the addEventListener() method of the subclassing of EventTarget? For example, would something along these lines be more consistent with the Accelerometer design:

let idleDetector = new IdleDetector({ threshold: 60 });
idleDetector.addEventListener('reading', () => reloadOnShake(idleDetector));
idleDetector.start();

Couple of other things that came up: feature detection and permissions/errors/feature policies.

// feature detection
if (window.IdleDetector) {
  /// idle detection available
}

And we thought that making start() return a Promise would allow us to return all sorts of initialization errors. E.g.:

try {
  let idleDetector = new IdleDetector({ threshold: 60 });
  idleDetector.addEventListener('reading', () => reloadOnShake(idleDetector));
  await idleDetector.start();
} catch (e) {
  // deal with permission errors, feature policy errors, etc
}

WDYT?

Putting aside this, I also really like the design for one-shot queries with a static async method. This works really well to me:

const reading = await IdleDetector.read({ threshold: 2 * 60 });

@tomayac wrt

If we think of idle detection use cases, a chat app should probably report "idle" if a screen lock is active (even if it's not the right word) in that case.

I think that's the original intent/model and the implementation.

The state is reported in two orthogonal/different dimensions, the user state (idle/active) and the screen state (locked/unlocked).

We debated a bit whether it would be useful to decouple in different APIs the user state from the screen state, and arrived at bundling but weekly held.

Does that make sense and address your point?

@kenchris curious: is there a specific reason why you chose a onreading callback EventHandler as opposed to using the addEventListener() method of the subclassing of EventTarget?

Both are supported :-) in addition to the onreading property there is a "reading" event. That is how EventTarget usually works.

And we thought that making start() return a Promise would allow us to return all sorts of initialization errors. E.g.:

That was considered for Sensors as well. I don't remember the discussion but the conclusion was that it was better not to (there is already the error event, as errors can happen at any time). @tobie @anssiko do you remember?

I believe it is better to not return a promise, just for the sake of consistency across the platform

Yes. We dropped those promises as mentioned here: https://github.com/w3c/sensors/issues/104#issuecomment-248316955.

At best, you had to duplicate your event handlers and then filter out error messages between the promise and the event handler.

At worst it pushed developers to rely only on rejected promises as an error handling strategy and miss a number of error classes.

Related: https://github.com/w3c/sensors/issues/93

(For more historical context, this was discussed at famous Lisbon F2F https://www.w3.org/2016/09/20-dap-minutes.html, but I think the issue pointed out by @tobie is the best summary. You know F2F minutes.)

Pink @kenchris - can we discuss next week?

@torgo sure thing!

I got a CL in that covers a lot of ground and aligns with what was discussed here.

I'll follow up with some more API design questions that came up while we were coding this up momentarily.

Would a name like “presence detector” be more appropriate to a) avoid confusion with requestIdleCallback and b) communicate that you can detect an active state as well as an idle one?

Just to clarify, progress "stalled" has no negative implications, we're still in-progress (or "stalled") with a new (hopefully more efficient) work mode and the dual state means that "we have provided all the technical feedback we could, we know you have acknowledged the feedback and are happy to look at the next iteration when you have something ready".

As for the last comment from @jwheare - we don't have strong opinions about the naming. @kenchris noted that it can be confused with proximity.

Thanks a lot for all the patience, we don't have much more feedback on this so we'll close this as part of our new process. If there are significant changes in the design, please ask us to re-open.

Thanks again for bringing this to our attention.

I would like to ask the TAG to reopen this review as there is now a specification available: https://wicg.github.io/idle-detection

The API design is mostly unchanged from what has been discussed here previously. What has been added is a new 'idle-detection' permission which is required to call start() on an IdleDetector instance.

Hi @reillyeon - one question on this: what is the trajectory for this spec after WICG? Is this intended to be a part of the DAS work? We couldn't find it on the charter. Has there been any thinking on where this ends up? Sorry if that's documented somewhere above and I've missed it.

I do not have a particular destination working group in mind for this incubation.

Sorry this took so long. We discussed this in our F2F today, and the proposed changes look great to us! From the back of our head, this feels like it would belong in Webapps, but as long as it ends up somewhere we are happy.

Thanks for bringing this to our attention.