Skip to content

Configuration Options

This page documents shared configuration options for both Client to Server and Server to Server integration methods.

Storage Types

The storageType option controls how DeviceAssure caches responses to prevent redundant API calls.

local-storage (default)

DeviceAssure.load({
  licence: '<LICENCE_KEY>',
  storageType: 'local-storage'  // This is the default
});

Uses browser localStorage to cache responses. Stores a JSON string containing the expiry time and response data. The cache persists across browser sessions until it expires or is cleared.

DeviceAssure.load({
  licence: '<LICENCE_KEY>',
  storageType: 'cookie'
});

Uses browser cookies to cache responses. The cookie's expiration time determines when a fresh API call is made.

none

DeviceAssure.load({
  licence: '<LICENCE_KEY>',
  storageType: 'none'
});

Disables caching entirely. Every call to DeviceAssure.load() triggers a fresh API request.

Recommended when:

  • Using IMEI validation (different IMEIs need different results)
  • You need real-time validation on every user action
  • Using Server to Server mode (caching is your server's responsibility)

Note: Using none does not clear existing cache - it simply ignores it.

Cache Expiry

The storageExpiry option sets how long cached responses remain valid.

DeviceAssure.load({
  licence: '<LICENCE_KEY>',
  storageType: 'local-storage',
  storageExpiry: 8 * 60 * 60 * 1000  // 8 hours in milliseconds
});
Value Duration
1800000 30 minutes (default)
3600000 1 hour
86400000 24 hours (maximum)

Once the cache expires, the next call to DeviceAssure.load() will make a fresh API request.

Request Timeout

The requestTimeout option sets how long, in milliseconds, to wait for each request to the DeviceAssure service before giving up on it.

DeviceAssure.load({
  licence: '<LICENCE_KEY>',
  requestTimeout: 5000  // 5 seconds
});

When a request times out, the next URL in the failover list is tried. Once every URL has been tried, onError is called with timeout: true.

The default is 10000 (10 seconds). The minimum is 1 second and the maximum is 60 seconds. Values outside this range, or values that are not numbers, are ignored and the default of 10000 is used instead.

Custom Tags

Tags allow you to attach custom metadata to API requests. This metadata is returned in the response under the meta field.

DeviceAssure.load({
  licence: '<LICENCE_KEY>',
  tags: [
    { key: 'page', value: 'checkout' },
    { key: 'user-type', value: 'premium' },
    { key: 'session-id', value: 'abc123' }
  ]
});

Constraints:

  • Maximum key length: 64 characters
  • Maximum value length: 128 characters
  • Both key and value must be strings

Use cases:

  • Tracking which page triggered validation
  • Correlating validations with user sessions
  • Adding business context to validation results

Note: Custom tag data is NOT stored by DeviceAtlas and is not available for subsequent data retrieval or analysis.

IMEI Corroboration

The imei option enables IMEI corroboration, which validates alignment between the IMEI and device characteristics. This feature can also check if a device has been reported lost or stolen via the GSMA Device Check service.

Note: This feature requires a licence with IMEI enabled. Contact support@deviceassure.com for details.

Configuration

DeviceAssure.load({
  licence: '<LICENCE_KEY>',
  imei: '123456789012345',
  storageType: 'none'  // Recommended with IMEI
});

Requirements

  • Licence must have IMEI feature enabled
  • IMEI must be a non-empty string
  • Leading/trailing whitespace is automatically trimmed

Best Practices

  • Always use storageType: 'none' when validating IMEIs
  • Handle the onError callback for IMEI validation errors

Error Messages

Client to Server: 

{ "message": "IMEI is not present, please enable it in config. API request not sent." }

Server to Server: 

{ "message": "IMEI is not present, please provide an IMEI." }

Note: IMEI corroboration and IMEI Format Validation are separate features. Corroboration is performed by the DeviceAssure backend and needs a licence with IMEI enabled. Format validation runs in the browser, needs no licence, and only checks that the value could be an IMEI at all.

IMEI Format Validation

An IMEI carries a check digit, so a mistyped or made up value can be rejected before a request is ever sent.

The validateIMEIFormat option has the library validate the imei it was given. When the IMEI fails, no request is made and an error is raised. When it passes, the request proceeds as normal and the API is told the check was run.

Note: This is a client-side check and requires no licence. It confirms only that the value is a well formed IMEI, not that it belongs to the device. For that, see IMEI Corroboration.

Configuration

DeviceAssure.load({
  licence: '<LICENCE_KEY>',
  imei: '<IMEI>',
  validateIMEIFormat: true,
  storageType: 'none',
  onSuccess: function(response) {},
  onError: function(error) {
    // error.message is one of the messages listed below
  }
});

The failure is delivered to the onError callback when one is configured, and thrown when one is not.

Requirements

  • Only a 15 digit IMEI is accepted. It is the only form carrying a check digit, so it is the only one the checksum can verify. A 16 digit IMEISV gives that position over to the software version number.
  • Leading and trailing whitespace is trimmed before the check, so the value validated is the value that goes on the wire.

Error Messages

Message Cause
IMEI is not a string. The value is not a string.
IMEI is not present, please provide one. The value is empty or is all whitespace.
IMEI must contain digits only. The value holds letters, whitespace or special characters.
IMEI must be 15 digits. The value is not 15 digits long.
Invalid IMEI format The check digit does not add up.

On the Request

When the check has run and passed, data.telephony.validateIMEIFormat is set to passed on the request, so the API can tell a verified IMEI from an unverified one. A failing IMEI never reaches the API, because the request is blocked in the browser.

Validating Without a Request

The same check is available as a standalone method, for validating a form field before anything is submitted. See DeviceAssure.validateIMEIFormat().

Note that the standalone method validates the value exactly as it is given, so whitespace is a failure there, where the validateIMEIFormat option trims it first.

QR Codes

DeviceAssure.qr() accepts the same option. Because qr takes its whole configuration on each call, the flag must be passed to qr directly and is not inherited from a previous load. A failing IMEI generates no QR code, and the reason arrives through the qr callback rather than onError. See QR Code Configuration Options.

See Also