Web SDK Integration
Introduction
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 our Lens Web SDK, a JavaScript library that works 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
- API key scoped to your web app’s origin
Browser Support
- Android Chrome 87+
- iOS Safari/Chrome 14+
- 14.3+ within a
UIWebVieworWKWebView
- 14.3+ within a
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
<!-- Script -->) 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!
Wrapping Up
We hope the code and concepts we’ve walked through give you the confidence and understanding to translate into whatever frontend framework you’re using – whether that’s React, Vue.js, or something else entirely. We’re always happy to help with any hurdles or questions along the way! In the meantime, head over to the Web Reference for a complete rundown of the SDK.
Next, head to the API integration guide to learn how to receive processed captures via webhook.