Lens Web SDK Reference
Additional functionality and reference for the JavaScript client-side API
Setup
See the integration guide for a full walkthrough of setting up the capture library.
Initialize the library
The main entry point that initializes the SDK and appends a hidden <lens-camera>web component to the <body> of the page.
METHOD
useLensCamera(config)
PARAMETERS
| Name | Type | Description | Default |
|---|---|---|---|
config | object | Configuration options to initialize the SDK and camera component with. | |
↳ apiKey | string | The API key issued by the Truepic team for your Web SDK integration. | |
↳ appVersion | string | The version of your web app from your package.json or elsewhere. | |
↳ storeCaptures | boolean | Whether to store all captures in the browser for reference indefinitely, not just during the period of pending and active upload. | false |
RETURNS
The <lens-camera> web component instance. If called more than once, the same instance is returned, as only one can exist on the page.
Camera Component
The <lens-camera> web component displays the camera and provides a client-side JavaScript API to programmatically orchestrate it. Creation is handled by useLensCamera() and should not be done manually.
Constants
| Name | Type | Description |
|---|---|---|
EVENTS | object | The various event types |
↳ CAPTURE | string | The capture event type. |
↳ CLOSED | string | The closed event type. |
↳ ERROR | string | The error event type. |
↳ OPENED | string | The opened event type. |
↳ UPLOADED | string | The uploaded event type. |
↳ UPLOADING | string | The uploading event type. |
FACING | object | The front or back camera to use based on the direction it's facing. |
↳ENVIRONMENT | string | The back camera facing the environment. |
↳ USER | string | The front camera facing the user. |
LOCATION | object | Options for whether to prompt the user for location permission and require it for capture. |
↳ REQUIRED | boolean | Prompt the user for location permission and only allow capture if permitted. |
↳ OPTIONAL | string | Prompt the user for location permission. If denied, capture is still allowed, but location is not recorded. |
↳ NEVER | boolean | Never prompt the user for location permission and do not record it even if previously permitted. |
MODES | object | The capture mode to use, either photo or video. |
↳ PHOTO | string | The capture mode to take a photo. |
↳ VIDEO | string | The capture mode to record a video. |
VERSION | string | The version of the SDK that's currently in use. |
Methods
Close the camera
Close the camera and stop accessing the user's location, camera, and microphone (in video mode).
METHOD
close()
PARAMETERS
None
RETURNS
undefined
Delete all captures
Delete all captures being stored in the browser. If a capture is being actively uploaded, the request will be aborted.
If the storeCaptures config option is set to false, only pending and active uploads will be deleted, as captures are only stored during that period. If set to true, all captures being stored in the browser will be deleted.
METHOD
async deleteAllCaptures()
PARAMETERS
None
RETURNS
A promise that resolves in a boolean
Delete a capture
Delete a capture being stored in the browser. If the capture is being actively uploaded, the request will be aborted.
If the storeCaptures config option is set to false, only pending and active uploads can be deleted, as captures are only stored during that period. If set to true, any capture being stored in the browser can be deleted.
METHOD
async deleteCapture(capture)
PARAMETERS
| Name | Type | Description |
|---|---|---|
capture | Capture Object or id string | The capture to delete. |
RETURNS
A promise that resolves in a boolean
Check browser support
Check whether the current browser (user agent) is supported.
METHOD
isUserAgentSupported()
PARAMETERS
None
RETURNS
boolean
Count captures uploaded
Get the number of captures in the various states of being uploaded.
METHOD
getUploadCounts()
PARAMETERS
None
RETURNS
object
| Name | Type | Description |
|---|---|---|
waiting | number | The number of captures waiting to be uploaded. |
active | number | The number of captures in the process of being uploaded. |
total | number | The total number of uploads both waiting and active. |
Check if there are pending uploads
Check whether there are any captures being uploaded.
METHOD
hasUploadPending()
PARAMETERS
None
RETURNS
boolean
Open the camera
Open the camera and start the initialization process to begin taking captures. The browser will prompt the user for access to their location, camera, and microphone (in video mode) if they haven't previously granted access (each browser does this differently).
METHOD
open(options = {})
PARAMETERS
| Name | Type | Description | Default |
|---|---|---|---|
options | object | Configuration options to open the camera with. | {} |
↳ allowModeChange | boolean | Whether to allow the user to change the mode from photo or video in the camera. | true |
↳ customData | object | Custom data to associate with each capture, such as an identifier to connect the captures to after processing. Any JSON-encodable values are allowed. | null |
↳ facing | FACING constant | The front or back camera to use based on the direction it's facing. | FACING.ENVIRONMENT |
↳ location | LOCATION constant, object | Whether to prompt the user for location permission and require it for capture. Use the object syntax to configure additional location-related options. | LOCATION.REQUIRED |
↳↳ enabled | boolean | Whether to prompt the user for location permission. true is equivalent to setting LOCATION.REQUIRED as the top-level location value, while false is equivalent to LOCATION.NEVER. | true |
↳↳ required | boolean | Whether to require location permission in order to allow capture. false is equivalent to setting LOCATION.OPTIONAL as the top-level location value. | true |
↳↳ requirePrecise | boolean | Whether to require precise location permission in order to allow capture. If false, approximate location permission is allowed, which typically results in an accuracy of greater than 1,500 meters. | true |
↳↳ preciseAccuracyMax | number | When precise location is required, the maximum number of meters allowed for accuracy. The default of 1,500 meters is about 1 mile. Anything larger is considered approximate, so it should only be set to a lower number to require a more precise reading. | 1500 |
↳ mode | MODES constant | The capture mode to open the camera in, either photo or video. | MODES.PHOTO |
↳ processOptions | object | Options to configure how each capture should be processed by the API. See the API reference for a complete list of options. | null |
RETURNS
undefined
Remove the component
Close (if open) and remove the <lens-camera> web component from the page.
METHOD
remove()
PARAMETERS
None
RETURNS
undefined
Retry upload
Re-enqueue a capture that has failed to be uploaded after 25 attempts. The status of the capture must be ERROR, otherwise a LensUploadError is thrown.
METHOD
async retryUpload(capture)
PARAMETERS
| Name | Type | Description |
|---|---|---|
capture | Capture Object or id string | The capture to re-enqueue for upload. |
RETURNS
A promise that resolves in a boolean
Move or remove the upload indicator
This method allows you to move or remove the upload indicator from the default position of the top right (portrait) or bottom left (landscape) of the screen. If moving, simply add the returned element to the DOM in the desired location and position as necessary.
METHOD
useExternalUploadIndicator()
PARAMETERS
None
RETURNS
<lens-camera-upload-indicator>
Events
An event is an instance of CustomEvent with a detail property that contains the custom data documented for each type below. For convenience, the EVENTS constants can be used to reference a type when adding or removing a listener.
capture
Fired when a photo or video has been captured successfully.
DETAIL
| Name | Type | Description |
|---|---|---|
capture | Capture Object | The data model for the capture. |
captures-loaded
Fired when the captures stored in the browser have been loaded.
If the storeCaptures config option is set to false, only pending uploads will be loaded, as captures are only stored during that period. If set to true, all captures being stored in the browser will be loaded.
DETAIL
| Name | Type | Description |
|---|---|---|
captures | array(Capture Object) | The data models for the captures. |
closed
Fired when close has completed successfully.
DETAIL
None
error
Fired when an error occurs that may be useful to your integration. See LensError Object for more details.
DETAIL
| Name | Type | Description |
|---|---|---|
capture | Capture Object | The data model for the capture. |
error | LensError Object | The error that occurred. |
opened
Fired when open has completed successfully.
DETAIL
None
uploaded
Fired when a capture has been successfully uploaded to the Lens API for
verification and processing.
DETAIL
| Name | Type | Description |
|---|---|---|
capture | Capture Object | The data model for the capture. |
uploading
Fired when a capture starts uploading to the Lens API for verification and
processing.
DETAIL
| Name | Type | Description |
|---|---|---|
capture | Capture Object | The data model for the capture. |
Style Customizations
The look and feel of the camera can be customized through the use of CSS variables. These can be set on the :root pseudo-class or lens-camera element.
| Name | Description |
|---|---|
--lens-camera-font-family | The custom font family to use for text throughout the camera. As with the standard font-family property, a comma-separated list of fallbacks is supported. |
Example
:root {
--lens-camera-font-family: 'Roboto Slab Variable', serif;
}Capture Object
The data model for a photo or video capture.
Properties
| Name | Type | Description |
|---|---|---|
blob | blob | The raw, binary JPEG photo or MPEG-4 video. |
capturedAt | string (date-time) | The date/time of capture. |
customData | object | Custom data associated with the capture, such as an identifier to connect the capture to after processing. |
id | string | A unique, randomly generated identifier for the capture while in the browser. It is not the id found in the record object that's assigned by the Lens API when uploaded. |
duration | integer | If video, the duration in seconds. |
posterBlob | blob | If video, the first frame as a raw, binary JPEG for use as the poster or preview. |
processOptions | object | Options to configure how the capture should be processed by the API. |
record | object | The latest capture record from the Lens API. Only set after uploading. |
status | STATUSES constant | The current status of the capture. |
type | TYPES constant | The type of capture. |
Constants
| Name | Type | Description |
|---|---|---|
STATUSES | object | The status of the capture. |
↳ NEW | string | The capture has started. |
↳ READY | string | The capture has been completed and is ready for upload. |
↳ NOTIFYING | string | The Lens API is being notified that the capture is pending upload. |
↳ NOTIFIED | string | The Lens API has been notified that the capture is pending upload. |
↳ UPLOADING | string | The capture is being uploaded to the Lens API. |
↳ UPLOADED | string | The capture has been uploaded to the Lens API. |
↳ ERROR | string | The capture has failed to be uploaded to the Lens API. |
TYPES | object | The type of capture. |
↳ PHOTO | string | A photo taken. |
↳ VIDEO | string | A video recorded. |
Methods
Hash blob
The SHA-256, base-64 encoded hash of the blob returned by a capture.
METHOD
async hashBlob()
PARAMETERS
None
RETURNS
A promise that resolves with the SHA-256, base-64 encoded hash, or undefined if there is no blob. The promise is rejected if an error occurs.
Is photo
Whether the capture is a photo.
METHOD
isPhoto()
PARAMETERS
None
RETURNS
boolean
Is video
Whether the capture is a video.
METHOD
isVideo()
PARAMETERS
None
RETURNS
boolean
Error Objects
The <lens-camera> web component gracefully handles and displays all errors produced by the Web SDK. However, when an error may be useful to your integration as well, it's propagated through the error event. Listening to this event is completely optional and only necessary for more in-depth integrations.
To check for a specific type of error, the error classes can be imported by name and compared against using instanceof:
import { LensUploadError } from 'https://lens-sdk.truepic.com/lens_camera.es.js'
// ...
if (error instanceof LensUploadError) {
// Handle this type of error specifically...
}LensError
The base class that all Web SDK errors extend and inherit from. Extends and inherits from the global Error object itself.
Properties
| Name | Type | Description |
|---|---|---|
cause | Error | The underlying error that caused this error. |
code | integer | The CODES constant that specifically identifies the error. |
details | object | Additional context that can be helpful in understanding the error. |
originalError | Error | Deprecated in favor of cause. |
See additional inherited properties from Error ↗.
Constants
| Name | Type | Description |
|---|---|---|
CODES | object | Identifiers for each specific error. |
See additional inherited constants from Error ↗.
Methods
Serialize to JSON
Serialize the error to an object that can be passed to JSON.serialize().
METHOD
toJSON()
PARAMETERS
None
RETURNS
object
See additional inherited methods from Error ↗.
Subclasses
The following classes extend and inherit from LensError.
LensAPIError
The error when a request to the Lens API fails or responds with an error.
LensCaptureError
The error when a capture-related operation fails.
LensEnrollmentError
The error when an enrollment-related operation fails.
LensGeolocationError
The error when a geolocation-related operation fails.
LensStreamError
The error when a media stream-related operation fails.
LensUploadError
The error when a capture upload-related operation fails.
LensUserAgentError
The error when the user agent (browser) is unsupported.
Updated about 1 year ago