add examples for UniFi Protect integration events (#36029)

Co-authored-by: J. Nick Koston <nick@koston.org>

source/_integrations/unifiprotect.markdown

@@ -280,6 +280,32 @@ Three URLs for proxy API endpoints:
 
 The easiest way to find the `nvr_id`, `camera_id`, `start`, and `end` times is by viewing one of the videos from UniFi Protect in the Media browser. If you open the video in a new browser tab, you will see all these values in the URL. The `start` time is close to the last_changed timestamp of the event when the sensor started detecting motion. The `end` time is close to the last_changed timestamp of the event when the sensor stopped detecting motion. Similarly, to see the `event_id` of the image, go to {% my developer_states title="**Developer Tools** > **States**" %} and find the event when the sensor started detecting motion.
 
+### Example Notification Automation with Video
+
+```yaml
+alias: "Security: Camera Motion Notification"
+description: "Sends a notification with video upon motion detection."
+triggers:
+  - entity_id:
+      - binary_sensor.g5_bullet_motion # Replace with your camera entity
+    trigger: state
+    from: "on"
+    to: "off"
+actions:
+  - data:
+      message: "Motion detected at Camera XXX"
+      data:
+        image: >-
+          {% raw %}/api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.from_state.attributes.event_id }}{% endraw %}
+        video: >-
+          {% raw %}/api/unifiprotect/video/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.from_state.attributes.event_id }}{% endraw %}
+    action: notify.mobile_app_your_device # Replace with your notification target
+mode: single
+max_exceeded: silent
+```
+
+Waiting for the motion sensor to change from `on` to `off` before sending the notification is essential. Waiting ensures that the event has ended and the video is accessible; otherwise, you may get an error instead of the video link.
+
 ## Event Entities Support
 
 The UniFi Protect integration provides support for various event types triggered by connected devices. Below are the descriptions for each supported event type:
@@ -292,6 +318,29 @@ The UniFi Protect integration provides support for various event types triggered
   - **event_id**: A unique ID that identifies the doorbell event.
 - **Description**: This event is triggered when someone rings the doorbell. It provides an `event_id`, which can be used to fetch related media, such as a thumbnail of the event. For instance, you can use `event.g4_doorbell_pro_doorbell` to get the thumbnail image when a ring occurs.
 
+#### Example G4 Doorbell Ring Triggered Automation
+
+```yaml
+alias: G4 Doorbell Ring Triggered Automation
+description: Automation that triggers when the G4 Doorbell Pro rings
+triggers:
+  - event_type: state_changed
+    event_data:
+      entity_id: event.g4_doorbell_pro_poe_doorbell # Replace with your doorbell entity
+    trigger: event
+conditions:
+  - condition: template
+    value_template: |
+      {% raw %}{{ 'ring' in trigger.event.data.new_state.attributes.event_types }}{% endraw %}
+actions:
+  - data:
+      message: Someone is at the door!
+      title: Doorbell Notification
+    action: notify.mobile_app_your_device # Replace with your notification target
+```
+
+The condition is required to prevent the notification from being triggered by events of type 'unknown', for example, during a restart.
+
 ### NFC Card Scanned Event
 
 - **Event Name**: NFC
@@ -301,6 +350,38 @@ The UniFi Protect integration provides support for various event types triggered
   - **nfc_id**: The ID of the scanned NFC card.
 - **Description**: This event is triggered when an NFC card is scanned at a compatible device (e.g., a smart doorbell). It contains information such as the `nfc_id` of the scanned card.
 
+#### Example G4 Doorbell NFC Scanned Automation
+
+```yaml
+alias: G4 Doorbell NFC Scanned Automation
+description: >-
+  Automation that triggers when a specific NFC card is scanned on the G4
+  Doorbell Pro
+triggers:
+  - event_type: state_changed
+    event_data:
+      entity_id: event.g4_doorbell_pro_poe_nfc  # Replace with your doorbell entity
+    trigger: event
+conditions:
+  - condition: template
+    value_template: >
+      {% raw %}{{ 
+         trigger.event.data.new_state is not none and
+         trigger.event.data.new_state.attributes.event_type == 'scanned' and
+         trigger.event.data.new_state.attributes.nfc_id in ['ABCDEF1234', 'OTHER_ALLOWED_ID']
+       }}{% endraw %}
+actions:
+  - data:
+      message: >-
+        {% raw %}The NFC card with ID {{ trigger.event.data.new_state.attributes.nfc_id }} has been scanned at the doorbell.{% endraw %}
+      title: NFC Scan Notification
+    action: notify.mobile_app_your_device # Replace with your notification target
+```
+
+**Warning:**
+
+When processing NFC scans, always validate the scanned ID. Unknown NFC cards also trigger the scan event. Additionally, this event was developed using third-party cards, as the developer did not have access to official UniFi cards at the time. With third-party cards, the scan relies on the card's serial number. While this approach is not uncommon, it is essential to note that the card's serial number is generally not considered a secure identifier and can be duplicated relatively easily.
+
 ### Fingerprint Identified Event
 
 - **Event Name**: Fingerprint
@@ -310,6 +391,36 @@ The UniFi Protect integration provides support for various event types triggered
   - **ulp_id**: The fingerprint ID used to identify the person. If no fingerprint match is found, the `ulp_id` will be empty and the `event_type` will be `not_identified`.
 - **Description**: This event is triggered when a fingerprint is scanned by a compatible device. If the fingerprint is recognized, it provides a `ulp_id`, which represents the fingerprint ID. If the fingerprint is not recognized, the `event_type` will be set to `not_identified`, and no `ulp_id` will be provided.
 
+#### Example G4 Doorbell Fingerprint Identified Automation
+
+```yaml
+alias: G4 Doorbell Fingerprint Identified Automation
+description: Automation that triggers when a fingerprint is successfully identified on the G4 Doorbell Pro
+trigger:
+  - platform: event
+    event_type: state_changed
+    event_data:
+      entity_id: event.g4_doorbell_pro_poe_fingerprint # Replace with your doorbell entity
+condition:
+  - condition: template
+    value_template: >
+      {% raw %}{{ 
+         trigger.event.data.new_state is not none and
+         trigger.event.data.new_state.attributes.event_type == 'identified' and
+         (trigger.event.data.new_state.attributes.ulp_id|default('')) != '' and
+         trigger.event.data.new_state.attributes.ulp_id in ['ALLOWED_ID1', 'ALLOWED_ID2']
+       }}{% endraw %}
+action:
+  - service: notify.mobile_app_your_device # Replace with your notification target
+    data:
+      {% raw %}message: "Fingerprint identified with ID: {{ trigger.event.data.new_state.attributes.ulp_id }}"{% endraw %}
+      title: "Fingerprint Scan Notification"
+```
+
+**Warning:**
+
+Similar to NFC, an event is triggered when a fingerprint is recognized and not recognized. However, unlike NFC, at the time of implementation, no fingerprint ID is included in the event if the fingerprint is unknown.
+
 ## Troubleshooting
 
 ### Delay in video feed