diff --git a/.changeset/dirty-eels-wash.md b/.changeset/dirty-eels-wash.md new file mode 100644 index 00000000..de8213d2 --- /dev/null +++ b/.changeset/dirty-eels-wash.md @@ -0,0 +1,5 @@ +--- +"@fingerprint/python-sdk": minor +--- + +Add `Simulator` signal for iOS platform diff --git a/.changeset/nervous-boats-poke.md b/.changeset/nervous-boats-poke.md new file mode 100644 index 00000000..5ec5c6e2 --- /dev/null +++ b/.changeset/nervous-boats-poke.md @@ -0,0 +1,5 @@ +--- +"@fingerprint/python-sdk": minor +--- + +Add `virtual_machine_ml_score` field for `VirtualMachine` signal diff --git a/.changeset/ninety-scissors-laugh.md b/.changeset/ninety-scissors-laugh.md new file mode 100644 index 00000000..c2b906a1 --- /dev/null +++ b/.changeset/ninety-scissors-laugh.md @@ -0,0 +1,5 @@ +--- +"@fingerprint/python-sdk": minor +--- + +Add `high_recall_id` and `simulator` filters for the `SearchEvents` method diff --git a/.changeset/orange-coats-roll.md b/.changeset/orange-coats-roll.md new file mode 100644 index 00000000..3fe7d334 --- /dev/null +++ b/.changeset/orange-coats-roll.md @@ -0,0 +1,5 @@ +--- +"@fingerprint/python-sdk": minor +--- + +Add `tampering_confidence` and `tampering_ml_score` fields for `Tampering` smart signal diff --git a/.changeset/tame-seals-breathe.md b/.changeset/tame-seals-breathe.md new file mode 100644 index 00000000..7ab6942f --- /dev/null +++ b/.changeset/tame-seals-breathe.md @@ -0,0 +1,5 @@ +--- +"@fingerprint/python-sdk": patch +--- + +Remove `REQUEST_NOT_FOUND` value from the `ErrorCode` enum diff --git a/.github/workflows/functional_tests.yml b/.github/workflows/functional_tests.yml index f1a2d52a..058e0c7a 100644 --- a/.github/workflows/functional_tests.yml +++ b/.github/workflows/functional_tests.yml @@ -22,7 +22,7 @@ jobs: fail-fast: false max-parallel: 1 matrix: - python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.9", "pypy3.10" ] + python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.11" ] steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d60eb358..6699689f 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -11,7 +11,7 @@ jobs: strategy: matrix: - python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.9", "pypy3.10" ] + python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.11" ] steps: - uses: actions/checkout@v4 diff --git a/.openapi-generator/FILES b/.openapi-generator/FILES index 4fab6971..caf60730 100644 --- a/.openapi-generator/FILES +++ b/.openapi-generator/FILES @@ -24,6 +24,7 @@ docs/IPInfoV4.md docs/IPInfoV6.md docs/Identification.md docs/IdentificationConfidence.md +docs/IncrementalIdentificationStatus.md docs/Integration.md docs/IntegrationSubintegration.md docs/PluginsInner.md @@ -38,9 +39,11 @@ docs/RuleActionType.md docs/SDK.md docs/SealedResults.md docs/SearchEventsBot.md +docs/SearchEventsIncrementalIdentificationStatus.md docs/SearchEventsSdkPlatform.md docs/SearchEventsVpnConfidence.md docs/SupplementaryIDHighRecall.md +docs/TamperingConfidence.md docs/TamperingDetails.md docs/TouchSupport.md docs/Velocity.md @@ -76,6 +79,7 @@ fingerprint_server_sdk/models/geolocation.py fingerprint_server_sdk/models/geolocation_subdivisions_inner.py fingerprint_server_sdk/models/identification.py fingerprint_server_sdk/models/identification_confidence.py +fingerprint_server_sdk/models/incremental_identification_status.py fingerprint_server_sdk/models/integration.py fingerprint_server_sdk/models/integration_subintegration.py fingerprint_server_sdk/models/ip_block_list.py @@ -93,9 +97,11 @@ fingerprint_server_sdk/models/rule_action_header_field.py fingerprint_server_sdk/models/rule_action_type.py fingerprint_server_sdk/models/sdk.py fingerprint_server_sdk/models/search_events_bot.py +fingerprint_server_sdk/models/search_events_incremental_identification_status.py fingerprint_server_sdk/models/search_events_sdk_platform.py fingerprint_server_sdk/models/search_events_vpn_confidence.py fingerprint_server_sdk/models/supplementary_id_high_recall.py +fingerprint_server_sdk/models/tampering_confidence.py fingerprint_server_sdk/models/tampering_details.py fingerprint_server_sdk/models/touch_support.py fingerprint_server_sdk/models/velocity.py diff --git a/.schema-version b/.schema-version index 5e008de3..3a285c2b 100644 --- a/.schema-version +++ b/.schema-version @@ -1 +1 @@ -v3.0.1 \ No newline at end of file +v3.1.0 \ No newline at end of file diff --git a/README.md b/README.md index 559bf225..be69e69f 100644 --- a/README.md +++ b/README.md @@ -348,6 +348,7 @@ Class | Method | HTTP request | Description - [IPInfoV6](docs/IPInfoV6.md) - [Identification](docs/Identification.md) - [IdentificationConfidence](docs/IdentificationConfidence.md) + - [IncrementalIdentificationStatus](docs/IncrementalIdentificationStatus.md) - [Integration](docs/Integration.md) - [IntegrationSubintegration](docs/IntegrationSubintegration.md) - [PluginsInner](docs/PluginsInner.md) @@ -361,9 +362,11 @@ Class | Method | HTTP request | Description - [RuleActionType](docs/RuleActionType.md) - [SDK](docs/SDK.md) - [SearchEventsBot](docs/SearchEventsBot.md) + - [SearchEventsIncrementalIdentificationStatus](docs/SearchEventsIncrementalIdentificationStatus.md) - [SearchEventsSdkPlatform](docs/SearchEventsSdkPlatform.md) - [SearchEventsVpnConfidence](docs/SearchEventsVpnConfidence.md) - [SupplementaryIDHighRecall](docs/SupplementaryIDHighRecall.md) + - [TamperingConfidence](docs/TamperingConfidence.md) - [TamperingDetails](docs/TamperingDetails.md) - [TouchSupport](docs/TouchSupport.md) - [Velocity](docs/Velocity.md) diff --git a/docs/ErrorCode.md b/docs/ErrorCode.md index 0c2260bc..ea45e8d1 100644 --- a/docs/ErrorCode.md +++ b/docs/ErrorCode.md @@ -9,7 +9,6 @@ Error code: * `subscription_not_active` - Fingerprint workspace is not active. * `wrong_region` - Server and workspace region differ. * `feature_not_enabled` - This feature (for example, Delete API) is not enabled for your workspace. -* `request_not_found` - The specified event ID was not found. It never existed, expired, or it has been deleted. * `visitor_not_found` - The specified visitor ID was not found. It never existed or it may have already been deleted. * `too_many_requests` - The limit on secret API key requests per second has been exceeded. * `state_not_ready` - The event specified with event ID is @@ -35,7 +34,6 @@ Error code: * `SUBSCRIPTION_NOT_ACTIVE` (value: `'subscription_not_active'`) * `WRONG_REGION` (value: `'wrong_region'`) * `FEATURE_NOT_ENABLED` (value: `'feature_not_enabled'`) -* `REQUEST_NOT_FOUND` (value: `'request_not_found'`) * `VISITOR_NOT_FOUND` (value: `'visitor_not_found'`) * `TOO_MANY_REQUESTS` (value: `'too_many_requests'`) * `STATE_NOT_READY` (value: `'state_not_ready'`) diff --git a/docs/Event.md b/docs/Event.md index e9159d60..09c810dd 100644 --- a/docs/Event.md +++ b/docs/Event.md @@ -6,6 +6,7 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- **event_id** | **str** | Unique identifier of the user's request. The first portion of the event_id is a unix epoch milliseconds timestamp For example: `1758130560902.8tRtrH` | **timestamp** | **int** | Timestamp of the event with millisecond precision in Unix time. | +**incremental_identification_status** | [**IncrementalIdentificationStatus**](IncrementalIdentificationStatus.md) | | [optional] **linked_id** | **str** | A customer-provided id that was sent with the request. | [optional] **environment_id** | **str** | Environment Id of the event. For example: `ae_47abaca3db2c7c43` | [optional] **suspect** | **bool** | Field is `true` if you have previously set the `suspect` flag for this event using the [Server API Update event endpoint](https://docs.fingerprint.com/reference/server-api-v4-update-event). | [optional] @@ -42,11 +43,15 @@ Name | Type | Description | Notes **privacy_settings** | **bool** | `true` if the request is from a privacy aware browser (e.g. Tor) or from a browser in which fingerprinting is blocked. Otherwise `false`. | [optional] **root_apps** | **bool** | Android specific root management apps detection. There are 2 values: * `true` - Root Management Apps detected (e.g. Magisk). * `false` - No Root Management Apps detected or the client isn't Android. | [optional] **rule_action** | [**EventRuleAction**](EventRuleAction.md) | | [optional] +**simulator** | **bool** | iOS specific simulator detection. There are 2 values: * `true` - Simulator environment detected. * `false` - No signs of simulator or the client is not iOS. | [optional] **suspect_score** | **int** | Suspect Score is an easy way to integrate Smart Signals into your fraud protection work flow. It is a weighted representation of all Smart Signals present in the payload that helps identify suspicious activity. The value range is [0; S] where S is sum of all Smart Signals weights. See more details here: https://docs.fingerprint.com/docs/suspect-score | [optional] **tampering** | **bool** | Flag indicating browser tampering was detected. This happens when either: * There are inconsistencies in the browser configuration that cross internal tampering thresholds (see `tampering_details.anomaly_score`). * The browser signature resembles an \"anti-detect\" browser specifically designed to evade fingerprinting (see `tampering_details.anti_detect_browser`). | [optional] +**tampering_confidence** | [**TamperingConfidence**](TamperingConfidence.md) | | [optional] +**tampering_ml_score** | **float** | A score that indicates the models calculated probability that an event is coming from an anti detect browser. * Values above `0.8` indicate that the request is an anti detect browser based on the ml model * Values below `0.8` indicate that the request is not an anti detect browser based on the ml model | [optional] **tampering_details** | [**TamperingDetails**](TamperingDetails.md) | | [optional] **velocity** | [**Velocity**](Velocity.md) | | [optional] **virtual_machine** | **bool** | `true` if the request came from a browser running inside a virtual machine (e.g. VMWare), `false` otherwise. | [optional] +**virtual_machine_ml_score** | **float** | Machine learning–based virtual machine score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `virtual_machine` detection result | [optional] **vpn** | **bool** | VPN or other anonymizing service has been used when sending the request. | [optional] **vpn_confidence** | [**VpnConfidence**](VpnConfidence.md) | | [optional] **vpn_origin_timezone** | **str** | Local timezone which is used in timezone_mismatch method. | [optional] diff --git a/docs/FingerprintApi.md b/docs/FingerprintApi.md index 1fbd9a3f..0266cbf0 100644 --- a/docs/FingerprintApi.md +++ b/docs/FingerprintApi.md @@ -183,7 +183,7 @@ Name | Type | Description | Notes [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) # **search_events** -> EventSearch search_events(limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, bot=bot, ip_address=ip_address, asn=asn, linked_id=linked_id, url=url, bundle_id=bundle_id, package_name=package_name, origin=origin, start=start, end=end, reverse=reverse, suspect=suspect, vpn=vpn, virtual_machine=virtual_machine, tampering=tampering, anti_detect_browser=anti_detect_browser, incognito=incognito, privacy_settings=privacy_settings, jailbroken=jailbroken, frida=frida, factory_reset=factory_reset, cloned_app=cloned_app, emulator=emulator, root_apps=root_apps, vpn_confidence=vpn_confidence, min_suspect_score=min_suspect_score, developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, environment=environment, proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node) +> EventSearch search_events(limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, ip_address=ip_address, asn=asn, linked_id=linked_id, url=url, bundle_id=bundle_id, package_name=package_name, origin=origin, start=start, end=end, reverse=reverse, suspect=suspect, vpn=vpn, virtual_machine=virtual_machine, tampering=tampering, anti_detect_browser=anti_detect_browser, incognito=incognito, privacy_settings=privacy_settings, jailbroken=jailbroken, frida=frida, factory_reset=factory_reset, cloned_app=cloned_app, emulator=emulator, root_apps=root_apps, vpn_confidence=vpn_confidence, min_suspect_score=min_suspect_score, developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, environment=environment, proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node, incremental_identification_status=incremental_identification_status, simulator=simulator) Search events @@ -218,6 +218,7 @@ import os import fingerprint_server_sdk from fingerprint_server_sdk.models.event_search import EventSearch from fingerprint_server_sdk.models.search_events_bot import SearchEventsBot +from fingerprint_server_sdk.models.search_events_incremental_identification_status import SearchEventsIncrementalIdentificationStatus from fingerprint_server_sdk.models.search_events_sdk_platform import SearchEventsSdkPlatform from fingerprint_server_sdk.models.search_events_vpn_confidence import SearchEventsVpnConfidence from fingerprint_server_sdk import ApiException, ErrorResponse @@ -235,7 +236,8 @@ api_instance = fingerprint_server_sdk.FingerprintApi(configuration) limit: int = 10 # Limit the number of events returned. (optional) (default to 10) pagination_key: str = 'pagination_key_example' # Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. In the following request, use that value in the `pagination_key` parameter to get the next page of results: 1. First request, returning most recent 200 events: `GET api-base-url/events?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=1740815825085` (optional) -visitor_id: str = 'visitor_id_example' # Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter for events matching this `visitor_id`. (optional) +visitor_id: str = 'visitor_id_example' # Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). (optional) +high_recall_id: str = 'high_recall_id_example' # The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). (optional) bot: SearchEventsBot = fingerprint_server_sdk.SearchEventsBot() # Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. (optional) ip_address: str = 'ip_address_example' # Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 (optional) asn: str = 'asn_example' # Filter events by the ASN associated with the event's IP address. This corresponds to the `ip_info.(v4|v6).asn` property in the response. (optional) @@ -268,14 +270,16 @@ mitm_attack: bool = True # Filter events by MITM (Man-in-the-Middle) Attack dete proxy: bool = True # Filter events by Proxy detection result. > Note: When using this parameter, only events with the `proxy` property set to `true` or `false` are returned. Events without a `proxy` Smart Signal result are left out of the response. (optional) sdk_version: str = 'sdk_version_example' # Filter events by a specific SDK version associated with the identification event (`sdk.version` property). Example: `3.11.14` (optional) sdk_platform: SearchEventsSdkPlatform = fingerprint_server_sdk.SearchEventsSdkPlatform() # Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) . `js` - Javascript agent (Web). `ios` - Apple iOS based devices. `android` - Android based devices. (optional) -environment: List[str] = ['environment_example'] # Filter for events by providing one or more environment IDs (`environment_id` property). (optional) +environment: List[str] = ['environment_example'] # Filter for events by providing one or more environment IDs (`environment_id` property). ### Array syntax To provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`). Other notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported. (optional) proximity_id: str = 'proximity_id_example' # Filter events by the most precise Proximity ID provided by default. > Note: When using this parameter, only events with the `proximity.id` property matching the provided ID are returned. Events without a `proximity` result are left out of the response. (optional) total_hits: int = 56 # When set, the response will include a `total_hits` property with a count of total query matches across all pages, up to the specified limit. (optional) tor_node: bool = True # Filter events by Tor Node detection result. > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response. (optional) +incremental_identification_status: SearchEventsIncrementalIdentificationStatus = fingerprint_server_sdk.SearchEventsIncrementalIdentificationStatus() # Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. (optional) +simulator: bool = True # Filter events by iOS Simulator Detection result. > Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response. (optional) try: # Search events - api_response = api_instance.search_events(limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, bot=bot, ip_address=ip_address, asn=asn, linked_id=linked_id, url=url, bundle_id=bundle_id, package_name=package_name, origin=origin, start=start, end=end, reverse=reverse, suspect=suspect, vpn=vpn, virtual_machine=virtual_machine, tampering=tampering, anti_detect_browser=anti_detect_browser, incognito=incognito, privacy_settings=privacy_settings, jailbroken=jailbroken, frida=frida, factory_reset=factory_reset, cloned_app=cloned_app, emulator=emulator, root_apps=root_apps, vpn_confidence=vpn_confidence, min_suspect_score=min_suspect_score, developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, environment=environment, proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node) + api_response = api_instance.search_events(limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, ip_address=ip_address, asn=asn, linked_id=linked_id, url=url, bundle_id=bundle_id, package_name=package_name, origin=origin, start=start, end=end, reverse=reverse, suspect=suspect, vpn=vpn, virtual_machine=virtual_machine, tampering=tampering, anti_detect_browser=anti_detect_browser, incognito=incognito, privacy_settings=privacy_settings, jailbroken=jailbroken, frida=frida, factory_reset=factory_reset, cloned_app=cloned_app, emulator=emulator, root_apps=root_apps, vpn_confidence=vpn_confidence, min_suspect_score=min_suspect_score, developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, environment=environment, proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node, incremental_identification_status=incremental_identification_status, simulator=simulator) print("The response of FingerprintApi->search_events:\n") pprint(api_response) except ApiException as e: @@ -296,7 +300,8 @@ Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **limit** | **int**| Limit the number of events returned. | [optional] [default to 10] **pagination_key** | **str**| Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. In the following request, use that value in the `pagination_key` parameter to get the next page of results: 1. First request, returning most recent 200 events: `GET api-base-url/events?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=1740815825085` | [optional] - **visitor_id** | **str**| Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter for events matching this `visitor_id`. | [optional] + **visitor_id** | **str**| Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). | [optional] + **high_recall_id** | **str**| The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). | [optional] **bot** | [**SearchEventsBot**](.md)| Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. | [optional] **ip_address** | **str**| Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 | [optional] **asn** | **str**| Filter events by the ASN associated with the event's IP address. This corresponds to the `ip_info.(v4|v6).asn` property in the response. | [optional] @@ -329,10 +334,12 @@ Name | Type | Description | Notes **proxy** | **bool**| Filter events by Proxy detection result. > Note: When using this parameter, only events with the `proxy` property set to `true` or `false` are returned. Events without a `proxy` Smart Signal result are left out of the response. | [optional] **sdk_version** | **str**| Filter events by a specific SDK version associated with the identification event (`sdk.version` property). Example: `3.11.14` | [optional] **sdk_platform** | [**SearchEventsSdkPlatform**](.md)| Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) . `js` - Javascript agent (Web). `ios` - Apple iOS based devices. `android` - Android based devices. | [optional] - **environment** | [**List[str]**](str.md)| Filter for events by providing one or more environment IDs (`environment_id` property). | [optional] + **environment** | [**List[str]**](str.md)| Filter for events by providing one or more environment IDs (`environment_id` property). ### Array syntax To provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`). Other notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported. | [optional] **proximity_id** | **str**| Filter events by the most precise Proximity ID provided by default. > Note: When using this parameter, only events with the `proximity.id` property matching the provided ID are returned. Events without a `proximity` result are left out of the response. | [optional] **total_hits** | **int**| When set, the response will include a `total_hits` property with a count of total query matches across all pages, up to the specified limit. | [optional] **tor_node** | **bool**| Filter events by Tor Node detection result. > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response. | [optional] + **incremental_identification_status** | [**SearchEventsIncrementalIdentificationStatus**](.md)| Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. | [optional] + **simulator** | **bool**| Filter events by iOS Simulator Detection result. > Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response. | [optional] ### Return type diff --git a/docs/IncrementalIdentificationStatus.md b/docs/IncrementalIdentificationStatus.md new file mode 100644 index 00000000..779ea103 --- /dev/null +++ b/docs/IncrementalIdentificationStatus.md @@ -0,0 +1,13 @@ +# IncrementalIdentificationStatus +Only included for requests using incremental identification. +- `partially_completed` - the event did not receive the second "update" request. +- `completed` - the event was updated and all information is available. + + +## Enum + +* `PARTIALLY_COMPLETED` (value: `'partially_completed'`) +* `COMPLETED` (value: `'completed'`) + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + diff --git a/docs/SearchEventsIncrementalIdentificationStatus.md b/docs/SearchEventsIncrementalIdentificationStatus.md new file mode 100644 index 00000000..145a6727 --- /dev/null +++ b/docs/SearchEventsIncrementalIdentificationStatus.md @@ -0,0 +1,11 @@ +# SearchEventsIncrementalIdentificationStatus +Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. + + +## Enum + +* `PARTIALLY_COMPLETED` (value: `'partially_completed'`) +* `COMPLETED` (value: `'completed'`) + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + diff --git a/docs/SupplementaryIDHighRecall.md b/docs/SupplementaryIDHighRecall.md index 1c74e02a..dcdf1789 100644 --- a/docs/SupplementaryIDHighRecall.md +++ b/docs/SupplementaryIDHighRecall.md @@ -1,14 +1,14 @@ # SupplementaryIDHighRecall -A supplementary browser identifier that prioritizes coverage over precision. The High Recall ID algorithm matches more generously, i.e., this identifier will remain the same even when there are subtle differences between two requests. This algorithm does not create as many new visitor IDs as the standard algorithms do, but there could be an increase in false-positive identification. +The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. ## Properties Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**visitor_id** | **str** | String of 20 characters that uniquely identifies the visitor's browser or mobile device. | -**visitor_found** | **bool** | Attribute represents if a visitor had been identified before. | +**visitor_id** | **str** | The High Recall identifier for the visitor's browser. It is an alphanumeric string with a maximum length of 25 characters. | +**visitor_found** | **bool** | True if this is a returning browser and has been previously identified. Otherwise, false. | **confidence** | [**IdentificationConfidence**](IdentificationConfidence.md) | | [optional] -**first_seen_at** | **int** | Unix epoch time milliseconds timestamp indicating the time at which this ID was first seen. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000 | [optional] -**last_seen_at** | **int** | Unix epoch time milliseconds timestamp indicating the time at which this ID was last seen. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000 | [optional] +**first_seen_at** | **int** | Unix epoch timestamp (in milliseconds) indicating when the browser was first identified. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000 | [optional] +**last_seen_at** | **int** | Unix epoch timestamp (in milliseconds) corresponding to the most recent visit by this browser. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000 | [optional] [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) diff --git a/docs/TamperingConfidence.md b/docs/TamperingConfidence.md new file mode 100644 index 00000000..1e824853 --- /dev/null +++ b/docs/TamperingConfidence.md @@ -0,0 +1,14 @@ +# TamperingConfidence +Confidence level of the tampering detection. +If a proxy is not detected, confidence is "high". +If it's detected, can be "low", "medium", or "high". + + +## Enum + +* `LOW` (value: `'low'`) +* `MEDIUM` (value: `'medium'`) +* `HIGH` (value: `'high'`) + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + diff --git a/fingerprint_server_sdk/__init__.py b/fingerprint_server_sdk/__init__.py index 26e073e7..969430ba 100644 --- a/fingerprint_server_sdk/__init__.py +++ b/fingerprint_server_sdk/__init__.py @@ -64,6 +64,7 @@ 'IPInfoV6', 'Identification', 'IdentificationConfidence', + 'IncrementalIdentificationStatus', 'Integration', 'IntegrationSubintegration', 'PluginsInner', @@ -77,9 +78,11 @@ 'RuleActionType', 'SDK', 'SearchEventsBot', + 'SearchEventsIncrementalIdentificationStatus', 'SearchEventsSdkPlatform', 'SearchEventsVpnConfidence', 'SupplementaryIDHighRecall', + 'TamperingConfidence', 'TamperingDetails', 'TouchSupport', 'Velocity', @@ -138,6 +141,9 @@ from fingerprint_server_sdk.models.ip_info_v6 import IPInfoV6 from fingerprint_server_sdk.models.identification import Identification from fingerprint_server_sdk.models.identification_confidence import IdentificationConfidence +from fingerprint_server_sdk.models.incremental_identification_status import ( + IncrementalIdentificationStatus, +) from fingerprint_server_sdk.models.integration import Integration from fingerprint_server_sdk.models.integration_subintegration import IntegrationSubintegration from fingerprint_server_sdk.models.plugins_inner import PluginsInner @@ -151,9 +157,13 @@ from fingerprint_server_sdk.models.rule_action_type import RuleActionType from fingerprint_server_sdk.models.sdk import SDK from fingerprint_server_sdk.models.search_events_bot import SearchEventsBot +from fingerprint_server_sdk.models.search_events_incremental_identification_status import ( + SearchEventsIncrementalIdentificationStatus, +) from fingerprint_server_sdk.models.search_events_sdk_platform import SearchEventsSdkPlatform from fingerprint_server_sdk.models.search_events_vpn_confidence import SearchEventsVpnConfidence from fingerprint_server_sdk.models.supplementary_id_high_recall import SupplementaryIDHighRecall +from fingerprint_server_sdk.models.tampering_confidence import TamperingConfidence from fingerprint_server_sdk.models.tampering_details import TamperingDetails from fingerprint_server_sdk.models.touch_support import TouchSupport from fingerprint_server_sdk.models.velocity import Velocity diff --git a/fingerprint_server_sdk/api/fingerprint_api.py b/fingerprint_server_sdk/api/fingerprint_api.py index 2e7205bb..b01cfb8c 100644 --- a/fingerprint_server_sdk/api/fingerprint_api.py +++ b/fingerprint_server_sdk/api/fingerprint_api.py @@ -21,6 +21,9 @@ from fingerprint_server_sdk.models.event_search import EventSearch from fingerprint_server_sdk.models.event_update import EventUpdate from fingerprint_server_sdk.models.search_events_bot import SearchEventsBot +from fingerprint_server_sdk.models.search_events_incremental_identification_status import ( + SearchEventsIncrementalIdentificationStatus, +) from fingerprint_server_sdk.models.search_events_sdk_platform import SearchEventsSdkPlatform from fingerprint_server_sdk.models.search_events_vpn_confidence import SearchEventsVpnConfidence from fingerprint_server_sdk.rest import RESTResponseType @@ -557,7 +560,13 @@ def search_events( visitor_id: Annotated[ Optional[StrictStr], Field( - description='Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter for events matching this `visitor_id`. ' + description='Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). ' + ), + ] = None, + high_recall_id: Annotated[ + Optional[StrictStr], + Field( + description='The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). ' ), ] = None, bot: Annotated[ @@ -750,7 +759,7 @@ def search_events( environment: Annotated[ Optional[list[StrictStr]], Field( - description='Filter for events by providing one or more environment IDs (`environment_id` property). ' + description='Filter for events by providing one or more environment IDs (`environment_id` property). ### Array syntax To provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`). Other notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported. ' ), ] = None, proximity_id: Annotated[ @@ -771,6 +780,18 @@ def search_events( description='Filter events by Tor Node detection result. > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response. ' ), ] = None, + incremental_identification_status: Annotated[ + Optional[SearchEventsIncrementalIdentificationStatus], + Field( + description='Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. ' + ), + ] = None, + simulator: Annotated[ + Optional[StrictBool], + Field( + description='Filter events by iOS Simulator Detection result. > Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response. ' + ), + ] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -788,8 +809,10 @@ def search_events( :type limit: int :param pagination_key: Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. In the following request, use that value in the `pagination_key` parameter to get the next page of results: 1. First request, returning most recent 200 events: `GET api-base-url/events?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=1740815825085` :type pagination_key: str - :param visitor_id: Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter for events matching this `visitor_id`. + :param visitor_id: Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). :type visitor_id: str + :param high_recall_id: The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). + :type high_recall_id: str :param bot: Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. :type bot: SearchEventsBot :param ip_address: Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 @@ -854,7 +877,7 @@ def search_events( :type sdk_version: str :param sdk_platform: Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) . `js` - Javascript agent (Web). `ios` - Apple iOS based devices. `android` - Android based devices. :type sdk_platform: SearchEventsSdkPlatform - :param environment: Filter for events by providing one or more environment IDs (`environment_id` property). + :param environment: Filter for events by providing one or more environment IDs (`environment_id` property). ### Array syntax To provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`). Other notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported. :type environment: List[str] :param proximity_id: Filter events by the most precise Proximity ID provided by default. > Note: When using this parameter, only events with the `proximity.id` property matching the provided ID are returned. Events without a `proximity` result are left out of the response. :type proximity_id: str @@ -862,6 +885,10 @@ def search_events( :type total_hits: int :param tor_node: Filter events by Tor Node detection result. > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response. :type tor_node: bool + :param incremental_identification_status: Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. + :type incremental_identification_status: SearchEventsIncrementalIdentificationStatus + :param simulator: Filter events by iOS Simulator Detection result. > Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response. + :type simulator: bool :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -884,6 +911,7 @@ def search_events( limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, + high_recall_id=high_recall_id, bot=bot, ip_address=ip_address, asn=asn, @@ -920,6 +948,8 @@ def search_events( proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node, + incremental_identification_status=incremental_identification_status, + simulator=simulator, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -955,7 +985,13 @@ def search_events_with_http_info( visitor_id: Annotated[ Optional[StrictStr], Field( - description='Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter for events matching this `visitor_id`. ' + description='Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). ' + ), + ] = None, + high_recall_id: Annotated[ + Optional[StrictStr], + Field( + description='The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). ' ), ] = None, bot: Annotated[ @@ -1148,7 +1184,7 @@ def search_events_with_http_info( environment: Annotated[ Optional[list[StrictStr]], Field( - description='Filter for events by providing one or more environment IDs (`environment_id` property). ' + description='Filter for events by providing one or more environment IDs (`environment_id` property). ### Array syntax To provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`). Other notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported. ' ), ] = None, proximity_id: Annotated[ @@ -1169,6 +1205,18 @@ def search_events_with_http_info( description='Filter events by Tor Node detection result. > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response. ' ), ] = None, + incremental_identification_status: Annotated[ + Optional[SearchEventsIncrementalIdentificationStatus], + Field( + description='Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. ' + ), + ] = None, + simulator: Annotated[ + Optional[StrictBool], + Field( + description='Filter events by iOS Simulator Detection result. > Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response. ' + ), + ] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -1186,8 +1234,10 @@ def search_events_with_http_info( :type limit: int :param pagination_key: Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. In the following request, use that value in the `pagination_key` parameter to get the next page of results: 1. First request, returning most recent 200 events: `GET api-base-url/events?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=1740815825085` :type pagination_key: str - :param visitor_id: Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter for events matching this `visitor_id`. + :param visitor_id: Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). :type visitor_id: str + :param high_recall_id: The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). + :type high_recall_id: str :param bot: Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. :type bot: SearchEventsBot :param ip_address: Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 @@ -1252,7 +1302,7 @@ def search_events_with_http_info( :type sdk_version: str :param sdk_platform: Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) . `js` - Javascript agent (Web). `ios` - Apple iOS based devices. `android` - Android based devices. :type sdk_platform: SearchEventsSdkPlatform - :param environment: Filter for events by providing one or more environment IDs (`environment_id` property). + :param environment: Filter for events by providing one or more environment IDs (`environment_id` property). ### Array syntax To provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`). Other notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported. :type environment: List[str] :param proximity_id: Filter events by the most precise Proximity ID provided by default. > Note: When using this parameter, only events with the `proximity.id` property matching the provided ID are returned. Events without a `proximity` result are left out of the response. :type proximity_id: str @@ -1260,6 +1310,10 @@ def search_events_with_http_info( :type total_hits: int :param tor_node: Filter events by Tor Node detection result. > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response. :type tor_node: bool + :param incremental_identification_status: Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. + :type incremental_identification_status: SearchEventsIncrementalIdentificationStatus + :param simulator: Filter events by iOS Simulator Detection result. > Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response. + :type simulator: bool :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -1282,6 +1336,7 @@ def search_events_with_http_info( limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, + high_recall_id=high_recall_id, bot=bot, ip_address=ip_address, asn=asn, @@ -1318,6 +1373,8 @@ def search_events_with_http_info( proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node, + incremental_identification_status=incremental_identification_status, + simulator=simulator, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -1353,7 +1410,13 @@ def search_events_without_preload_content( visitor_id: Annotated[ Optional[StrictStr], Field( - description='Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter for events matching this `visitor_id`. ' + description='Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). ' + ), + ] = None, + high_recall_id: Annotated[ + Optional[StrictStr], + Field( + description='The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). ' ), ] = None, bot: Annotated[ @@ -1546,7 +1609,7 @@ def search_events_without_preload_content( environment: Annotated[ Optional[list[StrictStr]], Field( - description='Filter for events by providing one or more environment IDs (`environment_id` property). ' + description='Filter for events by providing one or more environment IDs (`environment_id` property). ### Array syntax To provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`). Other notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported. ' ), ] = None, proximity_id: Annotated[ @@ -1567,6 +1630,18 @@ def search_events_without_preload_content( description='Filter events by Tor Node detection result. > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response. ' ), ] = None, + incremental_identification_status: Annotated[ + Optional[SearchEventsIncrementalIdentificationStatus], + Field( + description='Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. ' + ), + ] = None, + simulator: Annotated[ + Optional[StrictBool], + Field( + description='Filter events by iOS Simulator Detection result. > Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response. ' + ), + ] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -1584,8 +1659,10 @@ def search_events_without_preload_content( :type limit: int :param pagination_key: Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. In the following request, use that value in the `pagination_key` parameter to get the next page of results: 1. First request, returning most recent 200 events: `GET api-base-url/events?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=1740815825085` :type pagination_key: str - :param visitor_id: Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter for events matching this `visitor_id`. + :param visitor_id: Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). :type visitor_id: str + :param high_recall_id: The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). + :type high_recall_id: str :param bot: Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. :type bot: SearchEventsBot :param ip_address: Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 @@ -1650,7 +1727,7 @@ def search_events_without_preload_content( :type sdk_version: str :param sdk_platform: Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) . `js` - Javascript agent (Web). `ios` - Apple iOS based devices. `android` - Android based devices. :type sdk_platform: SearchEventsSdkPlatform - :param environment: Filter for events by providing one or more environment IDs (`environment_id` property). + :param environment: Filter for events by providing one or more environment IDs (`environment_id` property). ### Array syntax To provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`). Other notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported. :type environment: List[str] :param proximity_id: Filter events by the most precise Proximity ID provided by default. > Note: When using this parameter, only events with the `proximity.id` property matching the provided ID are returned. Events without a `proximity` result are left out of the response. :type proximity_id: str @@ -1658,6 +1735,10 @@ def search_events_without_preload_content( :type total_hits: int :param tor_node: Filter events by Tor Node detection result. > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response. :type tor_node: bool + :param incremental_identification_status: Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. + :type incremental_identification_status: SearchEventsIncrementalIdentificationStatus + :param simulator: Filter events by iOS Simulator Detection result. > Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response. + :type simulator: bool :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -1680,6 +1761,7 @@ def search_events_without_preload_content( limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, + high_recall_id=high_recall_id, bot=bot, ip_address=ip_address, asn=asn, @@ -1716,6 +1798,8 @@ def search_events_without_preload_content( proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node, + incremental_identification_status=incremental_identification_status, + simulator=simulator, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -1736,6 +1820,7 @@ def _search_events_serialize( limit: Optional[int], pagination_key: Optional[str], visitor_id: Optional[str], + high_recall_id: Optional[str], bot: Optional[SearchEventsBot], ip_address: Optional[str], asn: Optional[str], @@ -1772,6 +1857,8 @@ def _search_events_serialize( proximity_id: Optional[str], total_hits: Optional[int], tor_node: Optional[bool], + incremental_identification_status: Optional[SearchEventsIncrementalIdentificationStatus], + simulator: Optional[bool], _request_auth: Optional[dict[StrictStr, Any]], _content_type: Optional[StrictStr], _headers: Optional[dict[StrictStr, Any]], @@ -1803,6 +1890,10 @@ def _search_events_serialize( if visitor_id is not None: _query_params.append(('visitor_id', visitor_id)) + # process the query parameters + if high_recall_id is not None: + _query_params.append(('high_recall_id', high_recall_id)) + # process the query parameters if bot is not None: _query_params.append(('bot', bot.value)) @@ -1947,6 +2038,16 @@ def _search_events_serialize( if tor_node is not None: _query_params.append(('tor_node', tor_node)) + # process the query parameters + if incremental_identification_status is not None: + _query_params.append( + ('incremental_identification_status', incremental_identification_status.value) + ) + + # process the query parameters + if simulator is not None: + _query_params.append(('simulator', simulator)) + # set the HTTP header `Accept` if 'Accept' not in _header_params: _header_params['Accept'] = self.api_client.select_header_accept(['application/json']) diff --git a/fingerprint_server_sdk/models/__init__.py b/fingerprint_server_sdk/models/__init__.py index 7ec04cdf..5b5528af 100644 --- a/fingerprint_server_sdk/models/__init__.py +++ b/fingerprint_server_sdk/models/__init__.py @@ -37,6 +37,9 @@ from fingerprint_server_sdk.models.ip_info_v6 import IPInfoV6 from fingerprint_server_sdk.models.identification import Identification from fingerprint_server_sdk.models.identification_confidence import IdentificationConfidence +from fingerprint_server_sdk.models.incremental_identification_status import ( + IncrementalIdentificationStatus, +) from fingerprint_server_sdk.models.integration import Integration from fingerprint_server_sdk.models.integration_subintegration import IntegrationSubintegration from fingerprint_server_sdk.models.plugins_inner import PluginsInner @@ -50,9 +53,13 @@ from fingerprint_server_sdk.models.rule_action_type import RuleActionType from fingerprint_server_sdk.models.sdk import SDK from fingerprint_server_sdk.models.search_events_bot import SearchEventsBot +from fingerprint_server_sdk.models.search_events_incremental_identification_status import ( + SearchEventsIncrementalIdentificationStatus, +) from fingerprint_server_sdk.models.search_events_sdk_platform import SearchEventsSdkPlatform from fingerprint_server_sdk.models.search_events_vpn_confidence import SearchEventsVpnConfidence from fingerprint_server_sdk.models.supplementary_id_high_recall import SupplementaryIDHighRecall +from fingerprint_server_sdk.models.tampering_confidence import TamperingConfidence from fingerprint_server_sdk.models.tampering_details import TamperingDetails from fingerprint_server_sdk.models.touch_support import TouchSupport from fingerprint_server_sdk.models.velocity import Velocity diff --git a/fingerprint_server_sdk/models/error_code.py b/fingerprint_server_sdk/models/error_code.py index 11d9cfb6..5762c209 100644 --- a/fingerprint_server_sdk/models/error_code.py +++ b/fingerprint_server_sdk/models/error_code.py @@ -20,7 +20,7 @@ class ErrorCode(str, Enum): """ - Error code: * `request_cannot_be_parsed` - The query parameters or JSON payload contains some errors that prevented us from parsing it (wrong type/surpassed limits). * `secret_api_key_required` - secret API key in header is missing or empty. * `secret_api_key_not_found` - No Fingerprint workspace found for specified secret API key. * `public_api_key_required` - public API key in header is missing or empty. * `public_api_key_not_found` - No Fingerprint workspace found for specified public API key. * `subscription_not_active` - Fingerprint workspace is not active. * `wrong_region` - Server and workspace region differ. * `feature_not_enabled` - This feature (for example, Delete API) is not enabled for your workspace. * `request_not_found` - The specified event ID was not found. It never existed, expired, or it has been deleted. * `visitor_not_found` - The specified visitor ID was not found. It never existed or it may have already been deleted. * `too_many_requests` - The limit on secret API key requests per second has been exceeded. * `state_not_ready` - The event specified with event ID is not ready for updates yet. Try again. This error happens in rare cases when update API is called immediately after receiving the event ID on the client. In case you need to send information right away, we recommend using the JS agent API instead. * `failed` - Internal server error. * `event_not_found` - The specified event ID was not found. It never existed, expired, or it has been deleted. * `missing_module` - The request is invalid because it is missing a required module. * `payload_too_large` - The request payload is too large and cannot be processed. * `service_unavailable` - The service was unable to process the request. * `ruleset_not_found` - The specified ruleset was not found. It never existed or it has been deleted. + Error code: * `request_cannot_be_parsed` - The query parameters or JSON payload contains some errors that prevented us from parsing it (wrong type/surpassed limits). * `secret_api_key_required` - secret API key in header is missing or empty. * `secret_api_key_not_found` - No Fingerprint workspace found for specified secret API key. * `public_api_key_required` - public API key in header is missing or empty. * `public_api_key_not_found` - No Fingerprint workspace found for specified public API key. * `subscription_not_active` - Fingerprint workspace is not active. * `wrong_region` - Server and workspace region differ. * `feature_not_enabled` - This feature (for example, Delete API) is not enabled for your workspace. * `visitor_not_found` - The specified visitor ID was not found. It never existed or it may have already been deleted. * `too_many_requests` - The limit on secret API key requests per second has been exceeded. * `state_not_ready` - The event specified with event ID is not ready for updates yet. Try again. This error happens in rare cases when update API is called immediately after receiving the event ID on the client. In case you need to send information right away, we recommend using the JS agent API instead. * `failed` - Internal server error. * `event_not_found` - The specified event ID was not found. It never existed, expired, or it has been deleted. * `missing_module` - The request is invalid because it is missing a required module. * `payload_too_large` - The request payload is too large and cannot be processed. * `service_unavailable` - The service was unable to process the request. * `ruleset_not_found` - The specified ruleset was not found. It never existed or it has been deleted. """ """ @@ -34,7 +34,6 @@ class ErrorCode(str, Enum): SUBSCRIPTION_NOT_ACTIVE = 'subscription_not_active' WRONG_REGION = 'wrong_region' FEATURE_NOT_ENABLED = 'feature_not_enabled' - REQUEST_NOT_FOUND = 'request_not_found' VISITOR_NOT_FOUND = 'visitor_not_found' TOO_MANY_REQUESTS = 'too_many_requests' STATE_NOT_READY = 'state_not_ready' diff --git a/fingerprint_server_sdk/models/event.py b/fingerprint_server_sdk/models/event.py index ed680817..49a40fd5 100644 --- a/fingerprint_server_sdk/models/event.py +++ b/fingerprint_server_sdk/models/event.py @@ -15,7 +15,7 @@ import json import pprint import re # noqa: F401 -from typing import Any, ClassVar, Optional +from typing import Annotated, Any, ClassVar, Optional, Union from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictInt, StrictStr from typing_extensions import Self @@ -25,6 +25,9 @@ from fingerprint_server_sdk.models.browser_details import BrowserDetails from fingerprint_server_sdk.models.event_rule_action import EventRuleAction from fingerprint_server_sdk.models.identification import Identification +from fingerprint_server_sdk.models.incremental_identification_status import ( + IncrementalIdentificationStatus, +) from fingerprint_server_sdk.models.ip_block_list import IPBlockList from fingerprint_server_sdk.models.ip_info import IPInfo from fingerprint_server_sdk.models.proximity import Proximity @@ -33,6 +36,7 @@ from fingerprint_server_sdk.models.raw_device_attributes import RawDeviceAttributes from fingerprint_server_sdk.models.sdk import SDK from fingerprint_server_sdk.models.supplementary_id_high_recall import SupplementaryIDHighRecall +from fingerprint_server_sdk.models.tampering_confidence import TamperingConfidence from fingerprint_server_sdk.models.tampering_details import TamperingDetails from fingerprint_server_sdk.models.velocity import Velocity from fingerprint_server_sdk.models.vpn_confidence import VpnConfidence @@ -50,6 +54,7 @@ class Event(BaseModel): timestamp: StrictInt = Field( description='Timestamp of the event with millisecond precision in Unix time.' ) + incremental_identification_status: Optional[IncrementalIdentificationStatus] = None linked_id: Optional[StrictStr] = Field( default=None, description='A customer-provided id that was sent with the request.' ) @@ -155,6 +160,10 @@ class Event(BaseModel): description="Android specific root management apps detection. There are 2 values: * `true` - Root Management Apps detected (e.g. Magisk). * `false` - No Root Management Apps detected or the client isn't Android. ", ) rule_action: Optional[EventRuleAction] = None + simulator: Optional[StrictBool] = Field( + default=None, + description='iOS specific simulator detection. There are 2 values: * `true` - Simulator environment detected. * `false` - No signs of simulator or the client is not iOS. ', + ) suspect_score: Optional[StrictInt] = Field( default=None, description='Suspect Score is an easy way to integrate Smart Signals into your fraud protection work flow. It is a weighted representation of all Smart Signals present in the payload that helps identify suspicious activity. The value range is [0; S] where S is sum of all Smart Signals weights. See more details here: https://docs.fingerprint.com/docs/suspect-score ', @@ -163,12 +172,31 @@ class Event(BaseModel): default=None, description='Flag indicating browser tampering was detected. This happens when either: * There are inconsistencies in the browser configuration that cross internal tampering thresholds (see `tampering_details.anomaly_score`). * The browser signature resembles an "anti-detect" browser specifically designed to evade fingerprinting (see `tampering_details.anti_detect_browser`). ', ) + tampering_confidence: Optional[TamperingConfidence] = None + tampering_ml_score: Optional[ + Union[ + Annotated[float, Field(le=1, strict=True, ge=0)], + Annotated[int, Field(le=1, strict=True, ge=0)], + ] + ] = Field( + default=None, + description='A score that indicates the models calculated probability that an event is coming from an anti detect browser. * Values above `0.8` indicate that the request is an anti detect browser based on the ml model * Values below `0.8` indicate that the request is not an anti detect browser based on the ml model ', + ) tampering_details: Optional[TamperingDetails] = None velocity: Optional[Velocity] = None virtual_machine: Optional[StrictBool] = Field( default=None, description='`true` if the request came from a browser running inside a virtual machine (e.g. VMWare), `false` otherwise. ', ) + virtual_machine_ml_score: Optional[ + Union[ + Annotated[float, Field(le=1, strict=True, ge=0)], + Annotated[int, Field(le=1, strict=True, ge=0)], + ] + ] = Field( + default=None, + description='Machine learning–based virtual machine score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `virtual_machine` detection result ', + ) vpn: Optional[StrictBool] = Field( default=None, description='VPN or other anonymizing service has been used when sending the request. ', @@ -190,6 +218,7 @@ class Event(BaseModel): __properties: ClassVar[list[str]] = [ 'event_id', 'timestamp', + 'incremental_identification_status', 'linked_id', 'environment_id', 'suspect', @@ -226,11 +255,15 @@ class Event(BaseModel): 'privacy_settings', 'root_apps', 'rule_action', + 'simulator', 'suspect_score', 'tampering', + 'tampering_confidence', + 'tampering_ml_score', 'tampering_details', 'velocity', 'virtual_machine', + 'virtual_machine_ml_score', 'vpn', 'vpn_confidence', 'vpn_origin_timezone', @@ -334,6 +367,7 @@ def from_dict(cls, obj: Optional[dict[str, Any]]) -> Optional[Self]: { 'event_id': obj.get('event_id'), 'timestamp': obj.get('timestamp'), + 'incremental_identification_status': obj.get('incremental_identification_status'), 'linked_id': obj.get('linked_id'), 'environment_id': obj.get('environment_id'), 'suspect': obj.get('suspect'), @@ -390,8 +424,11 @@ def from_dict(cls, obj: Optional[dict[str, Any]]) -> Optional[Self]: 'rule_action': EventRuleAction.from_dict(obj['rule_action']) if obj.get('rule_action') is not None else None, + 'simulator': obj.get('simulator'), 'suspect_score': obj.get('suspect_score'), 'tampering': obj.get('tampering'), + 'tampering_confidence': obj.get('tampering_confidence'), + 'tampering_ml_score': obj.get('tampering_ml_score'), 'tampering_details': TamperingDetails.from_dict(obj['tampering_details']) if obj.get('tampering_details') is not None else None, @@ -399,6 +436,7 @@ def from_dict(cls, obj: Optional[dict[str, Any]]) -> Optional[Self]: if obj.get('velocity') is not None else None, 'virtual_machine': obj.get('virtual_machine'), + 'virtual_machine_ml_score': obj.get('virtual_machine_ml_score'), 'vpn': obj.get('vpn'), 'vpn_confidence': obj.get('vpn_confidence'), 'vpn_origin_timezone': obj.get('vpn_origin_timezone'), diff --git a/fingerprint_server_sdk/models/incremental_identification_status.py b/fingerprint_server_sdk/models/incremental_identification_status.py new file mode 100644 index 00000000..81060b60 --- /dev/null +++ b/fingerprint_server_sdk/models/incremental_identification_status.py @@ -0,0 +1,35 @@ +""" +Server API +Fingerprint Server API allows you to get, search, and update Events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. +Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device. + +The version of the OpenAPI document: 4 +Contact: support@fingerprint.com +Generated by OpenAPI Generator (https://openapi-generator.tech) + +Do not edit the class manually. +""" # noqa: E501 + +from __future__ import annotations + +import json +from enum import Enum + +from typing_extensions import Self + + +class IncrementalIdentificationStatus(str, Enum): + """ + Only included for requests using incremental identification. - `partially_completed` - the event did not receive the second \"update\" request. - `completed` - the event was updated and all information is available. + """ + + """ + allowed enum values + """ + PARTIALLY_COMPLETED = 'partially_completed' + COMPLETED = 'completed' + + @classmethod + def from_json(cls, json_str: str) -> Self: + """Create an instance of IncrementalIdentificationStatus from a JSON string""" + return cls(json.loads(json_str)) diff --git a/fingerprint_server_sdk/models/search_events_incremental_identification_status.py b/fingerprint_server_sdk/models/search_events_incremental_identification_status.py new file mode 100644 index 00000000..f58c5f7a --- /dev/null +++ b/fingerprint_server_sdk/models/search_events_incremental_identification_status.py @@ -0,0 +1,35 @@ +""" +Server API +Fingerprint Server API allows you to get, search, and update Events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. +Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device. + +The version of the OpenAPI document: 4 +Contact: support@fingerprint.com +Generated by OpenAPI Generator (https://openapi-generator.tech) + +Do not edit the class manually. +""" # noqa: E501 + +from __future__ import annotations + +import json +from enum import Enum + +from typing_extensions import Self + + +class SearchEventsIncrementalIdentificationStatus(str, Enum): + """ + Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response. + """ + + """ + allowed enum values + """ + PARTIALLY_COMPLETED = 'partially_completed' + COMPLETED = 'completed' + + @classmethod + def from_json(cls, json_str: str) -> Self: + """Create an instance of SearchEventsIncrementalIdentificationStatus from a JSON string""" + return cls(json.loads(json_str)) diff --git a/fingerprint_server_sdk/models/supplementary_id_high_recall.py b/fingerprint_server_sdk/models/supplementary_id_high_recall.py index b0398021..0818e3f5 100644 --- a/fingerprint_server_sdk/models/supplementary_id_high_recall.py +++ b/fingerprint_server_sdk/models/supplementary_id_high_recall.py @@ -25,23 +25,23 @@ class SupplementaryIDHighRecall(BaseModel): """ - A supplementary browser identifier that prioritizes coverage over precision. The High Recall ID algorithm matches more generously, i.e., this identifier will remain the same even when there are subtle differences between two requests. This algorithm does not create as many new visitor IDs as the standard algorithms do, but there could be an increase in false-positive identification. + The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. """ visitor_id: StrictStr = Field( - description="String of 20 characters that uniquely identifies the visitor's browser or mobile device." + description="The High Recall identifier for the visitor's browser. It is an alphanumeric string with a maximum length of 25 characters." ) visitor_found: StrictBool = Field( - description='Attribute represents if a visitor had been identified before.' + description='True if this is a returning browser and has been previously identified. Otherwise, false.' ) confidence: Optional[IdentificationConfidence] = None first_seen_at: Optional[StrictInt] = Field( default=None, - description='Unix epoch time milliseconds timestamp indicating the time at which this ID was first seen. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000 ', + description='Unix epoch timestamp (in milliseconds) indicating when the browser was first identified. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000 ', ) last_seen_at: Optional[StrictInt] = Field( default=None, - description='Unix epoch time milliseconds timestamp indicating the time at which this ID was last seen. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000 ', + description='Unix epoch timestamp (in milliseconds) corresponding to the most recent visit by this browser. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000 ', ) __properties: ClassVar[list[str]] = [ 'visitor_id', diff --git a/fingerprint_server_sdk/models/tampering_confidence.py b/fingerprint_server_sdk/models/tampering_confidence.py new file mode 100644 index 00000000..42daf1d5 --- /dev/null +++ b/fingerprint_server_sdk/models/tampering_confidence.py @@ -0,0 +1,36 @@ +""" +Server API +Fingerprint Server API allows you to get, search, and update Events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. +Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device. + +The version of the OpenAPI document: 4 +Contact: support@fingerprint.com +Generated by OpenAPI Generator (https://openapi-generator.tech) + +Do not edit the class manually. +""" # noqa: E501 + +from __future__ import annotations + +import json +from enum import Enum + +from typing_extensions import Self + + +class TamperingConfidence(str, Enum): + """ + Confidence level of the tampering detection. If a proxy is not detected, confidence is \"high\". If it's detected, can be \"low\", \"medium\", or \"high\". + """ + + """ + allowed enum values + """ + LOW = 'low' + MEDIUM = 'medium' + HIGH = 'high' + + @classmethod + def from_json(cls, json_str: str) -> Self: + """Create an instance of TamperingConfidence from a JSON string""" + return cls(json.loads(json_str)) diff --git a/res/fingerprint-server-api.yaml b/res/fingerprint-server-api.yaml index db15fe10..8335daf4 100644 --- a/res/fingerprint-server-api.yaml +++ b/res/fingerprint-server-api.yaml @@ -271,7 +271,26 @@ paths: identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. - Filter for events matching this `visitor_id`. + + Filter events by matching Visitor ID (`identification.visitor_id` + property). + - name: high_recall_id + in: query + schema: + type: string + description: > + The High Recall ID is a supplementary browser identifier designed + for use cases that require wider coverage over precision. Compared + to the standard visitor ID, the High Recall ID strives to match + incoming browsers more generously (rather than precisely) with + existing browsers and thus identifies fewer browsers as new. The + High Recall ID is best suited for use cases that are sensitive to + browsers being identified as new and where mismatched browsers are + not detrimental. + + + Filter events by matching High Recall ID + (`supplementary_id_high_recall.visitor_id` property). - name: bot in: query schema: @@ -598,6 +617,16 @@ paths: description: > Filter for events by providing one or more environment IDs (`environment_id` property). + + + ### Array syntax + + To provide multiple environment IDs, use the repeated keys syntax + (`environment=env1&environment=env2`). + + Other notations like comma-separated (`environment=env1,env2`) or + bracket notation (`environment[]=env1&environment[]=env2`) are not + supported. required: false schema: type: array @@ -635,6 +664,25 @@ paths: > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response. + - name: incremental_identification_status + in: query + schema: + $ref: '#/components/schemas/SearchEventsIncrementalIdentificationStatus' + description: > + Filter events by their incremental identification status + (`incremental_identification_status` property). Non incremental + identification events are left out of the response. + - name: simulator + in: query + schema: + type: boolean + description: > + Filter events by iOS Simulator Detection result. + + + > Note: When using this parameter, only events with the `simulator` + property set to `true` or `false` are returned. Events without a + `simulator` Smart Signal result are left out of the response. responses: '200': description: Events matching the filter(s). @@ -779,6 +827,18 @@ components: description: Timestamp of the event with millisecond precision in Unix time. type: integer format: int64 + IncrementalIdentificationStatus: + type: string + description: > + Only included for requests using incremental identification. + + - `partially_completed` - the event did not receive the second "update" + request. + + - `completed` - the event was updated and all information is available. + enum: + - partially_completed + - completed LinkedId: type: string description: A customer-provided id that was sent with the request. @@ -893,12 +953,13 @@ components: SupplementaryIDHighRecall: type: object description: >- - A supplementary browser identifier that prioritizes coverage over - precision. The High Recall ID algorithm matches more generously, i.e., - this identifier will remain the same even when there are subtle - differences between two requests. This algorithm does not create as many - new visitor IDs as the standard algorithms do, but there could be an - increase in false-positive identification. + The High Recall ID is a supplementary browser identifier designed for + use cases that require wider coverage over precision. Compared to the + standard visitor ID, the High Recall ID strives to match incoming + browsers more generously (rather than precisely) with existing browsers + and thus identifies fewer browsers as new. The High Recall ID is best + suited for use cases that are sensitive to browsers being identified as + new and where mismatched browsers are not detrimental. required: - visitor_id - visitor_found @@ -906,27 +967,29 @@ components: visitor_id: type: string description: >- - String of 20 characters that uniquely identifies the visitor's - browser or mobile device. + The High Recall identifier for the visitor's browser. It is an + alphanumeric string with a maximum length of 25 characters. visitor_found: type: boolean - description: Attribute represents if a visitor had been identified before. + description: >- + True if this is a returning browser and has been previously + identified. Otherwise, false. confidence: $ref: '#/components/schemas/IdentificationConfidence' first_seen_at: type: integer format: int64 description: > - Unix epoch time milliseconds timestamp indicating the time at which - this ID was first seen. example: `1758069706642` - Corresponding to + Unix epoch timestamp (in milliseconds) indicating when the browser + was first identified. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000 last_seen_at: type: integer format: int64 description: > - Unix epoch time milliseconds timestamp indicating the time at which - this ID was last seen. example: `1758069706642` - Corresponding to - Wed Sep 17 2025 00:41:46 GMT+0000 + Unix epoch timestamp (in milliseconds) corresponding to the most + recent visit by this browser. example: `1758069706642` - + Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000 Tags: type: object description: >- @@ -1085,11 +1148,14 @@ components: ClonedApp: type: boolean description: > - Android specific cloned application detection. There are 2 values: * - `true` - Presence of app cloners work detected (e.g. fully cloned + Android specific cloned application detection. There are 2 values: + + * `true` - Presence of app cloners work detected (e.g. fully cloned application found or launch of it inside of a not main working profile - detected). * `false` - No signs of cloned application detected or the - client is not Android. + detected). + + * `false` - No signs of cloned application detected or the client is not + Android. DeveloperTools: type: boolean description: > @@ -1445,6 +1511,12 @@ components: mapping: allow: '#/components/schemas/EventRuleActionAllow' block: '#/components/schemas/EventRuleActionBlock' + Simulator: + type: boolean + description: | + iOS specific simulator detection. There are 2 values: + * `true` - Simulator environment detected. + * `false` - No signs of simulator or the client is not iOS. SuspectScore: type: integer description: > @@ -1460,6 +1532,26 @@ components: either: * There are inconsistencies in the browser configuration that cross internal tampering thresholds (see `tampering_details.anomaly_score`). * The browser signature resembles an "anti-detect" browser specifically designed to evade fingerprinting (see `tampering_details.anti_detect_browser`). + TamperingConfidence: + type: string + enum: + - low + - medium + - high + description: | + Confidence level of the tampering detection. + If a proxy is not detected, confidence is "high". + If it's detected, can be "low", "medium", or "high". + TamperingMlScore: + type: number + format: double + minimum: 0 + maximum: 1 + description: > + A score that indicates the models calculated probability that an event + is coming from an anti detect browser. + * Values above `0.8` indicate that the request is an anti detect browser based on the ml model + * Values below `0.8` indicate that the request is not an anti detect browser based on the ml model TamperingDetails: type: object properties: @@ -1572,6 +1664,16 @@ components: description: > `true` if the request came from a browser running inside a virtual machine (e.g. VMWare), `false` otherwise. + VirtualMachineMLScore: + type: number + format: double + minimum: 0 + maximum: 1 + description: > + Machine learning–based virtual machine score, represented as a + floating-point value between 0 and 1 (inclusive), with up to three + decimal places of precision. A higher score means a higher confidence in + the positive `virtual_machine` detection result Vpn: type: boolean description: | @@ -1828,11 +1930,15 @@ components: type: string description: > Locale derived from the Intl.DateTimeFormat API. Negative values - indicate known error states. The negative statuses can be: - "-1": A - permanent status for browsers that don't support Intl API. - "-2": A - permanent status for browsers that don't supportDateTimeFormat - constructor. - "-3": A permanent status for browsers in which - DateTimeFormat locale is undefined or null. + indicate known error states. The negative statuses can be: + + - "-1": A permanent status for browsers that don't support Intl API. + + - "-2": A permanent status for browsers that don't supportDateTimeFormat + constructor. + + - "-3": A permanent status for browsers in which DateTimeFormat locale + is undefined or null. Vendor: type: string description: Navigator vendor string. @@ -1854,10 +1960,15 @@ components: format: double description: > AudioContext fingerprint or negative status when unavailable. The - negative statuses can be: - -1: A permanent status for those browsers - which are known to always suspend audio context - -2: A permanent status - for browsers that don't support the signal - -3: A temporary status that - means that an unexpected timeout has happened + negative statuses can be: + + - -1: A permanent status for those browsers which are known to always + suspend audio context + + - -2: A permanent status for browsers that don't support the signal + + - -3: A temporary status that means that an unexpected timeout has + happened Plugins: type: array description: Browser plugins reported by `navigator.plugins`. @@ -1965,6 +2076,10 @@ components: - android - ios - browser + incremental_identification_status: + $ref: '#/components/schemas/IncrementalIdentificationStatus' + x-platforms: + - browser linked_id: $ref: '#/components/schemas/LinkedId' x-platforms: @@ -2142,6 +2257,10 @@ components: - android rule_action: $ref: '#/components/schemas/EventRuleAction' + simulator: + $ref: '#/components/schemas/Simulator' + x-platforms: + - ios suspect_score: $ref: '#/components/schemas/SuspectScore' x-platforms: @@ -2154,6 +2273,18 @@ components: - android - ios - browser + tampering_confidence: + $ref: '#/components/schemas/TamperingConfidence' + x-platforms: + - android + - ios + - browser + tampering_ml_score: + $ref: '#/components/schemas/TamperingMlScore' + x-platforms: + - android + - ios + - browser tampering_details: $ref: '#/components/schemas/TamperingDetails' x-platforms: @@ -2170,6 +2301,10 @@ components: $ref: '#/components/schemas/VirtualMachine' x-platforms: - browser + virtual_machine_ml_score: + $ref: '#/components/schemas/VirtualMachineMLScore' + x-platforms: + - browser vpn: $ref: '#/components/schemas/Vpn' x-platforms: @@ -2220,7 +2355,6 @@ components: - subscription_not_active - wrong_region - feature_not_enabled - - request_not_found - visitor_not_found - too_many_requests - state_not_ready @@ -2255,9 +2389,6 @@ components: * `feature_not_enabled` - This feature (for example, Delete API) is not enabled for your workspace. - * `request_not_found` - The specified event ID was not found. It never - existed, expired, or it has been deleted. - * `visitor_not_found` - The specified visitor ID was not found. It never existed or it may have already been deleted. @@ -2390,3 +2521,12 @@ components: `ios` - Apple iOS based devices. `android` - Android based devices. + SearchEventsIncrementalIdentificationStatus: + type: string + enum: + - partially_completed + - completed + description: > + Filter events by their incremental identification status + (`incremental_identification_status` property). Non incremental + identification events are left out of the response. diff --git a/test/mocks/errors/400_visitor_id_required.json b/test/mocks/errors/400_visitor_id_required.json new file mode 100644 index 00000000..e144a892 --- /dev/null +++ b/test/mocks/errors/400_visitor_id_required.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "request_cannot_be_parsed", + "message": "visitor id is required" + } +} diff --git a/test/mocks/events/get_event_200.json b/test/mocks/events/get_event_200.json index 8985aa0e..9d6a5704 100644 --- a/test/mocks/events/get_event_200.json +++ b/test/mocks/events/get_event_200.json @@ -3,6 +3,7 @@ "tags": {}, "timestamp": 1708102555327, "event_id": "1708102555327.NLOjmg", + "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) ....", @@ -124,6 +125,8 @@ }, "incognito": false, "tampering": false, + "tampering_confidence": "high", + "tampering_ml_score": 0.3231, "tampering_details": { "anomaly_score": 0.1955, "anti_detect_browser": false @@ -131,9 +134,11 @@ "cloned_app": false, "factory_reset_timestamp": 0, "jailbroken": false, + "simulator": false, "frida": false, "privacy_settings": false, "virtual_machine": false, + "virtual_machine_ml_score": 0.2, "location_spoofing": false, "velocity": { "distinct_ip": { diff --git a/test/mocks/events/get_event_ruleset_200.json b/test/mocks/events/get_event_ruleset_200.json index b02bfb2d..6742b0d6 100644 --- a/test/mocks/events/get_event_ruleset_200.json +++ b/test/mocks/events/get_event_ruleset_200.json @@ -3,6 +3,7 @@ "tags": {}, "timestamp": 1708102555327, "event_id": "1708102555327.NLOjmg", + "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) ....", @@ -124,6 +125,8 @@ }, "incognito": false, "tampering": false, + "tampering_confidence": "high", + "tampering_ml_score": 0.3231, "tampering_details": { "anomaly_score": 0.1955, "anti_detect_browser": false @@ -131,9 +134,11 @@ "cloned_app": false, "factory_reset_timestamp": 0, "jailbroken": false, + "simulator": false, "frida": false, "privacy_settings": false, "virtual_machine": false, + "virtual_machine_ml_score": 0.2, "location_spoofing": false, "velocity": { "distinct_ip": { diff --git a/test/mocks/events/search/get_event_search_200.json b/test/mocks/events/search/get_event_search_200.json index 2affda77..a6b34e68 100644 --- a/test/mocks/events/search/get_event_search_200.json +++ b/test/mocks/events/search/get_event_search_200.json @@ -5,6 +5,7 @@ "tags": {}, "timestamp": 1708102555327, "event_id": "1708102555327.NLOjmg", + "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) ....", @@ -126,6 +127,8 @@ }, "incognito": false, "tampering": false, + "tampering_confidence": "high", + "tampering_ml_score": 0.3231, "tampering_details": { "anomaly_score": 0.1955, "anti_detect_browser": false @@ -133,9 +136,11 @@ "cloned_app": false, "factory_reset_timestamp": 0, "jailbroken": false, + "simulator": false, "frida": false, "privacy_settings": false, "virtual_machine": false, + "virtual_machine_ml_score": 0.2, "location_spoofing": false, "velocity": { "distinct_ip": { diff --git a/test/mocks/events/update_event_multiple_fields_request.json b/test/mocks/events/update_event_multiple_fields_request.json new file mode 100644 index 00000000..adcdb05f --- /dev/null +++ b/test/mocks/events/update_event_multiple_fields_request.json @@ -0,0 +1,7 @@ +{ + "linked_id": "some_username", + "tags": { + "my_tag": "some_value" + }, + "suspect": true +} diff --git a/test/mocks/events/update_event_one_field_request.json b/test/mocks/events/update_event_one_field_request.json new file mode 100644 index 00000000..e42988f5 --- /dev/null +++ b/test/mocks/events/update_event_one_field_request.json @@ -0,0 +1,3 @@ +{ + "linked_id": "some_username" +} diff --git a/test/test_fingerprint_api.py b/test/test_fingerprint_api.py index 59716d31..f78003b7 100644 --- a/test/test_fingerprint_api.py +++ b/test/test_fingerprint_api.py @@ -12,6 +12,10 @@ EventUpdate, ForbiddenException, NotFoundException, + SearchEventsBot, + SearchEventsIncrementalIdentificationStatus, + SearchEventsSdkPlatform, + SearchEventsVpnConfidence, TooManyRequestsException, __version__, ) @@ -322,6 +326,112 @@ def test_search_events(self) -> None: self.assertIsInstance(first_event, Event) self.assertEqual(first_event.event_id, '1708102555327.NLOjmg') + def test_search_events_all_params(self) -> None: + """Test case for search_events with all available parameters""" + api_params = { + 'limit': 1, + 'pagination_key': '1741187431959', + 'high_recall_id': 'testHighRecallId', + 'bot': SearchEventsBot.GOOD, + 'ip_address': '192.168.0.1/32', + 'asn': 'testAsn', + 'linked_id': 'some_id', + 'url': 'https://example.com/page', + 'bundle_id': 'com.example.bundleId', + 'package_name': 'com.example', + 'origin': 'https://example.com', + 'start': 1582299576511, + 'end': 1582299576513, + 'reverse': True, + 'suspect': False, + 'vpn': True, + 'virtual_machine': True, + 'tampering': True, + 'anti_detect_browser': True, + 'incognito': True, + 'privacy_settings': True, + 'jailbroken': True, + 'frida': True, + 'factory_reset': True, + 'cloned_app': True, + 'emulator': True, + 'root_apps': True, + 'vpn_confidence': SearchEventsVpnConfidence.MEDIUM, + 'min_suspect_score': 0.5, + 'developer_tools': True, + 'location_spoofing': True, + 'mitm_attack': True, + 'proxy': True, + 'sdk_version': 'testSdkVersion', + 'sdk_platform': SearchEventsSdkPlatform.JS, + 'environment': ['env1', 'env2'], + 'proximity_id': 'testProximityId', + 'total_hits': 10, + 'tor_node': True, + 'incremental_identification_status': ( + SearchEventsIncrementalIdentificationStatus.PARTIALLY_COMPLETED + ), + 'simulator': True, + } + # URL params use serialized values (enum.value, lowercase bool) in API definition order + url_params = { + 'limit': 1, + 'pagination_key': '1741187431959', + 'high_recall_id': 'testHighRecallId', + 'bot': 'good', + 'ip_address': '192.168.0.1/32', + 'asn': 'testAsn', + 'linked_id': 'some_id', + 'url': 'https://example.com/page', + 'bundle_id': 'com.example.bundleId', + 'package_name': 'com.example', + 'origin': 'https://example.com', + 'start': 1582299576511, + 'end': 1582299576513, + 'reverse': 'true', + 'suspect': 'false', + 'vpn': 'true', + 'virtual_machine': 'true', + 'tampering': 'true', + 'anti_detect_browser': 'true', + 'incognito': 'true', + 'privacy_settings': 'true', + 'jailbroken': 'true', + 'frida': 'true', + 'factory_reset': 'true', + 'cloned_app': 'true', + 'emulator': 'true', + 'root_apps': 'true', + 'vpn_confidence': 'medium', + 'min_suspect_score': 0.5, + 'developer_tools': 'true', + 'location_spoofing': 'true', + 'mitm_attack': 'true', + 'proxy': 'true', + 'sdk_version': 'testSdkVersion', + 'sdk_platform': 'js', + 'environment': ['env1', 'env2'], + 'proximity_id': 'testProximityId', + 'total_hits': 10, + 'tor_node': 'true', + 'incremental_identification_status': 'partially_completed', + 'simulator': 'true', + } + + mock_pool = MockPoolManager(self) + self.api.api_client.rest_client.pool_manager = mock_pool + mock_pool.expect_request( + 'GET', + TestFingerprintApi.get_search_events_path(url_params), + fields=[], + headers=self.request_headers, + preload_content=True, + timeout=None, + response_data_file='events/search/get_event_search_200.json', + ) + event_response = self.api.search_events(**api_params) + self.assertIsInstance(event_response, EventSearch) + def test_search_events_bad_request(self) -> None: """Test case for search_events with 400 Bad Request response""" params = {'limit': 99}