Lens Web SDK

While native apps enable powerful experiences, communicating with your customers on the web remains the most convenient, efficient way to do business. Lens helps you collect Truepics across mobile platforms, wherever your users take photos and videos.

In this guide, we'll show you how to get started by walking you through a simple integration of Lens for mobile web browsers, a JavaScript library that captures signed images out of the box. We've made things easy by including a pre-built camera component and automatically uploading photos to the Lens API for verification and processing.

Requirements

For Developers

License key scoped to your web app's origin(s)
These are the scheme, hostnames, and/or ports that will be making the request to Truepic from your app's environment (test/development or production). Only allowed origins will be able to load the Javascript library. Wildcards are allowed for subdomains. You may provide as many urls as needed.

Device & Browser Support

Device	Support
Apple iPhones and iPads	iOS Safari and Chrome 14+ 14.3+ within a `UIWebView` or `WKWebView`
Android-based smartphones and tablets (e.g. Galaxy Tablet)	Android Chrome 87+

Device

Support

Apple iPhones and iPads

iOS Safari and Chrome 14+

14.3+ within a UIWebView or WKWebView

Android-based smartphones and tablets
(e.g. Galaxy Tablet)

Android Chrome 87+

Not supported:

Other browsers for any supported device
Microsoft Surface tablet
Amazon Fire tablet
Laptop and desktop devices

Getting Started

First, let's set the stage with a simple, bare-bones HTML page that we can flesh out as we move forward:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Lens Web SDK Integration Guide</title>
  </head>
  <body>
    <!-- Body -->
  </body>
  <!-- Script -->
</html>

To keep from repeating this code over and over, as we flesh out the details in each step, we'll simply reference the name of the section (like) where the code in question is to live.

Import the Script

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.

If you're unfamiliar with JavaScript modules, this may look a little different than the typical <script> tag that you're used to. As a third-party vendor on your page, we chose to deploy our library as a module to take advantage of more recent JavaScript best practices. Modules aren't exposed globally, so useLensCamera() (as you'll soon learn about) will be undefined outside of the <script> tag where it's imported. Modules load deferred and should result in fewer collisions on the page. Read through the previously linked MDN guide to learn more.

Let's start by adding it to our HTML page:

<!-- Script -->
<script type="module">
  import useLensCamera from 'https://lens-sdk.truepic.com/lens_camera.es.js'

  // More to come...
</script>

We're adding the script to the end of the <body> here, but it can also be put in the <head> or anywhere else.

Instantiate the Camera

Now that the script is imported, we have access to the useLensCamera()function. If you're familiar with hooks in React or Composables in Vue.js,useLensCamera() follows the same pattern to encapsulate the logic to set up and orchestrate the Lens camera, and it works whether you're using a component-based framework or vanilla JavaScript.

Let's call it in vanilla JavaScript:

<!-- Script -->
<script type="module">
  // Picking up from where we left off...

  const camera = useLensCamera({
    // Replace with your real API key:
    apiKey: 'cTrvjmhDN2qlS43akO/1XnWQ/pL7dF9CyKOKoc1zZ6/Xzw/rE/mPEbjhFstJYiss',
    // Replace with your app's version from package.json or elsewhere:
    appVersion: '0.1.0',
  })

  // More to come...
</script>

Under the hood, useLensCamera() initializes the SDK and appends a hidden <lens-camera> web component to the <body> of our HTML to house the camera. As we'll see next, the returned value (camera) is the instance of the web component that provides an API to programmatically orchestrate the camera.

Open the Camera

The script is imported, the camera is set up, but nothing is visible on the page yet — that's expected! We have to tell the camera to open to make the web component visible to the user. This can be done automatically (like on page load) or as the result of some user interaction, such as clicking a button, which is the method we'll use.

Let's add a button to our HTML page:

<!-- Body -->
<button id="open-camera">Open Camera</button>

Then listen for a click to open the camera:

<!-- Script -->
<script type="module">
  // Picking up from where we left off...

  const openCamera = document.getElementById('open-camera')

  openCamera.addEventListener(
    'click',
    () => {
      camera.open()
    },
    false
  )

  // More to come...
</script>

That's it. When the user clicks the button, the camera will overlay the page, taking up the whole viewport, and allow the user to begin capturing photos and videos that will be automatically uploaded to the Lens API for verification and
processing.

The camera includes a close button to return to your app, but you can also do this programmatically by calling camera.close().

Listen for Events (Optional)

The last piece of code we're going to add is optional, but will give you a sense of how the camera can be orchestrated to fit your desired experience.

In addition to functions like open() and close() that can be called programmatically, the web component also emits events when certain actions happen within the camera. For example, let's add a simple listener that logs to the console when a photo or video is captured:

<!-- Script -->
<script type="module">
  // Picking up from where we left off...

  camera.addEventListener(camera.constructor.EVENTS.CAPTURE, (event) => {
    console.log(event)
  })
</script>

If you inspect the event in the console, you'll see that event.details.capture is a Capture object that includes details about the capture. You could, for example, use the blob to display a preview of the capture back to the user for confirmation, or as a thumbnail in a list of captures taken. The possibilities are endless!