@touchcode/js-touchcode-sdk

js-touchcode-sdk

This is the Touchcode JavaScript SDK. It is intended for use in a browser environment, and is not designed to work in Node.js.

Setup

The library is available on npm. It can be installed with: npm install --save @touchcode/js-touchcode-sdk.

Usage

• Import js-touchcode-sdk:

import touchcodeInit from "@touchcode/js-touchcode-sdk";

• Create a Touchcode instance inside your view:

touchcodeInit(campaignId, touchcodeEnabledDiv, progressCallback,decodeCallback, autoRedirect, decodeUrl, testBandwidth)

• Create a handler for the decodeCallback:

const decodeCallback = (event) => {
    console.log('decode callback', event)
}

• Create element with a unique id in the body of the html page. Shown below is an example.

<div id=”touchcode_enabled_div” class="touchcode_content"> </div>

• In this example, the unique id is “touchcode_enabled_div”. This div will be used to receive touches. This element should be styled to reflect the region of the page that will have Touchcode functionality. Shown below is an example of css code that allows the entire visible webpage to receive touches.

.touchcode_content{ 
    display: block;
    width: 100%;
    height: 100vh; 
}

Example

The following example consists of a touchcodeInit module in an index.js file. The campaignID must be provided by Touchcode.

Touchcode calls back to by the decodeCallback with the value decoded in the argument code.

Note: Touchcode receives touch input. It must be the top most element of the view.

JavaScript

import touchcodeInit from "@touchcode/js-touchcode-sdk";


const decodeCallback = target => console.log(target) // target = https://www.touchcode.com

const progressCallback = touches => console.log(`There are ${touches} touch points`) // use this to give the user progress feedback.


const init = (() => {
    let campaignId = 'Provide-Campaign-ID',
        touchcodeEnabledDiv = 'touchcode_enabled_div',
        autoRedirect = false,
        decoderUrl = null,
        testBandwidth = true;

    touchcodeInit(campaignId, touchcodeEnabledDiv, progressCallback, decodeCallback, autoRedirect, testBandwidth);
})()

HTML

    <div class=”touchcode_content” id=”touchcode_enabled_div”> </div>

CSS

    .touchcode_content{ 
        display: block;
        width: 100%;
        height: 100vh; 
    }

touchcodeInit() Parameters

Name	Type	Default	Description
campaignId	string	REQUIRED	ID of the Touchcode campaign that will be used on this web app. This value must reflect an already created Touchcode campaign. Only codes in the codeset for this campaign will work on the web app.
touchcodeEnabledDiv	element object	REQUIRED	Element created in step 2. All touches occurring within this element will be sent to the decoder and if applicable, processed for a decode.
decodeCallback	func	(code) => null	Called when a decode is triggered with the decoded text passed as an argument. If no callback is specified the page will auto redirect to the target stored in the campaign.
progressCallback	func	(code) => null	Called when a touch event is triggered touchpoint data passed as an argument.
autoRedirect	bool	true	Boolean variable to determine whether or not the SDK will automatically redirect to the target URL. The absence of this parameter defaults to “True.”
decoderUrl	string	null	By default, the Touchcode SDK utilizes a standard decoder. In very rare circumstances, it may be desired to change the decoder that the webapp is using. In nearly all cases, this parameter should not be supplied.
testBandwidth	bool	false	Boolean variable to determine whether or not the SDK will automatically preform a bandwidth test during a session. In certain cases this may not be desirable on slow connections and can be disabled by passing “false”. The absence of this parameter defaults to “true.”

Validating One-Time Tokens

If your campaign has one-time tokens enabled, each successfully decoded target URL will include a tc_nonce query parameter with a one-time token (a nonce) that can be validated using our SDK. We recommend validating this token via JavaScript code running on the target website, assuming that that website is under your control. This approach pairs well with the autoRedirect option that can be passed to touchcodeInit().

You can validate one-time tokens using the validateTouchcodeToken() function, which returns a Promise that evaluates to either true or false:

// your-target-website.js
import { validateTouchcodeToken } from "@touchcode/js-touchcode-sdk";

validateTouchcodeToken()
    .then(isTokenValid => {
        // use the validation results here
    })
    .catch(err => console.error(err.message));

validateTouchcodeToken() will validate against the browser window's current location, and will look for the one-time token in a query parameter called tc_nonce.

Server-side Token Validation

If you'd prefer to validate one-time tokens on your own server, you can call our API directly instead of using this SDK.

To validate a token, make a POST request to https://api.touchcode.com/2.0.2/validate_nonce that includes a JSON body with the following format:

{
    "targetUrl": "https://example.com",
    "nonce": "MiQt_biWT46704NkXsu1JQ"
}

If your token and target URL are valid, then our API will respond with a 200 status code. If they are invalid, the API will respond with a 401 status code.