Digital Intelligence Troubleshooting & FAQs

Learn how to test, debug, and optimize your integration using Socure Digital Intelligence in RiskOS™.

Common errors

The table below outlines common errors that may occur when integrating Digital Intelligence. These issues can result from SDK initialization problems, environment mismatches, permission denials, or platform restrictions. Understanding these patterns can help you fine-tune your workflows, reduce false negatives, and determine when escalation or fallback logic is appropriate.

Issue	Explanation	Suggested fix
SDK does not return a `sessionToken`	The token is only issued once device data has been captured and uploaded.	Ensure correct SDK key is used. Wait for async handlers to complete. Check error callbacks. Review network/firewall settings to allow Socure backend calls.
API call returns no Digital Intelligence data	Using the wrong type of key or environment mismatch can prevent results.	Use an API key (not SDK key) for server calls. Verify environment (sandbox vs production).
Missing field in response	Some fields depend on the SDK platform, user permissions, or input data provided in the request.	Check the Data Dictionary platform availability section — many fields are platform-specific and return `null` on non-matching platforms. Verify permissions (for example, location). For velocity metrics, confirm the required PII fields are included in the request. See the SDK FAQs for detailed explanations.
Unexpected value in response	SDK reports values as observed by backend without modification.	This is expected. Use anomalies (e.g., injected or manipulated values) as potential risk signals.
Evaluation rejected with device-velocity tags (for example, Risky Device or Device Velocity or Daily Applications per Device is Risky)	Repeated evaluations from the same device build up device velocity, which can trip workflow rules that reject high-velocity devices. Common when testing repeatedly from one machine in sandbox or staging.	Expected behavior when many applications share one device. See the device velocity question in the FAQs.

How to debug

To debug Digital Intelligence behavior in RiskOS™:

Use the eval_id to trace execution in the Developer Console or RiskOS™ logs.
Check the status_code in each data_enrichments[] block (200 indicates success).
Validate that the Digital Intelligence enrichment module was triggered.
Review device, behavioral, and entity profiler outputs for anomalies or missing values.
Check SDK error callbacks on the client for initialization or permission errors.

Fallback strategies

If Digital Intelligence does not yield expected results:

Retry once SDK completes capture. Wait for async completion handlers.
Validate keys and environments. Confirm correct API vs SDK keys and sandbox vs production.
Handle missing signals gracefully. If certain fields are absent (permissions, platform limits), do not block the workflow — instead, rely on other signals.
Escalate to review. Use tags or review_queues in RiskOS™ to route inconclusive sessions for human analysis.

Error codes

If an error occurs while retrieving or processing the device session data, the Digital Intelligence enrichment response includes a digitalIntelligenceErrors array alongside the digitalIntelligence object. Each entry contains a code and a message. When this array is present, the digitalIntelligence object may be absent or incomplete.

Code	Message	Description
`DI_ERR_001`	Device session not found	The provided session ID does not exist.
`DI_ERR_002`	Device session ID not provided	The `deviceSessionId` field was not included in the request.
`DI_ERR_003`	Invalid device session token	The session token format is invalid or could not be decoded.
`DI_ERR_004`	Authorization failed	Authorization to the device service failed.
`DI_ERR_005`	Device record not processable	The device record could not be processed.
`DI_ERR_006`	Internal processing error	An unexpected error occurred during processing.

Escalation path

For production-impacting issues or debugging edge cases:

Reproduce the issue. Do this in the sandbox or staging environment if possible.
Capture relevant identifiers. Collect:
- eval_id
- Full request payload
- referenceId from the Digital Intelligence enrichment
Open a support ticket. Contact Socure Support or your Technical Account Manager (TAM) and include:
- Workflow name
- Input fields submitted
- Expected vs actual decision
- Logs or screenshots (if applicable)
Urgent escalation. For high-severity cases, escalate via:
- Slack (if integrated)
- Your designated Socure escalation channel

Known limitations

Permission-dependent signals. Certain fields (e.g., location) require explicit user permission.
Platform restrictions. Some fields are only available on specific platforms (iOS, Android, or Web) due to differences in OS-level APIs and browser capabilities. See the Data Dictionary platform availability section for a complete breakdown, and the SDK FAQs for explanations of why specific fields vary across platforms.
Indeterminate computed values. Certain flags (e.g., isVirtualMachine) are only populated when a definitive determination can be made.
Observed values only. Digital Intelligence reports exactly what the SDK/backend detects — anomalies may represent tampering or malicious injection attempts.

📘
Note:
Use the Developer Console to view raw request/response logs in real time for debugging or validation.

FAQs

General product behavior

Why are my evaluations rejected with device-velocity tags during repeated testing?

