Skip to main content
Sign in

Embed the marketplace in your app

The marketplace is what you embed in your app using the SDK so your users can setup integrations with other apps. You can control what flows to show by tagging them, and filtering on those tags. The widget emits a number of different events that you can leverage to control the user journey.

Screenshot 2024-01-29 at 4.03.18 PM.png

 

In this tutorial, we will:

If you haven't already, please create a flow that syncs data TO another app, or create a flow that syncs data FROM another app, before you proceed because you need a flow to embed.

Generate the embed code

  1. Click Embed (on the Flows page).
  2. Choose a style. In this example, we're using Compact.
  3. Choose how to show the flows. In this example, we're using "Flows grouped as apps".
  4. Click Next.
  5. Click Generate code.
An HTML file with a fully working prototype will have downloaded.

Open it in the browser and try it out. You should also inspect the code or open it in a code editor to see how it runs.

Note: Just like the preview on the embed page, all integrations you set up and/or enable with this file are against your user in Integry.

Install the SDK

The SDK is available as a module which can be installed via npm or yarn. Download and install the SDK using the package manager of your choice.

Please make sure the SDK has loaded before accessing methods. You can access the global in the window onload event, or add an event listener to listen to the document DOMContentLoaded event as shown here:

document.addEventListener("DOMContentLoaded", (event) => {
new IntegryJS(config);
});

Authenticate your app and ID the user

For Integry to recognize your requests, you need to set up authentication first. Provide an App Key, Secret, User ID, A and Hash. Here's what they are and how to find them:

App key​

This uniquely identifies your app in Integry. You can find it in Account Settings > Security.

App secret

It's a unique secret key for every app and is used for authentication. You can find it in Account Settings > Security. You should never expose this to the browser.

User ID​

We simply use whatever unique ID string you pass in this field to associate, and return, flow integrations that a user sets up. We don't assign any additional credentials to your users.

API key

API calls from Integry to your app can be authenticated using this key. We will pass it in the header or parameters.

If you don't support user-specific API keys, you can hardcode an Integry-specific key. You can also pass extra values to ID the user, campaign, etc.

Hash​

This is calculated using the User ID and App Secret to authenticate the SDK widget with Integry's servers. While it can be calculated client-side using a helper function, it's best that you calculate it server-side after a user logs in to your app, and return the hash via API endpoint (along with the App Key and User ID) for security.

Here's how you would do that in Express, a popular NodeJS web framework:

// 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 userId = user.id;
    const appKey = process.env.INTEGRY_APP_KEY;
    const appSecret = process.env.INTEGRY_APP_SECRET;

    const hash = crypto
        .createHmac("sha256", appSecret)
        .update(userId)
        .digest("hex");

    // use these to initialize the Actions SDK
    res.json({
        appKey,
        hash,
        userId,
    });
});

Note: Again, the app secret must be stored securely and should not be embedded in HTML where it can be easily seen in the page source.

Create an instance of the widget

Place the following code in the <body> tag.
<script>
// Wait for the DOM (web page content) to be fully loaded
window.addEventListener("DOMContentLoaded", async function(){

    // Replace '<app_key>', '<hash>', and '<user_id>' with your actual values
    const integryHandler = new IntegryJS({
        appKey,
        hash,
        userId,
        xIntegryConfig: {
            appAuth: {
                apiKey: "", /* Add your App API key here. It will be use to authenticate user */
            }
        },
        options: {
        title: "Apps", /* Add title here E.g. "Apps" */
        tags: [], /* Which Apps do you want to show? Pass tag names in array E.g. ["Production","Beta"] */

        // All objects, that can be used, are passed in, as shown below
        objects: {
            "Contact": {
                "firstName": "John",
                "lastName": "Doe",
                "email": "johndoe@example.com",
                "dateOfBirth": "1990-01-01",
                "gender": "male",
                "age": 20
                "phone": "555-555-1234",
                "address": {
                    "postalCode": "10001",
                    "city": "New York",
                    "state": "NY",
                    "street": "123 Main St",
                    "country": "USA"
                    },
                },
            },
        },
    });
});
</script>

Note: This includes the Contact object. More on that in a bit.

Initialize the widget

Add a <div>tag where the widget will be rendered. In this example, the Integry widget will be rendered in-line where you place this div.
<div id="x-integry-container"></div>
Call this function a <script></script> block when you want to initialize the widget. In this example, since we're, you could simply do that on page load by putting it right after the instance creation code.
integryHandler.init({
    containerId: "x-integry-container", /* Add the dom container id where you want to render sdk */
    showApps: true, /* Add this flag if you want to group Flows by App*/      
    renderMode: IntegryJS.RenderModes.INLINE, /* View App List in a modal or inline? Pass IntegryJS.RenderModes.MODAL or IntegryJS.RenderModes.INLINE.*/
    renderAppPageMode: IntegryJS.RenderModes.MODAL, /* View Flows list in a modal or inline? Pass IntegryJS.RenderModes.MODAL or IntegryJS.RenderModes.INLINE.*/
    renderFlowSetupMode: IntegryJS.RenderModes.MODAL, /* View Flow setup form in a modal or inline? Pass IntegryJS.RenderModes.MODAL or IntegryJS.RenderModes.INLINE.*/
    viewStyle: IntegryJS.ViewStyles.COMFORTABLE,
});

If the flow you want to try goes from another app to your app, then this is it! Just like you did then, you should now be able to set up an integration of that flow, and it will run when you trigger it from the other app.

If the flow you want to try goes from your app to the other app, then you have a couple more steps left.

Get the callback URL

In order to be able to trigger an integration of a flow from your app, you need to get and store the unique callback URL for that integration. The SDK generates and echoes the URL when the user finishes setting up the integration.

The example code shows how to echo and print the URL on the console.

integryHandler.eventEmitter.on('did-save-integration', (data) => {
    console.log("Callback URL: " + data.callbackUrl);
});

Run the flow

Finally, when the appropriate event occurs in your app (New lead? Button click?), call the URL you saved in the previous step with the appropriate JSON payload. If you're using the tutorial flow, then this would be the payload:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe@example.com",
  "dateOfBirth": "1990-01-01",
  "gender": "male",
  "age": 20
  "phone": "555-555-1234",
  "address": {
    "postalCode": "10001",
    "city": "New York",
    "state": "NY",
    "street": "123 Main St",
    "country": "USA"
  },
}

Of course, you'd replace the sample values with real values.

That's it, folks. You've now embedded the Integry widget. Now, go set up some integrations and see them run!