Configuration

In order to load and render Show.js simply include a JavaScript tag and then invoke the library.

Add Show.js script to the page

Add the following script tag to the webpage that will render the data to your customer:

PCI 4.0 RequirementsWith the introduction of PCI DSS version 4.0, a new requirement has been put forth to ensure the integrity of scripts that run on payment pages. Script Integrity is crucial in maintaining the security and trustworthiness of online payment systems, as any unauthorized modifications to these scripts could potentially lead to data breaches or fraudulent activities. To meet this requirement, organizations must implement mechanisms to verify the integrity of each script utilized on their payment pages. To get a hash of a specific version, visit this page.

<script type="text/javascript" src="https://js.verygoodvault.com/vgs-show/2.2.2/show.js" integrity="sha384-70nFlhYfZpPZ0nh4E9kRCT2HXORAKatDFQXQP8Dxq8motfd35aSMMu9g6VE/oAIV" crossorigin="anonymous"></script>

In your HTML create an empty wrapper element and assign it your own unique identifier (we've used "secret-data" here, but you can assign your own UID). This element defines the place where the iframe will be inserted:

Example:

<div id="secret-data">Iframe with revealed data would be here!</div>HTML

Initialize Show.js

Use the following code to create VGS Show instance:

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

Configure HTTP request

Use the .request() method to configure HTTP requests to your backend:

Example

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

Authorization methods

There are multiple options for how you can authorize a Show.js request:

show.request({
  withCredentials: true,
  ...
});

  • Via `Authorization` header in the `show.request()` method:

show.request({
  headers: {
    'Authorization': <token>
  }
});

Please also check that the server responds with the Access-Control-Allow- headers.

  • Via API Key as a header or as a query parameter in the show.request() method:

Render secure frame

Use the .render() method to insert the Show.js iframe somewhere on your page. It takes two arguments: a CSS selector identifying where the iframe will be rendered on the page and an object with custom styles that will be applied to the revealed value.

Example:


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

Subscribe to changes

Listen to events and handle different states in callback functions.


frame.on('requestSuccess', function() {
  console.log('HTTP request was successfully completed!');
});
frame.on('requestFail', function(error) {
  const errorStatus = error.status || 'Uknown error status code';
  console.log('The request failed with ', errorStatus);
  console.log(error.message);
});
frame.on('revealSuccess', function() {
  console.log('Reveal opeation successfully was completed. Secure value revealed!');
});
frame.on('revealFail', function() {
  console.log('Reveal opeation was failed in the iframe!');
});
frame.render('#secret-data', { fontWeight: 'bold', color: 'blue' });\n

Copy to clipboard button

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. The button itself is located in a separate iframe and is fully customizable.

Step 1. Create dependency

Use .copyFrom() method to set the target iframe (you want to copy data from) and configurethe button.

Iframe with revealed data should be initialized before the copy button.

Example:


  const show = VGSShow.create('<VAULT_ID>' function(state) {})
                    .setEnvironment('<ENVIRONMENT>');\n
  const cardNumber = show.request({
    name: 'secret-card-number',
    method: 'POST',
    path: '/secure-data',
    payload: {'card_number': '<ALIAS>'},
    htmlWrapper: 'text',
  });\n
  const copyButton = show.copyFrom(cardNumber, { text: 'My copy button' }, (status) => {
      if (status === 'Success') {
        alert('Copied!')
      }
  });

2. Render button

Render copy to clipboard button.

Example:

const show = VGSShow.create('<VAULT_ID>' function(state) {})
                  .setEnvironment('<ENVIRONMENT>');
const cardNumber = show.request({
  name: 'secret-card-number',
  method: 'POST',
  path: '/secure-data',
  payload: {'card_number': '<ALIAS>'},
  htmlWrapper: 'text',
});
cardNumber.render('#secret-data', { fontWeight: 'bold', color: 'blue' });\n
const copyButton = show.copyFrom(cardNumber, { 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',
});

Data formatting

You have the ability to format received data or the value being copied to the clipboard via serializers property.

.replace()

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.

Examples:

const cardNumber = 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)],
});
const copyBtn = show.copyFrom(cardNumber,
  {
    text: 'Copy',
    // remove dashes from value when copying data to clipboard 4111-1111-1111-1111 -> 41111111111111111
    serializers: [show.SERIALIZERS.replace('-', "")],
  },
  function (status) {
    if (status === 'success') {
      alert('Copied!');
    }
});

