Getting Started

Our inline SDK embeds the integration views within your own web 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 web 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. Bundle ID
  4. User ID of the user in your application setting up the integrations

The App key and App secret can be fetched from the App Credentials section of your app as shown below. 

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

<?php
    $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.

<script>
    window.onload = function () {
         integryAppSDK.load({
               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: 'https://yourwebsite.com/integration-form-page',
                "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.

bundle_instance_id:
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. 

<script>
   function callbackFunc(data) {
      console.log(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(integration.name).attr('width', '70%'))
         .append($('<td></td>')
            .append('<a href="' + integration.link + '">Edit</a>')
         )
         .append($('<td></td>')
            .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($('<td></td>')
            .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">' + template.name + '</span> \
                        <span class="text-muted">' + template.description + '</span> \
                    </div> \
                     </a> \
                  </th> \
                  <td> \
                     <a href="' + template.link + '" class="btn btn-success">Add</a> \
                   </td> ';

      var row = $('<tr class="bg-white"/>');
      row.append($.parseHTML(html));
      return row;
   }
 
</script>

CallBack Methods - Definitions

callbackFunc: 

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.name
  • template.description
  • template.icon_url
  • template.link

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:

  • integration.name
  • integration.link
  • integration.icon_url
  • integration.disable_link
  • integration_delete_link

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

We have written a detailed guide that explains different methods and how they are used. 

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>
      <p>
         <%= template.template_description %>
      </p>
      <div class="steps">
         <div class="hide">
            <%= integration_name_field %>
         </div>
         <% for(var i = 0; i < steps.length; i++) {  %>
         <div>
            <%= steps[i].content %>
         </div>
         <% } %>
      </div>
      <div class="footer">
         <%= footer %>
      </div>
   </div>
</div>

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="https://app.integry.io/w/assets/sdk-1.3.js">

</script>

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?