Web SDK Reference
Setup
- For a guide on setting up the camera, see Web Integration Guide
- For release notes, see Web Release Notes
Script Import
The Web SDK is bundled as a JavaScript module that includes everything, from the camera to the CSS, in a single import. It’s hosted by Truepic on our CDN for speed and convenience, and is evergreen with updates rolling out automatically, without any code redeployment on your end.
<script type="module">
import useLensCamera from 'https://lens-sdk.truepic.com/lens_camera.es.js'
</script>useLensCamera()
useLensCamera(config)The main entrypoint that initializes the SDK and appends a hidden
<lens-camera> web component to the <body> of the page.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
config | object | Configuration options to initialize the SDK and <lens-camera> web 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. |
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. |
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()
close()Close the camera and stop accessing the user’s location, camera, and microphone (video mode only).
Parameters
None
Returns
undefined
getUploadCounts()
getUploadCounts()Get the number of captures in the various states of being uploaded.
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. |
hasUploadPending()
hasUploadPending()Whether there are any captures being uploaded.
Parameters
None
Returns
boolean
open()
open((options = {}))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 (video mode only) if they haven’t previously granted access (each browser does this differently).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
options | object | Configuration options to open the camera with. | {} |
↳ 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 |
↳ 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()
remove()Close (if open) and remove the <lens-camera> web component from the page.
Parameters
None
Returns
undefined
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. |
closed
Fired when close has completed successfully.
Detail
None
error
Fired when an error occurs that may be useful to your integration. See Error Objects 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. |
Capture Object
The data model for a photo or video capture.
Properties
| Name | Type | Description |
|---|---|---|
blob | Blob | The raw, binary JPEG photo or MP4 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. |
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. |
type | TYPES constant | The type of capture. |
Constants
| Name | Type | Description |
|---|---|---|
TYPES | object | The type of capture. |
↳ PHOTO | string | A photo taken. |
↳ VIDEO | string | A video recorded. |
Methods
hashBlob()
async hashBlob()The SHA-256, base-64 encoded hash of the blob returned by a capture.
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.
isPhoto()
isPhoto()Whether the capture is a photo.
Parameters
None
Returns
boolean
isVideo()
isVideo()Whether the capture is a video.
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 |
|---|---|---|
code | integer | The CODES constant that specifically identifies the error. |
originalError | Error | The underlying, original error that prompted this error. |
See additional inherited properties from
Error
Constants
| Name | Type | Description |
|---|---|---|
CODES | object | Identifiers for each specific error. |
See additional inherited constants from
Error
Methods
None. See inherited methods from
Error.
LensUploadError
The error when a capture fails to be uploaded and cannot be retried. Extends and
inherits from LensError.
Properties
None. See inherited properties from LensError.
Constants
| Name | Type | Description |
|---|---|---|
CODES | object | Identifiers for each specific error. |
↳ NOTIFY_REQUEST_FAILED | integer | The initial request failed to notify the Lens API that a capture is pending upload. |
↳ UPLOAD_REQUEST_FAILED | integer | The upload request failed to the Lens API. |
See additional inherited constants from LensError
Methods
None. See inherited methods from LensError.