# 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.

```html
<script type="text/javascript" src="https://js.verygoodvault.com/vgs-show/2.2.2/show.js"></script>
```

## VGSShow\.create() <a href="#api-vgscollectcreate" id="api-vgscollectcreate"></a>

***

Create a VGS Show instance.

{% hint style="info" %}
*VGSShow\.create(vaultId, stateCallback)*
{% endhint %}

*Example:*

```javascript
const show = VGSShow.create('<VAULT_ID>', (state) => { 
  console.log(state)
});
```

*Parameters:*

<table><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>vaultId</strong> (required)</td><td>string</td><td>The VGS organization’s unique vault ID value.</td></tr><tr><td><strong>stateCallback</strong></td><td>(state) => {}</td><td><p>Callback that will be called whenever the iframe state changes. It receives a <code>state</code> object.</p><pre class="language-javascript"><code class="lang-javascript">{
  '&#x3C;NAME>': {
    revealed: true,
    name: '&#x3C;NAME>'
  }
}
</code></pre></td></tr></tbody></table>

## show\.setEnvironment() <a href="#api-showsetenvironment" id="api-showsetenvironment"></a>

***

Specify your vault environment. Information about your vault can be found on the Dashboard.

{% hint style="info" %}
*show\.setEnvironment(environment)*
{% endhint %}

*Example:*

```javascript
show.setEnvironment('sandbox');
```

*Parameters:*

| Argument                   | Type   | Description                                                                             |
| -------------------------- | ------ | --------------------------------------------------------------------------------------- |
| **environment** (required) | string | Vault environment: `sandbox`, `live` or one with specified data region (e.g `live-eu-1` |

## show\.setCname() <a href="#api-showsetcname" id="api-showsetcname"></a>

***

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.

{% hint style="info" %}
*show\.setCname(cname)*
{% endhint %}

*Example:*

```javascript
show.setCname('my-custom-hostname.com');
```

*Parameters:*

| Argument             | Type   | Description                                  |
| -------------------- | ------ | -------------------------------------------- |
| **cname** (required) | string | CNAME domain (e.g. `my-custom-hostname.com`) |

## show\.request() <a href="#api-showsetcname" id="api-showsetcname"></a>

***

Configure an HTTP request to your server.

{% hint style="info" %}
s*how\.request({ params })*
{% endhint %}

*Example:*

```javascript
const frame = show.request({
  name: 'secret-card-number',
  method: 'POST',
  path: '/secure-data',
  payload: {'card_number': '<ALIAS>'},
  htmlWrapper: 'text',
  jsonPathSelector: 'json.card_number'
});
```

*Parameters:*

<table><thead><tr><th width="231.80859375">Argument</th><th width="180.921875">Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>name</strong> (required)</td><td>string</td><td>The unique name used to identify a specific iframe in the <code>state</code> object inside an update callback.    </td></tr><tr><td><strong>method</strong> (required)</td><td>string</td><td>HTTP request method: <code>POST</code>, <code>GET</code>, <code>PUT</code></td></tr><tr><td><strong>path</strong> (required)</td><td>string</td><td>The path that the request will be submitted to.</td></tr><tr><td><strong>jsonPathSelector</strong> (required)</td><td>string</td><td>The JSONPath that the request will show the value for, not required for blob/image.</td></tr><tr><td><strong>htmlWrapper</strong></td><td>string ('text' | 'image')</td><td>This parameter specifies the expected type of response data. Image is wrapped into an <code>&#x3C;img src='&#x3C;revealed_data>'/></code> HTML tag. Text would be inserted into a element inside the iframe. <code>text</code> by default.</td></tr><tr><td><strong>payload</strong></td><td>object</td><td>Request body data.</td></tr><tr><td><strong>headers</strong></td><td>object</td><td>Request headers.</td></tr><tr><td><strong>xhrResponseType</strong> </td><td>string ('json' | 'arraybuffer')</td><td>Indicates the type of data that the server will respond with. <code>json</code> by default.</td></tr><tr><td><strong>decodeDataFrom</strong></td><td>string ('base64')</td><td>Indicates the encoding algorithm being used to decrypt value. <code>false</code> by default.</td></tr><tr><td><strong>displayBase64Image</strong></td><td>boolean</td><td>Please set to true if your image is base64 endoded. In this case, image would be wrapped into <code>&#x3C;img src='data:image/png;base64,&#x3C;revealed_data>'/></code>. <code>false</code> by default.</td></tr><tr><td><strong>serializers</strong></td><td>array</td><td><p>You could use serializers in order to format received data. Works only for the text content:</p><ul><li>.replace(oldSubStr, newSubStr, count)<em>function</em></li></ul><p>Returns a new string with some or all matches of an old value replaced by the new value. Under the hood using native <code>String.prototype.replace()</code> JS method. Example:</p><pre class="language-javascript"><code class="lang-javascript">  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)],
}); </code></pre></td></tr><tr><td><strong>withCredentials</strong></td><td>boolean</td><td>Indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates. <code>false</code> by default.</td></tr></tbody></table>

## show\.copyFrom() <a href="#api-showsetcname" id="api-showsetcname"></a>

***

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.

