Quickstart
The Web Reveal SDK is a static, single page application that allows for the display of generated Voucher objects from Vouchr’s API, in a client’s browser. This means that the entire application will run from a single page, in this case, index.html. The SDK has configurable theming options according to your branding needs, and it also has the ability to:
- Display a custom wrapper/packaging using HTML.
- Display custom payment content using HTML upon opening of the voucher.
- Execute custom javascript upon opening of the Voucher.
Prerequisites
- A Vouchr account with access to Vouchr’s API and the Web Reveal SDK
- A place to host a static website (during local development & testing, you can use a local static http server such as serve, or http-server)
Installation
Simply unzip the project contents to a folder, and set up your favorite HTTP server such as Apache or NGINX, so that a visitor to the site is served index.html. The page can also be hosted using a dedicated hosting provider such as Netlify, Surge, or Amazon S3.
Folder Structure
├── index.css
├── animations.css
├── index.html
├── favicon.ico
├── assets
│ └── images
├── config
│ └── config.js
├── content
│ ├── examples
│ ├── giftPackage.js
│ └── partnerPayment.js
└── static
├── css
├── js
└── media
Configuration
Minimal configuration is required to get the Web Reveal up and running. At a bare minimum, the app needs to be configured to perform calls to Vouchr’s API to retrieve a Voucher JSON object, mark a Voucher as claimed etc.
To configure the app, edit config/config.js. This file contains a JS object, that is read in by the app to set up the proper API url, API key, as well as other functionality. See below for a complete list of properties that can be configured, and their descriptions.
| Property | Type | Required | Description | Default |
|---|---|---|---|---|
| apiUrl | string | yes | The base API url that the app uses to perform calls to Vouchr endpoints. | |
| apiKey | string | yes | Vouchr API key for the application. | |
| confettiColors | string[] | no | An array of hexadecimal colors for the confetti explosion. | [‘#26ccff’, ‘#a25afd’, ‘#ff5e7e’, ‘#88ff5a’, ‘#fcff42’, ‘#ffa62d’, ‘#ff36ff’] |
| confettiMode | string | no | How the confetti is displayed. Choose from: ‘EXPLODE’, ‘FIREWORKS’, ‘FALLING’, ‘SIDES’. | ‘EXPLODE’ |
| showBadge | boolean | yes | Display a badge with the sender’s profile picture and their name at the top of the page. | true |
| showPlayGameAgain | boolean | yes | For Vouchers locked with a game, show a button and the game badge after the Voucher is unlocked, at the bottom of the page. This allows the receiver to play the game again. | true |
| dryOpen | boolean | no | Prevents the gift package from being opened. Instead alternative content may be displayed below it. | false |
Badge
Play Game Again
Usage
Development
For your convenience while configuring the app and modifying the theme, we provide an example of a voucher JSON object in content/examples. To preview the example, uncomment the following script tags in index.html:
<script src="content/examples/voucherObjectExample.js"></script>
Production
The app reads in the invite code, specified as a URL fragment, to retrieve the Voucher’s JSON object from the Vouchr API. For example, when a user visits www.vouchrsdk.com/#6TvXaioicrooWWif, the app reads in the invite code as 6TvXaioicrooWWif, and performs an API call to the appropriate endpoint to exchange the invite code for a Voucher. See the documentation on the Vouchr API for more details.
Integrating in an existing page
To include the Web Reveal SDK on an existing page, perform the following steps:
- Copy all of the script and style tags in the head and body section of index.html to your existing page (maintain the order of these tags).
- Include the following html after all of the body tags in the web reveal:
<div id="root"></div>
The Web Reveal SDK will use this element as a DOM container, to insert the reveal content. You can style this container element as you wish to make it fit in the page.