Getting Started

Our inline SDK embeds the integration views within your own app so that you have full control over how you want to structure the HTML or apply custom CSS.

Before you start: Before you get started, make sure you have your Integry Credentials. Please get in touch with your account contact or apply for them here.

Embed Code

Integry will provide JavaScript code snippet to embed inside your app. This snippet contains important information about the procedure to configure seamless integration. Before you proceed embedding the JavaScript snippet, please make sure that you have the following information ready with you:

  1. App key
  2. App secret
  3. User ID of the user in your application setting up the integrations
  4. Bundle ID

Here are the details of these:

App key: This is the ID that uniquely identifies an app. This is generated automatically for every app on Integry’s side. You can find this from the authorizations section of your app.

App Secret: The app secret is also a uniquely generated key for every app that works like a password for it. This goes hand-in-hand with the app key.

User ID: This is usually a UUID (Universal Unique Identifier) that is stored at your end against each user of your app. A user’s app credentials enable you to extract their corresponding user ID.

The User ID and App Secret are combined to make a Hash encryption, that is used inside the JS code snippet that we provide you. This can be generated in PHP like this:

echo hash_hmac('sha256', $userID, $appSecret);

In the above code, you need to replace the userID and appSecret variables with their actual values before running the command.

Bundle ID: This is the ID of the bundle in which all your integration templates are saved. Once the code snippet is embedded inside your app, all the templates in this bundle will be rendered in your app as available integrations.

To retrieve the Bundle ID, visit the bundles page. By hovering over the bundle you can see the Bundle ID in the URL in browser status bar as shown below. 

You can also click the bundle and when you are directed to the bundle-info page, the URL contains the ID of that bundle as shown below.

Let’s dive into understanding the details of the complete snippet code.

1. Initialize Server Side Variables

    $appKey = '<YOUR-APP-KEY>';
    $userID = '<USER-ID>';
    $appSecret = '<YOUR-APP-SECRET>';
    $bundleId = '<YOUR-BUNDLE-ID>';

userID can be any value such as an email, a number or a UUID (Universal Unique Identifier). It will uniquely identify a user. There are some scenarios where integrations might be shared among multiple users in your app (such as the admins of the app). In that case, you can use account ID as the value of the user ID; this will give all the users editing access to these integrations.

2. Embed JavaScript Code