{% hint style="info" %}
*show\.copyFrom(targetSecureFrame, { params }, callback)*
{% endhint %}

*Example:*

```javascript
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:*

<table><thead><tr><th width="231.80859375">Argument</th><th width="180.921875">Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>targetSecureFrame</strong> (required)</td><td>Secure Frame Instance</td><td>The Show.js frame instance is initialized <strong>before</strong> the copy button.</td></tr><tr><td><strong>params</strong> (required)</td><td>object</td><td><p>Available button configuration:</p><ul><li><code>"text"</code>. Button label.</li><li><code>"serializers"</code> . Use serializers to format the value being copied. Works only for the text content.</li></ul></td></tr><tr><td><strong>callback</strong></td><td>() ⇒ {}</td><td>The callback that will be called whenever the copy button is clicked. It receives a string with the action result status(<code>success</code> or <code>error</code>).</td></tr></tbody></table>

## frame.render() <a href="#api-showsetcname" id="api-showsetcname"></a>

***

Render and customize your secure iframe.

{% hint style="info" %}
*frame.render(selector, css)*
{% endhint %}

*Example:*

```javascript
frame.render('#secret-data', {
  'font-family': 'Arial, sans-serif',
  'color': 'white',
  'font-size': '14px',
  '&:hover': {
    'color': 'red',
  }
});
```

*Parameters:*

| Argument                | Type   | Description                                                                                                                                                                                                                                                                                             |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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() <a href="#api-showsetcname" id="api-showsetcname"></a>

***

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).

{% hint style="info" %}
*frame.on(event, callback)*
{% endhint %}

*Example:*

```javascript
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:*

<table><thead><tr><th width="165.66796875">Argument</th><th width="129.7421875">Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>event</strong> (required)</td><td>string</td><td><ul><li><code>requestSuccess</code>. Triggers when the iframe request was successfully completed.</li><li><code>requestFails</code>. Triggers when the iframe request fails. Event payload contains an error message and a status code (optional)</li><li><code>revealSuccess</code>. Triggers when the data inside the iframe is successfully revealed.</li><li><code>revealFails</code>. 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 in <code>jsonPathSelector</code>.</li></ul></td></tr><tr><td><strong>callback</strong></td><td>() ⇒ {}</td><td>A function to execute each time the event is triggered.</td></tr></tbody></table>

## frame.off() <a href="#api-showsetcname" id="api-showsetcname"></a>

***

Removes event handlers that were attached with .on() method.

{% hint style="info" %}
*frame.off(event, callback)*
{% endhint %}

*Example:*

```javascript
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:*

<table><thead><tr><th width="165.66796875">Argument</th><th width="129.7421875">Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>event</strong> (required)</td><td>string</td><td><ul><li><code>requestSuccess</code>. Triggers when the iframe request was successfully completed.</li><li><code>requestFails</code>. Triggers when the iframe request fails. Event payload contains an error message and a status code (optional)</li><li><code>revealSuccess</code>. Triggers when the data inside the iframe is successfully revealed.</li><li><code>revealFails</code>. 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 in <code>jsonPathSelector</code>.</li></ul></td></tr><tr><td><strong>callback</strong></td><td>() ⇒ {}</td><td>A function to execute each time the event is triggered.</td></tr></tbody></table>

## frame.retry() <a href="#api-showsetcname" id="api-showsetcname"></a>

***

Retry request attempt.

{% hint style="info" %}
*frame.retry({ ...params })*
{% endhint %}

*Example:*

```javascript
frame.on("requestFail", () => {
  frame.retry({...});
});
```

*Parameters:*

<table><thead><tr><th width="231.80859375">Argument</th><th width="180.921875">Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>name</strong> (required)</td><td>string</td><td>The unique name used to identify a specific iframe in the <code>state</code> object inside an update callback.    </td></tr><tr><td><strong>method</strong> (required)</td><td>string</td><td>HTTP request method: <code>POST</code>, <code>GET</code>, <code>PUT</code></td></tr><tr><td><strong>path</strong> (required)</td><td>string</td><td>The path that the request will be submitted to.</td></tr><tr><td><strong>jsonPathSelector</strong> (required)</td><td>string</td><td>The JSONPath that the request will show the value for, not required for blob/image.</td></tr><tr><td><strong>htmlWrapper</strong></td><td>string ('text' | 'image')</td><td>This parameter specifies the expected type of response data. Image is wrapped into an <code>&#x3C;img src='&#x3C;revealed_data>'/></code> HTML tag. Text would be inserted into a element inside the iframe. <code>text</code> by default.</td></tr><tr><td><strong>payload</strong></td><td>object</td><td>Request body data.</td></tr><tr><td><strong>headers</strong></td><td>object</td><td>Request headers.</td></tr><tr><td><strong>withCredentials</strong></td><td>boolean</td><td>Indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates. <code>false</code> by default.</td></tr></tbody></table>

## frame.unmount() <a href="#api-showsetcname" id="api-showsetcname"></a>

***

Unmount iframe from the DOM and clear internal references.

{% hint style="info" %}
*frame.unmount()*
{% endhint %}

*Example:*

```javascript
frame.unmount();
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.verygoodsecurity.com/vault/developer-tools/vgs-show/js/reference-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.