Troubleshooting and FAQs

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 permissions or platform support.	Check if permissions (e.g., location) were denied. Note OS/browser restrictions. Some computed fields (e.g., `isVirtualMachine`) may be indeterminate.
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.

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.

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 browsers and OS versions limit available device attributes.
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

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.