Building Side Panel Embedded Applications

Learn how to build an embedded application that displays in the right-hand side panel of Procore’s UI.

Introduction

This guide explains how to build a side panel embedded application that appears in Procore’s right-hand side panel. Side panel apps are context-aware and launch from specific tools or views within the Procore UI.

To get started, first create a Developer Portal account and app.

Add a New Side Panel Component

  1. In your Developer Portal app, expand the Embedded Components section.
  2. Click Add Component.
  3. For Type, select Side Panel.
  4. In the URL field, enter your app’s base web address (e.g., https://example.com/1234/12).
  5. Select from the supported Side Panel Views.
    • Use the Side Panel Views menu to select one or more tools and views where your app will be accessible.
  6. (Optional) Add custom URL parameters.
  7. Click Save Component.

Define Setup Instructions and Post-Installation Notes

You must provide setup instructions and post-installation notes to help Procore users complete the installation and setup of your application within a Procore project.

Clear post-installation guidance is required to ensure users know exactly what to do after installing your app. For example, they may need to sign up for an external account, configure settings on your platform, or complete authentication steps before the app is ready to use.

These instructions are shown to the user immediately after installation and remain accessible in the App Management section of the Procore Admin tool.

Follow these steps to define setup instructions:

  1. Expand the Instructions and Post-Installation Notes section.
  2. In the Instructions URL field, enter a link to your company’s support site or a page with step-by-step setup instructions.
  3. In the Instructions Page Name field, enter the label you want to display as the hyperlink text for the Instructions URL.
  4. In the Post-Installation Notes field, add any additional details or reminders users need to complete setup successfully.

Create Initial App Manifest Version

After configuring your component, save your App Manifest and create a version number.

  1. Click Save at the top of the page.
  2. Click Create Version.
  3. Enter a semantic version (e.g., 0.1.0).
    • Versions must be three integers separated by dots (x.x.x).
  4. Click Create.

Your version will be saved with the status Ready for Testing. As you continue development, click Save Version to capture new changes.

Use postMessage to Access Procore Context

The Procore Side Panel feature supports the MessageEvent interface and the Window.postMessage() method to determine the Procore context in which a side panel application instance is running. The information retrieved from a message event sent from the parent window includes the following data fields:

  • Company ID = event.data.context.company_id
  • Project ID = event.data.context.project_id
  • Resource ID = event.data.context.id
  • View = event.data.context.view

To access context data using the MessageEvent interface, add an event listener to your page and use the postMessage method to initialize communication with the parent window. The example code below demonstrates how to retrieve context data from the message event object. Note the use of conditional statements with the postMessage method to account for Multiple Procore Regions. Be sure to account for all regions where your application needs to retrieve Procore context. As new Procore regions become available, update your postMessage code to support them.

window.addEventListener('message', (event) => {

  const obj = event.data;
  if (obj.type === "setup") {
    const company_id = obj.context.company_id;
    const project_id = obj.context.project_id;
    const view = obj.context.view;
    const resource_id = obj.context.id;
  }
});

if (document.referrer === "https://app.procore.com/") {
  window.parent.postMessage({ type: 'initialize' }, "https://app.procore.com/");
}
if (document.referrer === "https://us02.procore.com/") {
  window.parent.postMessage({ type: 'initialize' }, "https://us02.procore.com/");
}
if (document.referrer === "https://uk01.procore.com/") {
  window.parent.postMessage({ type: 'initialize' }, "https://uk01.procore.com/");
}

In the example above, the targetOrigin parameter of the postMessage method is set to the specific origin of the parent window. The targetOrigin parameter specifies the origin of the window that should receive the message. Always provide a specific, fully-qualified URI in the targetOrigin parameter to ensure the best security.

For additional information, see the postMessage() method documentation.

Supported Message Events

Aside from the “setup” message event fired when your app starts, additional events are fired at different life cycles of the side panel app. All these events are sent as postMessages from Procore to your app’s window.

You can listen for “message” events and filter by the data “type”.

window.addEventListener('message', (event) => {
  const obj = event.data;
  if (obj.type === "sidepanel:app:visible") {
    // Do something when the app is visible.
  }
  if (obj.type === "sidepanel:app:hidden") {
    // Do something when the app is hidden but still running.
  }
  if (obj.type === "sidepanel:app:destroy") {
    // Do something when the app is about to be removed from the DOM.
  }
});

Reference: Supported Side Panel Views

Refer to the full list of supported view keys and URL patterns in the Side Panel View Key Reference.

Test and Validate in Development Sandbox

We recommend testing each app version in a development sandbox environment. See Installing an Application in the Development Sandbox for step-by-step instructions.

Promote Updated Sandbox Manifest to Production

Once you’ve completed testing, you can promote the sandbox version to production. See Managing App Versions & Update Notifications to learn how.