diff --git a/.changeset/event-source-union.md b/.changeset/event-source-union.md new file mode 100644 index 00000000..cee50e1c --- /dev/null +++ b/.changeset/event-source-union.md @@ -0,0 +1,5 @@ +--- +'openapi': minor +--- + +**events**: Model `Event` as a union of `EventDevice` and `EventEdge`, discriminated by `source`, in the docs and the Node SDK schema. Other SDK schemas keep a single flat `Event` with optional `source`. diff --git a/schemas/components/schemas/Event.yaml b/schemas/components/schemas/Event.yaml index 65b2872f..4812bf12 100644 --- a/schemas/components/schemas/Event.yaml +++ b/schemas/components/schemas/Event.yaml @@ -1,351 +1,14 @@ type: object -description: Contains results from Fingerprint Identification and all active Smart Signals. Some Smart Signals are only supported for certain device types, these fields will be omitted for events not generated from the supported devices. Consult the [Smart Signals reference](https://docs.fingerprint.com/docs/smart-signals-reference) for more details. -additionalProperties: false -required: - - event_id - - timestamp -properties: - event_id: - $ref: platform/EventId.yaml - x-platforms: - - android - - ios - - browser - timestamp: - $ref: platform/Timestamp.yaml - x-platforms: - - android - - ios - - browser - source: - $ref: platform/EventSource.yaml - x-platforms: - - android - - ios - - browser - incremental_identification_status: - $ref: platform/IncrementalIdentificationStatus.yaml - x-platforms: - - browser - linked_id: - $ref: platform/LinkedId.yaml - x-platforms: - - android - - ios - - browser - environment_id: - $ref: platform/EnvironmentId.yaml - x-platforms: - - android - - ios - - browser - suspect: - $ref: platform/Suspect.yaml - x-platforms: - - android - - ios - - browser - sdk: - $ref: platform/SDK.yaml - x-platforms: - - android - - ios - - browser - replayed: - $ref: platform/Replayed.yaml - x-platforms: - - android - - ios - - browser - triggered_by: - $ref: platform/webhook/TriggeredBy.yaml - identification: - $ref: identification/Identification.yaml - x-platforms: - - android - - ios - - browser - supplementary_id_high_recall: - $ref: identification/SupplementaryIDHighRecall.yaml - x-platforms: - - android - - ios - - browser - tags: - $ref: identification/Tags.yaml - x-platforms: - - android - - ios - - browser - url: - $ref: identification/Url.yaml - x-platforms: - - browser - bundle_id: - $ref: identification/BundleId.yaml - x-platforms: - - ios - package_name: - $ref: identification/PackageName.yaml - x-platforms: - - android - ip_address: - $ref: identification/IpAddress.yaml - x-platforms: - - android - - ios - - browser - user_agent: - $ref: identification/UserAgent.yaml - x-platforms: - - android - - ios - - browser - device: - $ref: identification/Device.yaml - x-platforms: - - android - - ios - - browser - os: - $ref: identification/Os.yaml - x-platforms: - - android - - ios - - browser - os_version: - $ref: identification/OsVersion.yaml - x-platforms: - - android - - ios - - browser - client_referrer: - $ref: identification/ClientReferrer.yaml - x-platforms: - - browser - browser_details: - $ref: identification/BrowserDetails.yaml - x-platforms: - - browser - proximity: - $ref: identification/Proximity.yaml - x-platforms: - - android - - ios - - browser - active_call: - $ref: smartsignals/ActiveCall.yaml - x-platforms: - - android - - ios - bot: - $ref: smartsignals/BotResult.yaml - x-platforms: - - browser - bot_type: - $ref: smartsignals/BotType.yaml - x-platforms: - - browser - bot_info: - $ref: smartsignals/BotInfo.yaml - x-platforms: - - browser - cloned_app: - $ref: smartsignals/ClonedApp.yaml - x-platforms: - - android - developer_tools: - $ref: smartsignals/DeveloperTools.yaml - x-platforms: - - browser - - android - - ios - device_details: - $ref: smartsignals/DeviceDetails.yaml - x-platforms: - - android - - ios - emulator: - $ref: smartsignals/Emulator.yaml - x-platforms: - - android - factory_reset_timestamp: - $ref: smartsignals/FactoryReset.yaml - x-platforms: - - android - - ios - frida: - $ref: smartsignals/Frida.yaml - x-platforms: - - android - - ios - ip_blocklist: - $ref: smartsignals/IPBlockList.yaml - x-platforms: - - android - - ios - - browser - ip_info: - $ref: smartsignals/IPInfo.yaml - x-platforms: - - android - - ios - - browser - proxy: - $ref: smartsignals/Proxy.yaml - x-platforms: - - android - - ios - - browser - proxy_confidence: - $ref: smartsignals/ProxyConfidence.yaml - x-platforms: - - android - - ios - - browser - proxy_details: - $ref: smartsignals/ProxyDetails.yaml - x-platforms: - - android - - ios - - browser - proxy_ml_score: - $ref: smartsignals/ProxyMLScore.yaml - x-platforms: - - browser - incognito: - $ref: smartsignals/Incognito.yaml - x-platforms: - - browser - jailbroken: - $ref: smartsignals/Jailbroken.yaml - x-platforms: - - ios - location_spoofing: - $ref: smartsignals/LocationSpoofing.yaml - x-platforms: - - android - - ios - mitm_attack: - $ref: smartsignals/MitMAttack.yaml - x-platforms: - - android - - ios - privacy_settings: - $ref: smartsignals/PrivacySettings.yaml - x-platforms: - - browser - root_apps: - $ref: smartsignals/RootApps.yaml - x-platforms: - - android - rule_action: - $ref: platform/EventRuleAction.yaml - simulator: - $ref: smartsignals/Simulator.yaml - x-platforms: - - ios - suspect_score: - $ref: smartsignals/SuspectScore.yaml - x-platforms: - - android - - ios - - browser - tampering: - $ref: smartsignals/Tampering.yaml - x-platforms: - - android - - ios - - browser - tampering_confidence: - $ref: smartsignals/TamperingConfidence.yaml - x-platforms: - - android - - ios - - browser - tampering_ml_score: - $ref: smartsignals/TamperingMlScore.yaml - x-platforms: - - android - - ios - - browser - tampering_details: - $ref: smartsignals/TamperingDetails.yaml - x-platforms: - - android - - ios - - browser - velocity: - $ref: smartsignals/Velocity.yaml - x-platforms: - - android - - ios - - browser - virtual_machine: - $ref: smartsignals/VirtualMachine.yaml - x-platforms: - - browser - virtual_machine_ml_score: - $ref: smartsignals/VirtualMachineMLScore.yaml - x-platforms: - - browser - vpn: - $ref: smartsignals/Vpn.yaml - x-platforms: - - android - - ios - - browser - vpn_confidence: - $ref: smartsignals/VpnConfidence.yaml - x-platforms: - - android - - ios - - browser - vpn_ml_score: - $ref: smartsignals/VpnMLScore.yaml - x-platforms: - - browser - vpn_origin_timezone: - $ref: smartsignals/VpnOriginTimezone.yaml - x-platforms: - - android - - ios - - browser - vpn_origin_country: - $ref: smartsignals/VpnOriginCountry.yaml - x-platforms: - - android - - ios - - browser - vpn_methods: - $ref: smartsignals/VpnMethods.yaml - x-platforms: - - android - - ios - - browser - high_activity_device: - $ref: smartsignals/HighActivity.yaml - x-platforms: - - android - - ios - - browser - rare_device: - $ref: smartsignals/RareDevice.yaml - x-platforms: - - browser - rare_device_percentile_bucket: - $ref: smartsignals/RareDevicePercentileBucket.yaml - x-platforms: - - browser - raw_device_attributes: - $ref: smartsignals/RawDeviceAttributes.yaml - x-platforms: - - browser - - ios - - android - labels: - $ref: smartsignals/Labels.yaml - x-platforms: - - browser - - ios - - android +description: | + An event, discriminated by its `source` property. Check `source` before reading other properties, because each source populates a different set of them: + - `device` - an identification event generated by the JS agent or a mobile SDK running on an end-user device. + - `edge` - an event generated by the Automation Intelligence API (`/edge` endpoint), analyzing a request intercepted at the edge. It contains only IP and bot analysis, and never contains Identification (`visitor_id`) or Smart Signals derived from device telemetry. +required: [] +oneOf: + - $ref: EventDevice.yaml + - $ref: EventEdge.yaml +discriminator: + propertyName: source + mapping: + device: EventDevice.yaml + edge: EventEdge.yaml diff --git a/schemas/components/schemas/EventDevice.yaml b/schemas/components/schemas/EventDevice.yaml new file mode 100644 index 00000000..9ffea6b3 --- /dev/null +++ b/schemas/components/schemas/EventDevice.yaml @@ -0,0 +1,353 @@ +type: object +description: An event generated by the JS agent or a mobile SDK running on an end-user device (`source` is `device`). Contains results from Fingerprint Identification and all active Smart Signals. Some Smart Signals are only supported for certain device types, these fields will be omitted for events not generated from the supported devices. Consult the [Smart Signals reference](https://docs.fingerprint.com/docs/smart-signals-reference) for more details. +additionalProperties: false +required: + - event_id + - timestamp + - source +properties: + event_id: + $ref: platform/EventId.yaml + x-platforms: + - android + - ios + - browser + timestamp: + $ref: platform/Timestamp.yaml + x-platforms: + - android + - ios + - browser + source: + $ref: platform/EventSource.yaml + const: device + x-platforms: + - android + - ios + - browser + incremental_identification_status: + $ref: platform/IncrementalIdentificationStatus.yaml + x-platforms: + - browser + linked_id: + $ref: platform/LinkedId.yaml + x-platforms: + - android + - ios + - browser + environment_id: + $ref: platform/EnvironmentId.yaml + x-platforms: + - android + - ios + - browser + suspect: + $ref: platform/Suspect.yaml + x-platforms: + - android + - ios + - browser + sdk: + $ref: platform/SDK.yaml + x-platforms: + - android + - ios + - browser + replayed: + $ref: platform/Replayed.yaml + x-platforms: + - android + - ios + - browser + triggered_by: + $ref: platform/webhook/TriggeredBy.yaml + identification: + $ref: identification/Identification.yaml + x-platforms: + - android + - ios + - browser + supplementary_id_high_recall: + $ref: identification/SupplementaryIDHighRecall.yaml + x-platforms: + - android + - ios + - browser + tags: + $ref: identification/Tags.yaml + x-platforms: + - android + - ios + - browser + url: + $ref: identification/Url.yaml + x-platforms: + - browser + bundle_id: + $ref: identification/BundleId.yaml + x-platforms: + - ios + package_name: + $ref: identification/PackageName.yaml + x-platforms: + - android + ip_address: + $ref: identification/IpAddress.yaml + x-platforms: + - android + - ios + - browser + user_agent: + $ref: identification/UserAgent.yaml + x-platforms: + - android + - ios + - browser + device: + $ref: identification/Device.yaml + x-platforms: + - android + - ios + - browser + os: + $ref: identification/Os.yaml + x-platforms: + - android + - ios + - browser + os_version: + $ref: identification/OsVersion.yaml + x-platforms: + - android + - ios + - browser + client_referrer: + $ref: identification/ClientReferrer.yaml + x-platforms: + - browser + browser_details: + $ref: identification/BrowserDetails.yaml + x-platforms: + - browser + proximity: + $ref: identification/Proximity.yaml + x-platforms: + - android + - ios + - browser + active_call: + $ref: smartsignals/ActiveCall.yaml + x-platforms: + - android + - ios + bot: + $ref: smartsignals/BotResult.yaml + x-platforms: + - browser + bot_type: + $ref: smartsignals/BotType.yaml + x-platforms: + - browser + bot_info: + $ref: smartsignals/BotInfo.yaml + x-platforms: + - browser + cloned_app: + $ref: smartsignals/ClonedApp.yaml + x-platforms: + - android + developer_tools: + $ref: smartsignals/DeveloperTools.yaml + x-platforms: + - browser + - android + - ios + device_details: + $ref: smartsignals/DeviceDetails.yaml + x-platforms: + - android + - ios + emulator: + $ref: smartsignals/Emulator.yaml + x-platforms: + - android + factory_reset_timestamp: + $ref: smartsignals/FactoryReset.yaml + x-platforms: + - android + - ios + frida: + $ref: smartsignals/Frida.yaml + x-platforms: + - android + - ios + ip_blocklist: + $ref: smartsignals/IPBlockList.yaml + x-platforms: + - android + - ios + - browser + ip_info: + $ref: smartsignals/IPInfo.yaml + x-platforms: + - android + - ios + - browser + proxy: + $ref: smartsignals/Proxy.yaml + x-platforms: + - android + - ios + - browser + proxy_confidence: + $ref: smartsignals/ProxyConfidence.yaml + x-platforms: + - android + - ios + - browser + proxy_details: + $ref: smartsignals/ProxyDetails.yaml + x-platforms: + - android + - ios + - browser + proxy_ml_score: + $ref: smartsignals/ProxyMLScore.yaml + x-platforms: + - browser + incognito: + $ref: smartsignals/Incognito.yaml + x-platforms: + - browser + jailbroken: + $ref: smartsignals/Jailbroken.yaml + x-platforms: + - ios + location_spoofing: + $ref: smartsignals/LocationSpoofing.yaml + x-platforms: + - android + - ios + mitm_attack: + $ref: smartsignals/MitMAttack.yaml + x-platforms: + - android + - ios + privacy_settings: + $ref: smartsignals/PrivacySettings.yaml + x-platforms: + - browser + root_apps: + $ref: smartsignals/RootApps.yaml + x-platforms: + - android + rule_action: + $ref: platform/EventRuleAction.yaml + simulator: + $ref: smartsignals/Simulator.yaml + x-platforms: + - ios + suspect_score: + $ref: smartsignals/SuspectScore.yaml + x-platforms: + - android + - ios + - browser + tampering: + $ref: smartsignals/Tampering.yaml + x-platforms: + - android + - ios + - browser + tampering_confidence: + $ref: smartsignals/TamperingConfidence.yaml + x-platforms: + - android + - ios + - browser + tampering_ml_score: + $ref: smartsignals/TamperingMlScore.yaml + x-platforms: + - android + - ios + - browser + tampering_details: + $ref: smartsignals/TamperingDetails.yaml + x-platforms: + - android + - ios + - browser + velocity: + $ref: smartsignals/Velocity.yaml + x-platforms: + - android + - ios + - browser + virtual_machine: + $ref: smartsignals/VirtualMachine.yaml + x-platforms: + - browser + virtual_machine_ml_score: + $ref: smartsignals/VirtualMachineMLScore.yaml + x-platforms: + - browser + vpn: + $ref: smartsignals/Vpn.yaml + x-platforms: + - android + - ios + - browser + vpn_confidence: + $ref: smartsignals/VpnConfidence.yaml + x-platforms: + - android + - ios + - browser + vpn_ml_score: + $ref: smartsignals/VpnMLScore.yaml + x-platforms: + - browser + vpn_origin_timezone: + $ref: smartsignals/VpnOriginTimezone.yaml + x-platforms: + - android + - ios + - browser + vpn_origin_country: + $ref: smartsignals/VpnOriginCountry.yaml + x-platforms: + - android + - ios + - browser + vpn_methods: + $ref: smartsignals/VpnMethods.yaml + x-platforms: + - android + - ios + - browser + high_activity_device: + $ref: smartsignals/HighActivity.yaml + x-platforms: + - android + - ios + - browser + rare_device: + $ref: smartsignals/RareDevice.yaml + x-platforms: + - browser + rare_device_percentile_bucket: + $ref: smartsignals/RareDevicePercentileBucket.yaml + x-platforms: + - browser + raw_device_attributes: + $ref: smartsignals/RawDeviceAttributes.yaml + x-platforms: + - browser + - ios + - android + labels: + $ref: smartsignals/Labels.yaml + x-platforms: + - browser + - ios + - android diff --git a/schemas/components/schemas/EdgeResponse.yaml b/schemas/components/schemas/EventEdge.yaml similarity index 62% rename from schemas/components/schemas/EdgeResponse.yaml rename to schemas/components/schemas/EventEdge.yaml index 33292f5f..8c0ce6cb 100644 --- a/schemas/components/schemas/EdgeResponse.yaml +++ b/schemas/components/schemas/EventEdge.yaml @@ -1,9 +1,10 @@ type: object -description: IP and bot analysis for a request submitted through the Automation Intelligence API. +description: An event generated by the Automation Intelligence API (`source` is `edge`), containing IP and bot analysis for a request intercepted at the edge. No client-side agent is involved, so Identification (`visitor_id`) and Smart Signals derived from device telemetry are not available. `ip_info` is always present, but is empty when no IP intelligence is available for the request. additionalProperties: false required: - event_id - timestamp + - source - ip_info properties: event_id: @@ -12,8 +13,11 @@ properties: $ref: platform/Timestamp.yaml source: $ref: platform/EventSource.yaml + const: edge linked_id: $ref: platform/LinkedId.yaml + environment_id: + $ref: platform/EnvironmentId.yaml tags: $ref: identification/Tags.yaml url: diff --git a/schemas/paths/edge.yaml b/schemas/paths/edge.yaml index 3ac4227f..09945227 100644 --- a/schemas/paths/edge.yaml +++ b/schemas/paths/edge.yaml @@ -37,7 +37,7 @@ post: content: application/json: schema: - $ref: ../components/schemas/EdgeResponse.yaml + $ref: ../components/schemas/EventEdge.yaml examples: 200-ok-bot-detected: summary: Example response when a bot was detected. diff --git a/schemas/paths/examples/webhook/webhook_event.json b/schemas/paths/examples/webhook/webhook_event.json index 35567917..c50663be 100644 --- a/schemas/paths/examples/webhook/webhook_event.json +++ b/schemas/paths/examples/webhook/webhook_event.json @@ -3,9 +3,14 @@ "tags": {}, "timestamp": 1708102555327, "event_id": "1708102555327.NLOjmg", + "source": "device", + "incremental_identification_status": "completed", "url": "https://www.example.com/login?hope{this{works[!", "ip_address": "61.127.217.15", "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ....", + "device": "Other", + "os": "Windows", + "os_version": "7", "client_referrer": "https://example.com/blog/my-article", "browser_details": { "browser_name": "Chrome", @@ -26,14 +31,14 @@ "last_seen_at": 1708102555327 }, "supplementary_id_high_recall": { - "visitor_id": "3HNey93AkBW6CRbxV6xP", + "visitor_id": "0jnGMkPYXX37DqVa4ZIO3f_hr", "visitor_found": true, "confidence": { - "score": 0.97, - "version": "1.1" + "score": 0, + "version": "Not Supported" }, - "first_seen_at": 1708102555327, - "last_seen_at": 1708102555327 + "first_seen_at": 1778086556130, + "last_seen_at": 1778604975494 }, "proximity": { "id": "w1aTfd4MCvl", @@ -111,8 +116,10 @@ "last_seen_at": 1708102555327, "provider": "Massive" }, + "proxy_ml_score": 0.2, "vpn": false, "vpn_confidence": "high", + "vpn_ml_score": 0.2, "vpn_origin_timezone": "Europe/Berlin", "vpn_origin_country": "unknown", "vpn_methods": { @@ -120,10 +127,13 @@ "public_vpn": false, "auxiliary_mobile": false, "os_mismatch": false, - "relay": false + "relay": false, + "ml_prediction": false }, "incognito": false, "tampering": false, + "tampering_confidence": "high", + "tampering_ml_score": 0.3231, "tampering_details": { "anomaly_score": 0.1955, "anti_detect_browser": false @@ -143,6 +153,11 @@ "1_hour": 1, "24_hours": 1 }, + "distinct_linked_id": { + "5_minutes": 1, + "1_hour": 5, + "24_hours": 5 + }, "distinct_country": { "5_minutes": 1, "1_hour": 2, @@ -170,6 +185,11 @@ } }, "developer_tools": false, + "device_details": { + "device_manufacturer": "samsung", + "device_model": "SM-G991U", + "os_version": "13" + }, "mitm_attack": false, "sdk": { "platform": "js", @@ -187,8 +207,6 @@ }, "replayed": false, "high_activity_device": false, - "rare_device": false, - "rare_device_percentile_bucket": "