Document PointerEvent.persistentDeviceId (#35566)

* Document PointerEvent.persistentDeviceId * Update files/en-us/web/api/pointerevent/persistentdeviceid/index.md Co-authored-by: Joshua Chen <[email protected]> * Update files/en-us/web/api/pointerevent/persistentdeviceid/index.md Co-authored-by: Joshua Chen <[email protected]> * Fix note, change variables to camel case * change example to be more generally about pointers, and remove unneeded condition * Fixes for editorial review comments * small wording fix --------- Co-authored-by: Joshua Chen <[email protected]>
mdn · Aug 30, 2024 · ba77b09 · ba77b09
1 parent 8f936e1
commit ba77b09
Show file tree

Hide file tree

Showing 15 changed files with 104 additions and 0 deletions.
diff --git a/files/en-us/web/api/element/gotpointercapture_event/index.md b/files/en-us/web/api/element/gotpointercapture_event/index.md
@@ -34,6 +34,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/element/lostpointercapture_event/index.md b/files/en-us/web/api/element/lostpointercapture_event/index.md
@@ -34,6 +34,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/element/pointercancel_event/index.md b/files/en-us/web/api/element/pointercancel_event/index.md
@@ -45,6 +45,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/element/pointerdown_event/index.md b/files/en-us/web/api/element/pointerdown_event/index.md
@@ -37,6 +37,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/element/pointerenter_event/index.md b/files/en-us/web/api/element/pointerenter_event/index.md
@@ -34,6 +34,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/element/pointerleave_event/index.md b/files/en-us/web/api/element/pointerleave_event/index.md
@@ -34,6 +34,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/element/pointermove_event/index.md b/files/en-us/web/api/element/pointermove_event/index.md
@@ -34,6 +34,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/element/pointerout_event/index.md b/files/en-us/web/api/element/pointerout_event/index.md
@@ -34,6 +34,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/element/pointerover_event/index.md b/files/en-us/web/api/element/pointerover_event/index.md
@@ -34,6 +34,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/element/pointerrawupdate_event/index.md b/files/en-us/web/api/element/pointerrawupdate_event/index.md
@@ -43,6 +43,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/element/pointerup_event/index.md b/files/en-us/web/api/element/pointerup_event/index.md
@@ -34,6 +34,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/pointer_events/index.md b/files/en-us/web/api/pointer_events/index.md
@@ -66,6 +66,8 @@ The {{domxref("PointerEvent")}} interface extends the {{domxref("MouseEvent")}}
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{ domxref('PointerEvent.azimuthAngle', 'azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{ domxref('PointerEvent.pointerId','pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{ domxref('PointerEvent.width','width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/pointerevent/index.md b/files/en-us/web/api/pointerevent/index.md
@@ -28,6 +28,8 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref
   - : Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 - {{domxref('PointerEvent.azimuthAngle')}} {{ReadOnlyInline}} {{experimental_inline}}
   - : Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.
+- {{domxref('PointerEvent.persistentDeviceId')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A unique identifier for the pointing device generating the `PointerEvent`.
 - {{domxref('PointerEvent.pointerId')}} {{ReadOnlyInline}}
   - : A unique identifier for the pointer causing the event.
 - {{domxref('PointerEvent.width')}} {{ReadOnlyInline}}

diff --git a/files/en-us/web/api/pointerevent/persistentdeviceid/index.md b/files/en-us/web/api/pointerevent/persistentdeviceid/index.md
@@ -0,0 +1,75 @@
+---
+title: "PointerEvent: persistentDeviceId property"
+short-title: persistentDeviceId
+slug: Web/API/PointerEvent/persistentDeviceId
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.PointerEvent.persistentDeviceId
+---
+
+{{ APIRef("Pointer Events") }}{{SeeCompatTable}}
+
+The **`persistentDeviceId`** read-only property of the
+{{domxref("PointerEvent")}} interface is a unique identifier for the pointing device generating the `PointerEvent`. This provides a secure, reliable way to identify multiple pointing devices (such as pens) interacting with the screen simultaneously.
+
+A `persistentDeviceId` persists for the lifetime of a browsing session. To avoid the risk of fingerprinting/tracking, pointing devices are assigned a new `persistentDeviceId` at the start of each session.
+
+Pointer events whose generating device could not be identified are assigned a `persistentDeviceId` value of `0`.
+
+## Value
+
+An integer, or `0` if the device generating the `PointerEvent` could not be identified.
+
+> [!NOTE]
+> Due to digitizer and pointing device hardware constraints, a `persistentDeviceId` may not be available for all pointer events, particularly with older hardware. For example, the pointing device might not report its hardware ID to the digitizer in time for `pointerdown` to receive a `persistentDeviceId`: it may initially be `0` and change to a valid value for later events in the stroke.
+
+## Examples
+
+Assuming the following HTML:
+
+```html
+<canvas id="inking-surface" width="1280" height="720"></canvas>
+```
+
+The following JavaScript assigns a different inking color to unique pointers interacting with a canvas:
+
+```js
+const colorBlue = 0;
+const colorGreen = 1;
+const colorYellow = 2;
+const colors = [colorBlue, colorGreen, colorYellow];
+
+const pointerToColorMap = new Map();
+const colorAssignmentIndex = 0;
+
+const canvas = document.querySelector("#inking-surface");
+
+// Listen for a pointerdown event and map the persistentDeviceId to a color
+// if it exists and has not been mapped yet
+canvas.addEventListener("pointerdown", (e) => {
+  if (e.persistentDeviceId && !pointerToColorMap.has(e.persistentDeviceId)) {
+    pointerToColorMap.set(e.persistentDeviceId, colors[colorAssignmentIndex]);
+
+    // Bump the color assignment index and loop back over if needed
+    colorAssignmentIndex = (colorAssignmentIndex + 1) % colors.length;
+  }
+});
+
+// Listen for a `pointermove` and get the color assigned to this pointer
+// if persistentDeviceId exists and the pointer has been color mapped
+canvas.addEventListener("pointermove", (e) => {
+  if (e.persistentDeviceId && pointerToColorMap.has(e.persistentDeviceId)) {
+    const pointerColor = pointerToColorMap.get(e.persistentDeviceId);
+    // Do some inking on the <canvas>
+  }
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
diff --git a/files/en-us/web/api/pointerevent/pointerid/index.md b/files/en-us/web/api/pointerevent/pointerid/index.md
@@ -14,6 +14,9 @@ event. The identifier is unique, being different from the identifiers of all oth
 active pointer events. Since the value may be randomly generated, it is not guaranteed
 to convey any particular meaning.
 
+> [!NOTE]
+> The `pointerId` property is implemented inconsistently across browsers and does not always persist for each ink stroke or interaction with the screen. For a reliable way of identifying multiple pointing devices on a screen simultaneously, see {{domxref("PointerEvent.persistentDeviceId")}}.
+
 ## Value
 
 A number.