@secure-share/integrations v0.0.44

Secure Share Integrations

This repo hosts the custom integration implementation files loaded via CDN by Secure Share.

How does it work?

A custom integration is comprised of a single JS file written using the Secure Share SDK to register the desired custom functionality with Secure Share. That JS file is then pushed to a TBD CDN host that Secure Share can later use to pull in the custom integration. Any necessary npm dependencies may be used and webpack will bundle them all into a single file when built.

Back in Secure Share, query parameters are used to trigger the loading of the custom integration's CDN file (ex: /secure-share/sharing?ch={channel}. A "channel" refers to the unique identifier for a custom integration. Once Secure Share has loaded the file, it will apply all changes passed in the registerIntegration function.

TODO: clarify a bit better and add documentation for registerIntegration function

Creating a new custom integration

1) Create a feature branch from main 2) Choose a unique channel id for your integration, typically using an abbreviation (e.g. Zendesk integration => 'zd'). 3) Add a new file for your integration to the /src folder using the naming structure {unique_channel_id}.js (e.g. Zendesk integration => zd.js). 4) Write your custom code for the window.SecureShare.registerIntegration() function call. 5) Update webpack.config.js to include an entry point for your new file. 6) Run npm build to create the new /dist file. 7) todo: publishing

Complete example (using Zendesk example)

unique channel id for integration = 'zd'

// ./src/zd.js

import axios from 'axios';

window.SecureShare.registerIntegration('zd', {
    onRender: async ({ params }) => {
        
        const { deliveryChannelURL, objectId, userId, appId } = params;

        const { data } = await axios.get(`${deliveryChannelURL}/greeting/zd/${objectId}`, {
            headers: {
                authorization: `Virtru [["${appId}", "${userId}"]]`
            }
        });
        
        if (data) {
            const { zdTenant, users, ticketTitle, ticketBody } = data;

            const fields = [
                {
                    type: 'display',
                    label: 'Ticket Title',
                    value: ticketTitle
                },
                {
                    type: 'display',
                    label: 'Ticket Body',
                    value: ticketBody
                },
                {
                    type: 'display',
                    label: 'ZD Tenant',
                    value: zdTenant
                }
            ];

            return {
                header: `Zendesk ticket: ${ticketTitle}`,
                fields,
                recipients: users
            }
        }
    },

    onSubmit: async ({ params, files }) => {

        const { deliveryChannelURL, objectId, userId, appId } = params;

        const { data } = await axios.post(
            `${deliveryChannelURL}/send/zd/${objectId}`, 
            { files }, 
            {  
                headers: { authorization: `Virtru [["${appId}", "${userId}"]]` } 
            }
        );

        if (data) {
            console.log('response.data', data);
        }
    }
});

// webpack.config.js

module.exports = {
    ...
    entry: {
        ...
        zd: path.resolve(__dirname, 'src/zd.js') // zendesk
    },
    ...
};