When the Digital Intelligence enrichment runs, RiskOS™ records device velocity metrics: the unique PII elements (email, phone number, first name, last name) and the volume of applications seen with a device over a rolling 90-day window. Workflows can include rules that reject or flag a device when this velocity is high. These rules surface as workflow tags such as Risky Device or Device Velocity or Daily Applications per Device is Risky.

If you test repeatedly from the same device — for example, submitting many evaluations or Advanced Prefill requests from one laptop in sandbox or staging — that device accumulates velocity history. Once it crosses the workflow's threshold, the system rejects every subsequent evaluation from that device. The decision is working as designed: from the platform's perspective, a single device is driving an unusually high number of applications.

Can I reset a device's velocity? There is no self-service way to reset device velocity or clear the applications associated with a device. Velocity is derived from historical transactions over a rolling 90-day window, so a device's history ages out on its own as older transactions fall outside the window.

To keep testing without waiting for the window to roll forward:

Test from a different device. A different physical device generates a new device session with no velocity history. Switching browser profiles or using incognito mode on the same machine may not fully reset velocity, because device identity can persist across browsers through the cross-client GlobalDeviceID (device.globalDeviceId).
Use sandbox test scenarios. For functional testing, use the documented Device Risk sandbox deviceSessionId values, which return deterministic responses without building up real velocity.
Adjust the workflow for testing. If you manage the staging workflow, temporarily raise or disable the device-velocity rule while you test, then restore it before promoting the workflow.
Contact Socure. If you need a device's accumulated test data cleared, contact Socure Support or your Technical Account Manager (TAM). Include the eval_id and the device identifiers from a rejected evaluation.

Where did the fingerprint() method on iOS and Android go?

With the introduction of Digital Intelligence, customers no longer need to explicitly fingerprint the device.

Use the initializeSDK() method at app launch. The SDK will automatically fingerprint the device and generate a sessionToken, which can be retrieved via getSessionToken(). There is no need to call fingerprint() directly.

What if I need an explicit fingerprint() call on iOS or Android?

Most use cases don’t require forcing a fingerprint. However, the Digital Intelligence SDK provides a processDevice() method to trigger device data collection for specific contexts (e.g., login, signup, checkout).

What happened to the Base64 session id provided by Device Risk?

Digital Intelligence replaces the session id with sessionToken, a JWT used in subsequent API calls and RiskOS™ enrichments.

How can I implement a Reverse Proxy when using the Web SDK?

Socure supports Reverse Proxy implementations. Configure configBaseUrl when accessing the SDK through a proxy. Contact your Solutions Consultant team for details.

Does the Web SDK provide Canonical Name (CNAME) support?

No. CNAME support was dropped with the introduction of Digital Intelligence. Using CNAME is not recommended with the Web SDK.

How can I provide a context when configuring the Web SDK?

Context support has been deprecated. An alternative will be provided in a future release.

What will happen to Device Risk?

Starting July 31, 2024, support for Device Risk will be limited. No new features will be added. Customers should migrate to Digital Intelligence.

What is the device.globalDeviceId field in the API response? How is it different from the device.id field?

GlobalDeviceID (device.globalDeviceId) is the primary device node in the Identity Graph linking to our persistent view of identity, SocureID. As we continue to enhance Digital Intelligence capabilities, GlobalDeviceID is our cross-client view of device helping us link and secure every touch point in the consumer journey.

The legacy device ID (device.id) is client-specific and remains in the Digital Intelligence response for backward compatibility.

Integration and SDK usage

What platforms does the SDK support?

Digital Intelligence supports Web Native (JavaScript library and npm package), iOS, Android, and React Native.

How do I install and initialize the SDK?

Full setup instructions are available in the developer documentation. Initialization requires calling initializeSDK() at app launch.

Does the SDK require a key or authentication?

Yes. An SDK key is required for integration. SDK keys can be provisioned and managed in the Authentication Guide (make sure you select the SDK Key tab).

What types of device and behavioral data does the SDK collect?

The SDK automatically collects a wide range of device and behavioral signals. All collected data is available via the sessionToken through the RiskOS™ Evaluation API. See the Data Dictionary for full field breakdown.

Can I control or limit the data collected?

Data collection cannot generally be disabled once the SDK is initialized. Exceptions include:

Location data – Use omitLocationData (iOS/Android) to disable location capture. By default, only low-precision (2 decimal places) is collected. Higher precision can be enabled on request.
Behavioral data – Use pauseDataCollection() to stop capture and resumeDataCollection() to restart.

Are there performance implications with integrating the SDK?

The SDK is designed to be lightweight. Most computation happens on background threads, and data is flushed at intervals. It should not cause noticeable latency.

Does the SDK require explicit permissions?

No. The SDK does not directly prompt for permissions. It relies on your app to request them. Data will only be collected if permissions are granted.

Can we exchange the sessionToken between sub-accounts?

Yes. Digital Intelligence sessions are accessible for all accounts within the same account hierarchy.

Updated 22 days ago

Did this page help you?