Embed the Actions widget in your app

In this tutorial, we will:

• Install the SDK
• Authenticate your app
• Create an SDK instance
• Initialize the SDK instance
• Get the callback URL
• Run the action

If you haven't already, please Try App Actions in under 5 minutes first because this builds on that.

Install the SDK

The SDK can be installed in a number of ways:

• Install the npm module using the package manager of your choice:
  

  npm i -S @integry/actions-sdk-beta

  yarn add @integry/actions-sdk-beta

• Include the Universal Module Definition SDK file on your page just before the closing </body> tag:
  

  <script src="https://unpkg.com/@integry/actions-sdk-beta/dist/umd/index.umd.js"></script>

  <script src="https://cdn.jsdelivr.net/npm/@integry/actions-sdk-beta/dist/umd/index.umd.js"></script>

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

For Integry to recognize your requests, you need to set up authentication by providing your App Key, Secret, User ID, 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 > Embed.

App Secret

It's a unique secret key for every app and is used for authentication. You can also find it in Account Settings > Embed.

User ID

We use the User ID to associate and return actions that a user sets up. We don't assign any additional credentials to your users. We simply use whatever unique identifier you pass in this field.

Hash

This is calculated using the User ID and App Secret to authenticate the SDK embed 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).

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: The app key and secret must be stored securely and should not be embedded in HTML where they can easily be leaked.

Create an SDK instance

<script>
let sdkInstance;
window.addEventListener("DOMContentLoaded", async function() {
            sdkInstance = new IntegryJS({
                // populate the following with your values
                appId: "",
                userId: "",
                hash: "",
            });
        }
</script>

Customizing the SDK instance

Inside the curly braces { ... }, you can provide configuration options to customize the behavior of the SDK instance. For example:

sdkInstance = new IntegryJS({
embedConfig {
        title: "Actions",
        multipleActionInstances: true,
        allowMultipleAccounts: false,
        actionSetupType: "SAVE-AND-EXECUTE",
        buttonTitle: "Save",
        tags: ["Production", "Beta"]
            }
});

• title: Set the title of the SDK instance.
• multipleActionInstances: Decide whether users can set up the same action multiple times.
• allowMultipleAccounts: Specify if users can connect to the same app with multiple accounts.
• actionSetupType: Choose how action setup is handled (e.g., "SAVE" or "SAVE-AND-EXECUTE").
• buttonTitle: Define the label for the submit button in the setup interface.
• tags: Specify which actions are displayed based on matching tags. Pass tag names in array.

Passing objects in SDK

All the objects that you have used to map action fields are passed in this way.

objects: {
"object 1" { 
      property1: "value1", 
      property2: "value2", 
      // ... other properties
                   }, 
"object n" {
      property1: "value1",
      property2: "value2",
      // ... other properties
                   },
          }

Note: Remember to put the code inside the curly braces of embedConfig

objects: {
"Contact": {
"id": 1,
"firstName": "Alice",
"lastName": "Johnson"
},
"Issue": {
"title": "Sample Issue",
"description": "This is a description of the sample issue",
"assignee": "User_1",
"status": "Open",
"due_date": "2023-06-01T00:00:00Z"
},
}

Initialize the SDK instance

First, add a <div> in the <body> for the widget. It doesn't matter where you place it unless you're planning to show the widget in-line.

<div id="x-integry-container"></div>

Next, assuming you want users to click a button to setup an action, add that to the <body>.

<button onclick="renderSDK()">Setup an Action</button>

In order for the button to work, add this function in a <script> tag.

function renderSDK() {
    sdkInstance.init({
        containerId: "x-integry-container",
        renderMode: IntegryJS.RenderModes.MODAL,
    });
}

Note: If you want to view SDK in a modal, pass IntegryJS.RenderModes.MODAL. If you want to view SDK inline, pass renderMode: IntegryJS.RenderModes.INLINE

At this point, assuming everything is in order, you should be able to click that button, open the Actions widget, see all the actions in your account, click on an action, login to the action's app, and setup the action. If you open it again, and click the same action again, you won't have to login to the app again, and you will see your previous configuration (field mappings, etc.) which, if you want, you can modify and save again.

Why don't you try all that, and then we'll get to the fun parts?

Get the callback URL

When a user sets up an Action, we return a URL you can call with your payload to execute the Action. We need to get and store the callback URL for that action instance (so we can call it later).

For that, we will subscribe to the setup action event because it emits the callback URL.

var callbackUrl = "";
sdkInstance.eventEmitter.on("did-setup-action", (event) => {
    callbackUrl = event.callbackUrl;
});

You can save the URL on your end against that step, for instance, in a workflow, or against an event in your app. You can then call it whenever the workflow executes, or the event occurs, to run the action.

In order to test this, just open the action you already setup and save it (or setup another one!). The event will fire every time you save.

Run the action

Finally! The SDK is all locked and loaded, the action's been setup, and you've got the callback URL. How do you run the action?

First, we will append the app key, encoded hash and encoded user ID to the callback URL to create an action URL.

actionURL = callbackURL +
"?app_key="+ encodeURIComponent(appKey) +
"&hash=" + encodeURIComponent(hash) +
"&user_id=" + encodeURIComponent(userId);

Next, we will prepare the object payload that will be sent from your app to the 3rd party app as part of the action. This can feel a bit complicated but, don't worry, we're almost there!

Note: You have to manually run the action if actionSetupType: "SAVE" in the embedConfig. If actionSetupType: "SAVE-AND-EXECUTE", you wouldn't need to manually run the action. The SDK will initiate a call to the action URL once you save the setup. It will use the object payload associated with the action to make this call, in effect, executing the action.

Let's assume a Lead was generated by your app, and now you want to export that to Mailchimp because your user has setup it's 'Add Subscriber' action.

When they did that, they mapped some fields from your Lead object to the action's fields.

Note: This assumes that Lead was the object assigned to this action.

In order to run the action, you need to send the Lead object payload in the HTTP call. Integry will transform the data to Mailchimp's format using that mapping.

You can see the Lead object payload by going to Account Settings > Objects and clicking the object.

Feel free to customize the payload to exactly how data is represented in your app so that you don't have to do any transformations before sending it to us. If you do make a change though, try setting up the action again and you'll notice that the new/modified fields show up immediately.

Finally, make a POST call to the action URL with the object payload (including the user's real data in those fields!) in the body. Assuming everything is in order, you should immediately get a 2xx response if it worked, or a 4xx response if the app returned an error.

That's it! You just installed the SDK, authenticated your app, created and initialized an SDK instance, got the callback URL for an action's instance, and ran the action with your app's data. Good job!

Next, let's see how usage is logged so you can easily debug errors.