Embed the following code at the end of your web page before closing body tag. This will bring in a list of available templates and already configured integrations within your application so that users can either add a new integration or edit an existing integration.

    window.onload = function () {
               app_key: "<?php echo $appKey ?>",
               user_id: "<?php echo $userID ?>",
               hash: "<?php echo hash_hmac('sha256', $userID, $appSecret); ?>",
               bundle_id: "<?php echo $bundleId; ?>",
               bundle_instance_id: "<?php echo $bundleInstanceId; ?>",
               callback: callbackFunc,
               callback_render_integration_row: callbackFunc_Render_Integration_Row,
               callback_render_template_row: callbackFunc_Render_Template_Row,
               render_templates_container: 'templates',
               render_integrations_container: 'integrations',
               x_integry_configs: {
                view_container: 'intcontainer',
                view_url: '',
                "app_auth": {
                  "api_key": "<API-KEY-OF-CURRENT-USER>"

Embed Code JavaScript Methods and Variables - Definition

render_templates_container: ID of a container div to contain list of templates. You need to create an empty container and assign the ID of that container to this variable. 

render_integrations_container: ID of a container div to contain list of already configured integrations. You need to create an empty container and assign the ID of that container to this variable. 

x_integry_configs.view_container: ID of a container div to render integration form. This div should also have the template code to actually render the form. See the section "3. Compose Integration View" below for details.

x_integry_configs.view_url: A URL of a page where you want to render integration form. It could a separate page or the same page where you are showing list of templates. If this is a separate page, SDK embed code should be included in the source code of that page too. Also, the container div having ID specified in x_integry_configs.view_container should be on that page.  

x_integry_configs.app_auth: Here you need to provide the authentication details. For now, we support API-KEY. This API-KEY is generated by your app for currently logged in user.

The bundle_instance_id is generated internally by Integry against the current user and bundle. It helps us identify the current user and the integrations they have set up already. We associate all created user integrations to a bundle_instance_id.
Storing and sending bundle_instance_id back to SDK is an optional process. In most of the cases, you do not need to save the bundle_instance_id in your application as when this is not sent to the SDK, we internally lookup for an existing bundle_instance_id for the current user if it already exists and uses it.
If no bundle_instance_id exists for the current user, we create a new one internally. However, this bundle_instance_id is returned in integration creation response to SDK's "callback" method. You can optionally keep a mapping of this bundle_instance_id against the current user. If you store this bundle_instance_id and send back to the SDK, we will use this bundle_instance_id to save integrations instead of looking up ourselves.
It is a useful option when you want to keep a mapping of the bundle_instance_id not only with user id but also some other objects. For example, if your app is a task manager app, you may want your users to create integrations on per project/board level and create a new bundle_instance_id for each project's integrations. In such cases, you have an option to enforce the Integry SDK to create a new bundle_instance_id when a user is setting up their first integration in a native entity (project, board, form, etc).
To enforce the SDK to create a new bundle_instance_id, you can pass bundle_instance_id = -1.

The following snippet shows the callback functions and their definition. 

   function callbackFunc(data) {
      // show any success message here

   function callbackFunc_Render_Integration_Row(integration) {
      var row = $('<tr class="ui-widget-content jqgrow ui-row-ltr"></tr>')
         .append($('<td></td>').attr('width', 50).append('<img width="50" src="' + integration.icon_url + '" />'))
         .append($('<td></td>').append('width', '70%'))
            .append('<a href="' + + '">Edit</a>')
            .append($('<a></a>').attr('href', (integration.status === 'ACTIVE') ? integration.disable_link : integration.enable_link).append((integration.status === 'ACTIVE') ? "Disable" : "Enable").attr('data-op', (integration.status === 'ACTIVE') ? 'disable' : 'enable'))


            .append($('<a></a>').attr('href', integration.delete_link).append("Delete").attr('data-op', 'delete'))
      return row;

   function callbackFunc_Render_Template_Row(template) {

      var img = template.branding_app.icon_url;
      var html = '<th scope="row" class="col-md-6"> \
                     <a class="media align-items-center" href="#"> \
                    <img alt="Image" src="' + img + '" class="avatar rounded avatar-sm" /> \
                    <div class="media-body"> \
                        <span class="h6 mb-0">' + + '</span> \
                        <span class="text-muted">' + template.description + '</span> \
                    </div> \
                     </a> \
                  </th> \
                  <td> \
                     <a href="' + + '" class="btn btn-success">Add</a> \
                   </td> ';

      var row = $('<tr class="bg-white"/>');
      return row;

CallBack Methods - Definitions


This method is called when an integration is saved. 

function callbackFunc(data)
      //write method details here

At this point you can perform post-save actions like:

  • Show success message to user
  • Redirect to another page etc.

callbackFunc_Render_Template_Row: This method is called to render each individual integration template. 

function callbackFunc_Render_Template_Row(template)
      //write method details here

In this method you can prepare output html. Each time this method is called, a template object is passed to it. A template object contains the following properties:

  • template.description
  • template.icon_url

callbackFunc_Render_Integration_Row: This method is called to render each individual integration instance (an already configured integration).

function callbackFunc_Render_Integration_Row(integration)
      //write method details here

In this method you can prepare output html for the integrations already created by the user. Each time this method is called, an integration object is passed to it. An integration object contains the following properties:

  •  This property reflects the name of the integration. You can use it where you want to show integration name to the user.
  • This property provides the edit link of an integration. You can use it to let the user edit an integration.
  • integration.icon_url: This property provides the URL address of the integration app icon. You can use it if you want to display the application icon on your interface.
  • integration.disable_link: This property provides the link that lets the user disable an integration.
  • integration_delete_link: This property provides the link that lets the user enable an integration.
  • integration.status === 'ACTIVE': This property shows that an integration is in active state.
  • integration.status === 'INACTIVE': This property shows that an integration is disabled.
  • integration.status === 'AUTH_MISSING': This property shows that the authentication of an integration is not found or has been deleted.
  • integration.status === 'CREATION_IN_PROGRESS': This property shows that an integrations is being created and has not been completely setup yet.
  • integration.status === 'CREATION_FAIL': This property shows that an integration creation process has failed and the setup was unsuccessful.
  • integration.task_execution.status === 'in-progress': This property shows that an integration is currently running its first time setup. It is important to know that the first time setup task is not the same as the integration creation process. For example, the first time setup task usually performs the first time data import after the integration has been setup successfuly.
  • integration.task_execution.status === 'success': This property shows that the last task performed by this integration was processed successfully.
  • integration.task_execution.status === 'fail': This property shows that the last task performed by this integration failed to process.

The above code will result an output similar to the following:

3. Compose Integration View

Now on the web page where you want the integration form to be rendered or where you have placed “x_integry_configs. view_container” HTML dom element, you can compose your own structure of html using our available SDK’s tokenized variables. Learn more about these variables, here.

Following is an example of how you can structure your own HTML using these variables. You will need to have the following code inside your application page that you configured as view_url. Say the value of x_integry_configs. view_container was intcontainer:

<div id="intcontainer" class="hidden">
   <div class="wrapper">
      <a id="integrations-wrapper"></a>
         <%= template.template_description %>
      <div class="steps">
         <div class="hide">
            <%= integration_name_field %>
         <% for(var i = 0; i < steps.length; i++) {  %>
            <%= steps[i].content %>
         <% } %>
      <div class="footer">
         <%= footer %>

Following is how it might look like inside your app:

4. After saving the integration

When you save the integration, you can pass your own function to the callback parameter. The widget will call this function whenever a user sets up an integration. More on this callback function, here

5. Include our SDK

Now that every thing is setup correctly, include the following script tag before closing body tag.

<script src="">


This will load our SDK, which will pick up all your configurations defined above and kick off the process of loading templates, integrations, rendering the integration form etc.

For more queries!

Did this answer your question?