Tutorial

This tutorial will help you set up an integrations bundle on your app. Broadly, the steps that need to be followed are:

1. Create a SDK deployment on the Integry web app
2. Copy secrets from the deployment page
3. Use these secrets to generate a hash server-side
4. Use the hash on your client to initialize the SDK

Prerequisites

1. Please make sure you have set up a SDK deployment on the Deployments page that will be shown to your users.
2. Please have the following information ready with you. These are available once you create an SDK deploy as shown below:

1. App key

The app key is an ID that uniquely identifies an app. This is generated automatically for every app on Integry’s side.

2. App secret

The app secret is a uniquely generated secret key for every app and is used for authentication.

Dragons ahead

The app key and secret must be stored securely and should not be embedded in HTML where it can be easily seen in the browser source.

3. Deployment ID

This is the ID of the SDK deployment in which all your flows are saved. Once the SDK is configured, all the flows in this bundle will be rendered in your app as available integrations.

4. User ID

The user ID is used to grant access to flows to a subset of your users, all the way down to individual users. A common use case is to have a UUID (Universal Unique Identifier) that is stored in your web app for each of your users. You can use that identifier as the user ID to give each of your users their own set of flows.

Scope access to multiple users

There can be scenarios where flows might be shared among multiple users in your app e.g. admins of that app. In that case, you can use an account ID instead of user IDs; this will give all the users under that account shared access to those flows.

5. Hash

You should have a mechanism for the authentication hash generation in place. This hash should be calculated server-side and returned to your client where it will be passed to the SDK as a configuration option. It is possible to move this calculation entirely to the client using our hash calculation helper function, but this not recommended unless:

1. The secret is not embedded in HTML and will never be leaked in browser source
2. You are using server-side rendering and the client will never see the helper code
3. You are in a testing environment and temporarily need this functionality until the recommended secure option is in place

In case you do not meet any of the criteria mentioned above, you can create a custom route on your backend to calculate the hash and return these secrets. Let us review this in the next section.

Backend configuration

Since an appKey, userId and hash are required to initialize the SDK, there has to be a way these parameters are securely passed to the client.

The hash is used to authenticate the SDK embed with Integry's servers. It is calculated using the user ID and app secret. Here are some examples on how to calculate the hash in multiple languages.

JS

const generate = (str) =>
  new Uint8Array(
    [...unescape(encodeURIComponent(str))].map((c) => c.charCodeAt(0)),
  );

const key = generate('${appSecret}');
const message = generate('<USER_ID>');

const cryptoKey = await crypto.subtle.importKey(
  'raw',
  key,
  { name: 'HMAC', hash: 'SHA-256' },
  true,
  ['sign'],
);

const signed = await crypto.subtle.sign('HMAC', cryptoKey, message);

const hash = [...new Uint8Array(signed)] // use this hash
  .map((b) => b.toString(16).padStart(2, '0'))
  .join('');

Python

import hmac
import hashlib

app_secret = b"<app_secret>"
user_id = b"<user_id>"

# use this hash
hash = hmac.new(app_secret, user_id, hashlib.sha256).hexdigest()

Php

<?php

$appSecret = '<APP_SECRET>';
$userId = '<USER_ID>';
$hash = hash_hmac('sha256', $userId, $appSecret);

You can consume these examples in a protected API endpoint and return these after users log in to your app. Here's an example of how this can be done in Express, a popular NodeJS web framework.

const generate = (str) =>
  new Uint8Array(
    [...unescape(encodeURIComponent(str))].map((c) => c.charCodeAt(0))
  );

// simple authentication guard
function restrict(req, res, next) {
  if (req.session.user) {
    next();
  } else {
    req.session.error = "Access denied!";
    res.redirect("/login");
  }
}

app.get("/integry-params", restrict, function (req, res) {
  const { user } = req;

  const appSecret = "<APP_SECRET>";
  const appKey = "<APP_KEY>";
  const deploymentId = "<DEPLOYMENT_ID>";

  const message = generate(user.id);
  const key = generate(appSecret);

  const cryptoKey = await crypto.subtle.importKey(
    "raw",
    key,
    { name: "HMAC", hash: "SHA-256" },
    true,
    ["sign"]
  );

  const signed = await crypto.subtle.sign("HMAC", cryptoKey, message);

  const hash = [...new Uint8Array(signed)]
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");

  res.json({
    hash,
    appKey,
    deploymentId,
  });
});

Initializing the SDK

After retrieving the secrets from the API route, we are now ready to set up the SDK. Here is a minimal example of how to initialize the SDK using the pieces of information we gathered as a prerequisite.

<body>
  <div id="my-integry-container"></div>
</body>
<!-- ... -->
<script>
  window.addEventListener('DOMContentLoaded', async function () {
    const sdkInstance = new IntegryJS({
      appId: '<app_id>',
      deploymentId: '<deployment_id>',
      userId: '<user_id>',
      hash: '<hash>',
    });

    // initialize integration view in our container
    sdkInstance.init({
      containerId: 'my-integry-container',
      renderMode: IntegryJS.RenderModes.MODAL,
    });
  });
</script>

This will use the configuration to instantiate an IntegryJS object which you can use to initialize an embed view in any container element in the DOM.

By default, this minimal configuration will render a simple integration layout with a list of integrations, where the template forms will be shown in a modal. Attempting to set up an integration will open a modal where the SDK will load the associated template form.

The SDK will handle everything internally in this mode of operation, while providing EventEmitter methods which you can subscribe to in order to plug in your own logic in the lifecycle.

tip

We have made this simple to get started with, but you will likely be interested in customizing the views with your own branding, colors and fonts etc.

Please read our changing defaults and style customization sections to find out more.