Reference Documentation
The VGS Show.js JavaScript library enables you to securely display sensitive data in a webpage while safely isolating that sensitive data from your systems and any 3rd party scripts. This enables you to instruct VGS to securely share data directly with your users while limiting your data security compliance burden.
<script type="text/javascript" src="https://js.verygoodvault.com/vgs-show/2.2.2/show.js"></script>VGSShow.create()
Create a VGS Show instance.
Example:
const show = VGSShow.create('<VAULT_ID>', (state) => {
console.log(state)
});Parameters:
vaultId (required)
string
The VGS organization’s unique vault ID value.
stateCallback
(state) => {}
Callback that will be called whenever the iframe state changes. It receives a state object.
{
'<NAME>': {
revealed: true,
name: '<NAME>'
}
}show.setEnvironment()
Specify your vault environment. Information about your vault can be found on the Dashboard.
Example:
show.setEnvironment('sandbox');Parameters:
environment (required)
string
Vault environment: sandbox, live or one with specified data region (e.g live-eu-1
show.setCname()
Specify your CNAME. If specified, the data will go through the cname instead of the vault url. Please make sure you have activated CNAME on the Dashboard.
Example:
show.setCname('my-custom-hostname.com');Parameters:
cname (required)
string
CNAME domain (e.g. my-custom-hostname.com)
show.request()
Configure an HTTP request to your server.
Example:
const frame = show.request({
name: 'secret-card-number',
method: 'POST',
path: '/secure-data',
payload: {'card_number': '<ALIAS>'},
htmlWrapper: 'text',
jsonPathSelector: 'json.card_number'
});Parameters:
name (required)
string
The unique name used to identify a specific iframe in the state object inside an update callback.
method (required)
string
HTTP request method: POST, GET, PUT
path (required)
string
The path that the request will be submitted to.
jsonPathSelector (required)
string
The JSONPath that the request will show the value for, not required for blob/image.
htmlWrapper
string ('text' | 'image')
This parameter specifies the expected type of response data. Image is wrapped into an <img src='<revealed_data>'/> HTML tag. Text would be inserted into a element inside the iframe. text by default.
payload
object
Request body data.
headers
object
Request headers.
xhrResponseType
string ('json' | 'arraybuffer')
Indicates the type of data that the server will respond with. json by default.
decodeDataFrom
string ('base64')
Indicates the encoding algorithm being used to decrypt value. false by default.
displayBase64Image
boolean
Please set to true if your image is base64 endoded. In this case, image would be wrapped into <img src='data:image/png;base64,<revealed_data>'/>. false by default.
serializers
array
You could use serializers in order to format received data. Works only for the text content:
.replace(oldSubStr, newSubStr, count)function
Returns a new string with some or all matches of an old value replaced by the new value. Under the hood using native String.prototype.replace() JS method. Example:
const frame = show.request({
...
// separate card number with dashes 4111111111111111 -> 4111-1111-1111-1111
serializers: [show.SERIALIZERS.replace('(\\d{4})(\\d{4})(\\d{4})(\\d{4})', '$1-$2-$3-$4')],
// separate card number with spaces 4111111111111111 -> 4111 1111 1111 1111
serializers: [show.SERIALIZERS.replace('(\\d{4})(\\d{4})(\\d{4})(\\d{4})', '$1 $2 $3 $4')],
// remove spaces 4111 1111 1111 1111 -> 4111111111111111
serializers: [show.SERIALIZERS.replace(' ', '')],
// remove first 2 dashes 4111-1111-1111-1111 -> 411111111111-1111
serializers: [show.SERIALIZERS.replace('-', "", 2)],
});withCredentials
boolean
Indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates. false by default.
show.copyFrom()
In order to improve and simplify UX for the end-user, Show.js provides the ability to copy data from the iframe to the clipboard buffer. .copyFrom() method generates a secure button instance. The button itself is located in a separate iframe and is fully customizable. To render it on the page, please use .render() method.
Example:
const frame = show.request({
name: 'secret-card-number',
method: 'POST',
path: '/secure-data',
payload: {'card_number': '<ALIAS>'},
htmlWrapper: 'text',
});
frame.render('#secret-data', { fontWeight: 'bold', color: 'blue' });
const copyButton = show.copyFrom(frame, { text: 'My copy button' }, (status) => {
if (status === 'Success') {
alert('Copied!')
}
});
copyButton.render('#place-for-copy-button', {
'@font-face': {
'font-family': 'PT Mono',
'font-style': 'normal',
'font-weight': '400',
'font-display': 'swap',
'src': 'local("PT Mono"), local("PTMono-Regular") url(https://fonts.gstatic.com/s/ptmono/v7/9oRONYoBnWILk-9AnCszM_HxEcn7Hg.woff2) format("woff2")',
'unicode-range': 'U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116'
},
'font-family': '"PT Mono", monospace',
'padding': '10px',
'background-color': 'red',
'font-size': '12px',
'color': 'white',
});Parameters:
targetSecureFrame (required)
Secure Frame Instance
The Show.js frame instance is initialized before the copy button.
params (required)
object
Available button configuration:
"text". Button label.
"serializers". Use serializers to format the value being copied. Works only for the text content.
callback
() ⇒ {}
The callback that will be called whenever the copy button is clicked. It receives a string with the action result status(success or error).
frame.render()
Render and customize your secure iframe.
Example:
frame.render('#secret-data', {
'font-family': 'Arial, sans-serif',
'color': 'white',
'font-size': '14px',
'&:hover': {
'color': 'red',
}
});Parameters:
selector (required)
string
The CSS selector that points to the element where the iframe will be added.
css
object
Use CSS properties and apply various CSS styles to the inner content. We do support: regular CSS properties, generic Web Fonts and @font-face property, pseudo-classes (eg. :hover, :focus) and media queries (media query condition is calculated based on the iframe width, not on the parent window)
frame.on()
Listen to events and handle different states in callback functions.
Adding an event handler for an unsupported event will throw an error.
Multiple event handlers can be added for the same event in the same iframe.
When multiple iframes reveal data with a single request, all iframes can receive corresponding events.
Please consider this case while adding event handlers to iframes with the same payload (token).
Example:
const frame = show.request({
name: 'secret-card-number',
method: 'POST',
path: '/secure-data',
payload: {'card_number': '<ALIAS>'},
htmlWrapper: 'text',
});
frame.on('requestSuccess', () => {
console.log('Request was successfully completed in card number iframe!');
});
frame.on('requestFail', (error) => {
const errorStatus = error.status || 'Uknown error status code';
console.log('The request failed with ', errorStatus);
console.log(error.message);
});
frame.on('revealSuccess', () => {
console.log('Reveal opeation successfully was completed in card number iframe!');
});
frame.on('revealFail', () => {
console.log('Reveal opeation was failed in card number iframe!');
});Parameters:
event (required)
string
requestSuccess. Triggers when the iframe request was successfully completed.
requestFails. Triggers when the iframe request fails. Event payload contains an error message and a status code (optional)
revealSuccess. Triggers when the data inside the iframe is successfully revealed.
revealFails. Triggers when the iframe reveal operation failed. In some cases request can be successfully completed but data still be unrevealed. A typical use case for this behavior is an incorrect payload (token) or a typo injsonPathSelector.
callback
() ⇒ {}
A function to execute each time the event is triggered.
frame.off()
Removes event handlers that were attached with .on() method.
Example:
const frame = show.request({
name: 'secret-card-number',
method: 'POST',
path: '/secure-data',
payload: {'card_number': '<ALIAS>'},
htmlWrapper: 'text',
});
frame.on('requestSuccess', function() {
console.log('Request was successfully completed in card number iframe!');
});
frame.on('requestFail', function(error) {
const errorStatus = error.status || 'Uknown error status code';
console.log('The request failed with ', errorStatus);
console.log(error.message);
});
// Your condition to remove attached listeners.
let needToRemoveListeners = true;
if (needToRemoveListeners) {
frame.off('requestSuccess');
frame.off('requestFail');
}Parameters:
event (required)
string
requestSuccess. Triggers when the iframe request was successfully completed.
requestFails. Triggers when the iframe request fails. Event payload contains an error message and a status code (optional)
revealSuccess. Triggers when the data inside the iframe is successfully revealed.
revealFails. Triggers when the iframe reveal operation failed. In some cases request can be successfully completed but data still be unrevealed. A typical use case for this behavior is an incorrect payload (token) or a typo injsonPathSelector.
callback
() ⇒ {}
A function to execute each time the event is triggered.
frame.retry()
Retry request attempt.
Example:
frame.on("requestFail", () => {
frame.retry({...});
});Parameters:
name (required)
string
The unique name used to identify a specific iframe in the state object inside an update callback.
method (required)
string
HTTP request method: POST, GET, PUT
path (required)
string
The path that the request will be submitted to.
jsonPathSelector (required)
string
The JSONPath that the request will show the value for, not required for blob/image.
htmlWrapper
string ('text' | 'image')
This parameter specifies the expected type of response data. Image is wrapped into an <img src='<revealed_data>'/> HTML tag. Text would be inserted into a element inside the iframe. text by default.
payload
object
Request body data.
headers
object
Request headers.
withCredentials
boolean
Indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates. false by default.
frame.unmount()
Unmount iframe from the DOM and clear internal references.
Example:
frame.unmount();Last updated