Guides
JavaScript SDK
You can use our JavaScript SDK to:
- Encrypt data client-side
- Collect or display senitive data with UI Components
Quickstart
Installation
Our JavaScript SDK is distributed from our CDN, and can be installed just by placing this script tag before the closing </body>
tag in your HTML.
Once installed, initialize the JavaScript SDK with your Team and App ID found in the Evervault Dashboard.
Encrypt a string
Now that the SDK is initialized, we can encrypt a string.
Full example
Pulling all of this together leaves us with the following working example. You can copy and paste the code below (using your own Team ID and App ID), run it in your own environment and run the encryption and decryption for yourself.
Reference
window.Evervault(appId, teamId)
The SDK constructor accepts two parameters:
- Your Team ID
- Your App ID
Parameters
The ID of your Evervault team. This can be found inside of your team settings on the Evervault dashboard.
The ID of your Evervault app. This can be found inside of your app settings on the Evervault dashboard.
window.Evervault.init(appId, teamId)
The init
method allows for async initialization of the SDK, it accepts two parameters:
- Your Team ID
- Your App ID
Parameters
The ID of your Evervault team. This can be found inside of your team settings on the Evervault dashboard.
The ID of your Evervault app. This can be found inside of your app settings on the Evervault dashboard.
evervault.encrypt(data)
Encrypts data using Evervault Encryption.
To encrypt strings using the JavaScript SDK, simply pass a String
or an Object
into the evervault.encrypt()
function. To encrypt a file, pass a File
or Blob
.
The encrypted data can be stored in your database or file storage as normal. Evervault Strings can be used across all of our Primitives. Evervault File Encryption is currently in Beta, and files can only be decrypted with Outbound Relay.
evervault.decrypt(token, data)
Decrypts data previously encrypted with the encrypt()
function or through Relay.
The decrypt()
function allows you to decrypt previously encrypted data using a token.
The token is a time bound token for decrypting data. The token can be generated using our backend SDKs or through our REST API.
The payload must be the same payload that was used to create the token and expires in a maximum of 10 minutes depending on the expiry set when creating the token.
The payload can be any String
or Object
and it will be returned, decrypted, in the same form.
evervault.ui.card(options)
Initializes a Card UI Component. The Card component makes it easy to collect and encrypt card data in a completely PCI-compliant environment.
Arguments
Allows you to completely customize the appearance of the component. See the Styling section for more details.
If set to true, the component will automatically steal focus when it mounts.
Allows you to configure the fields displayed in the component. Possible values are 'name', 'number', 'expiry', and 'cvc'. By default only 'number', 'expiry' and 'cvc' will be shown.
card.mount()
Mounts the component to a given DOM node.
card.on('change')
Subscribe to changes made to the component. The encrypted card details can be accessed from the payload passed to the callback.
Payload
Information about the entered card, including meta data as well as the encrypted number aned CVC.
Whether or not there are any errors shown. Validation occurs as the user looses focus on a field. You can force validation to occur with the .validate
method.
card.on('complete')
The complete event will fire once the user has successfully filled out all fields in the Card Component with valid values.
Payload
Information about the entered card, including meta data as well as the encrypted number aned CVC.
Whether or not there are any errors shown. Validation occurs as the user looses focus on a field. You can force validation to occur with the .validate
method.
card.on('ready')
The ready event will be fired once the component has fully loaded and is ready to be displayed. This is often used to show a loading state while the component loads.
card.on('error')
The error event will be fired if the component fails to load. If you want to respond to validation errors you should use the change event instead.
card.on('swipe')
Subscribe to swipe events from card readers. The encrypted card details can be accessed from the payload passed to the callback. The component must have focus for the card reader event to be detected.
card.update()
Update the configuration for the component after it has been initialized. Any arguments passed will be merged with the arguments passed when the component was initialized.
Arguments
Allows you to completely customize the appearance of the component. See the Styling section for more details.
If set to true, the component will automatically steal focus when it mounts.
Allows you to configure the fields displayed in the component. Possible values are 'name', 'number', 'expiry', and 'cvc'. By default only 'number', 'expiry' and 'cvc' will be shown.
card.validate()
Manually trigger validation for the card details fields.
card.unmount()
Removes the component from the DOM.
evervault.ui.pin(options)
Initializes a Pin UI Component. The Pin component allows you to collect and encrypt pin numbers in a completely PCI-compliant environment.
Options
Allows you to completely customize the appearance of the component. See the Styling section for more details.
pin.mount()
Mounts the component to a given DOM node.
pin.on('change')
Subscribe to changes made to the Pin component. The encrypted pin can be accessed from the payload passed to the callback.
Payload
pin.on('complete')
The 'complete' event will be fired once the pin number field has been fully filled out by the user.
Payload
pin.on('ready')
The ready event will be fired once the component has fully loaded and is ready to be displayed. This is often used to show a loading state while the component loads.
pin.on('error')
The error event will be fired if the component fails to load.
evervault.ui.reveal(request)
Initializes a Reveal UI Component. The Reveal component allows you to display previously encrypted card data to your users in plaintext in a secure iframe hosted by Evervault. Before using Reveal you'll first need to have a JSON endpoint to retrieve data from. This is often your own API endpoint combined with Inbound Relay to decryped previously encrypted data from your database.
It is important that the endpoint that you create sets the applicable CORS headers so that it can be accessed from the Reveal iframe. Otherwise your requests will fail!
reveal.on('ready')
The ready event will be fired once the request has been completed and all reveal consumer components are ready to be shown.
reveal.on('error')
The error event will be fired if the Reveal Component fails to load or the passed request fails.
reveal.text(JSONPath, options)
Creates a Reveal Text consumer. The Reveal Text consumer allows you to render a selected field from the request response.
Arguments
A JSON path selector for the response field you want to display.
Allows you to completely customize the appearance of the component. See the Styling section for more details.
text.mount()
Mounts the Reveal Text component to a given DOM node.
text.unmount()
Removes the Text Component from the DOM.
reveal.copyButton(JSONPath, options)
Creates a Reveal Copy Button consumer. This renders a button which when clicked will copy a response field to the users clipboard.
Arguments
A JSON path selector for the response field you want to display.
Allows you to completely customize the appearance of the component. See the Styling section for more details.
copyButton.mount()
Mounts the component to a given DOM node.
copyButton.on("copy")
The "copy" event will be fired when ever the user clicks the button and copies the value to their clipboard.
copyButton.unmount()
Removes the component from the DOM.
evervault.ui.themes
Provides access to the built-in UI Component themes. See the UI Components Styling section for more details.