VGS Show.js with CNAMEs

When integrated with VGS, by default, the traffic is passed via the VGS proxy, which has tntxxxxx.sandbox.verygoodproxy.com format, where tntxxxxx is your Vault identifier. VGS Show.js allows you to set your own hostname and make requests to the non-VGS domain name.

Before adding a new Hostname, you should create a CNAME record for your existing domain in your DNS provider’s account that should point to <VAULT_ID>.<ENVIRONMENT>.verygoodproxy.com.

Learn more about custom hostnames.

Go to the Vault Settings on the Dashboard and add a Custom Hostname, then click on the Activate for SDKs button.

Custom hostnames

Once the CNAME is turned on, specify the custom hostname domain using .setCname() method, and you're all set. Now, traffic will go through the defined CNAME.

Example:

const show = VGSShow.create('<VAULT_ID>', (state) => {})
                    .setEnvironment('<ENVIRONMENT>')
                    .setCname('my-cname.com')

VGS Show.js with Cookies

If you would like to pass cookies to your server along with the request made from the Show.js, make sure you've done all the steps from the list below:

  • You can't share cookies across domains. You may share across subdomains. Matching rules for the domain require the cookie Domain to match the host to which the request is being made. Configure and use CNAME in your integration with Show.js. Your application and API must have the same origin; otherwise, the browser will not attach them to the request. Custom Hostnames allows making a Vault accessible at a non-VGS domain name (for example, www.customdomain.com). So any requests made through VGS will now reflect your domain alias. Example: .myawesomesite.com - your application domain. .vgs.myawesomesite.com - CNAME configured and used as a request URL domain.

  • Add an additional withCredentials: true property in the show.request() method which will indicate that the request should be made using credentials such as cookies or authorization headers:\

show.request({
    ...,
    withCredentials: true
});

  • Make sure you have added SameSite=None and Secure attributes to the Set-Cookie header: Set-Cookie: flavor=choco; Domain=.myawesomesite.com; Secure; HttpOnly; SameSite=None

  • Please also check that the server responds with the Access-Control-Allow-Credentials header. Responding with this header to true means that the server allows cookies (or other user credentials) to be included on cross-origin requests.

  • Adding `SameSite=None` disable the protection from CSRF. Instead CSRF will need to be guarded against through one time use tokens or similar means.

  • Be aware of requests done to other origins which may result in the users cookie now being shared.

Configuration example

Client
<body>
  <main>
    <!-- Iframe wrapper -->
    <div id="secret-data"></div>
  </main>
  <!-- Show.js script file -->
  <script type="text/javascript" src="https://js.verygoodvault.com/vgs-show/2.0.0/<organization-id>.js"></script>
  <script>
    // Show.js initialization
    const show = VGSShow.create('<VAULT_ID>', function(state) {
        console.log(state);
    }).setEnvironment('<ENVIRONMENT>');
    // Request configuration
    const iframe = show.request({
      name: 'secret-card-number',
      method: 'POST',
      path: '/secure-data',
      payload: {'card_number': '<alias>'},
      htmlWrapper: 'text',
      jsonPathSelector: 'json.card_number'
    });
    // iframe rendering
    iframe.render('#secret-data', { fontWeight: 'bold', color: 'blue' });
  </script>
</body>
Server
route('/get-secret-data', method="POST", function(request, response) {
  // User authentication is required
  if (authenticationSuccess()) {
    response.status(200).send(<alias>);
  } else {
    response.status(403);
  }
});

VGS Show on mobile

Here is a demo of how VGS Show.js can be integrated into your mobile application via WebView:

Code examples

PreviousOverviewNextReference Documentation

Last updated