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
teamIdRequired

The ID of your Evervault team. This can be found inside of your team settings on the Evervault dashboard.

appIdRequired

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
teamIdRequired

The ID of your Evervault team. This can be found inside of your team settings on the Evervault dashboard.

appIdRequired

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.

Parameters
dataRequiredString | Data | File | Blob

The data to encrypt.


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
options.theme

Allows you to completely customize the appearance of the component. See the Styling section for more details.

options.autoFocusBoolean

If set to true, the component will automatically steal focus when it mounts.

options.fieldsString[]

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.

options.translations

Allows you to customize the text shown inside of the component.

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
card

Information about the entered card, including meta data as well as the encrypted number aned CVC.

errors{ [field]: String }

Validation errors related to the card details.

isValidBoolean

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.

isCompleteBoolean

Whether or not all of the fields have been filled out successfully with valid values.

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
card

Information about the entered card, including meta data as well as the encrypted number aned CVC.

errors{ [field]: String }

Validation errors related to the card details.

isValidBoolean

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.

isCompleteBoolean

Whether or not all of the fields have been filled out successfully with valid values.

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.

Payload
payload

Information about the card, including meta data as well as the encrypted number.

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
options.theme

Allows you to completely customize the appearance of the component. See the Styling section for more details.

options.autoFocusBoolean

If set to true, the component will automatically steal focus when it mounts.

options.fieldsString[]

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.

options.translations

Allows you to customize the text show inside of the component.

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
theme

Allows you to completely customize the appearance of the component. See the Styling section for more details.

autoFocusBoolean

If set to true, the component will automatically steal focus when it mounts.

lengthNumber | Default: 4

Change the length of the pin number.

modenumeric | alphanumeric

If set to 'alphanumeric' the pin number will also accept letters as input.

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
valueString

The encrypted pin number.

isCompleteBoolean

Whether or not the pin number field is complete.

pin.on('complete')

The 'complete' event will be fired once the pin number field has been fully filled out by the user.

Payload
valueString

The encrypted pin number.

isCompleteBoolean

Whether or not the pin number field is complete.

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
JSONPathString

A JSON path selector for the response field you want to display.

options.theme

Allows you to completely customize the appearance of the component. See the Styling section for more details.

options.format

Allows you to use regex matching to format the field value.

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
JSONPathString

A JSON path selector for the response field you want to display.

options.theme

Allows you to completely customize the appearance of the component. See the Styling section for more details.

options.text

The text to display inside of the button.

options.icon

A URL encoded image to display inside of the button.

options.format

Allows you to use regex matching to format the field value.

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.