Custom UI extensions (BETA)

📘

Custom UI extensions is currently in BETA. As this feature is still in development, it's subject to change. Please send your feedback to [email protected].

NB: Please ensure you test this feature on a draft app, not an approved/public one.

What are custom user interface extensions?


A custom user interface (UI) extension is an area in Pipedrive’s UI that extends an app’s functionality by loading any contextual web content within an embedded iframe. This allows apps to display their own content directly inside different Pipedrive views.

We have three custom UI extension points:

Custom panel

Custom panel

A custom panel is an iframe embedded inside a sidebar panel in the detail view of Deals, People, and Organizations.

Custom modal

Custom modal

A custom modal is an iframe embedded in a modal that opens when triggered by the user from various menus and links inside Pipedrive.

Custom UI for app settings

Custom UI for app settings

Custom UI for app settings is an iframe embedded in a surface that gives users easy access to user settings for your app.


How can custom UI extensions be used?


Custom UI for app settings

An example of a custom panel displaying related information to a Pipedrive deal

Custom UI extensions can be used in a multitude of ways. You now have near-complete freedom to showcase any content you want as you will be able to load any contextual web content within the iframe solution for your Pipedrive use case.

Some examples include displaying related information to Pipedrive entities like documents/invoices/proposals, multimedia, email marketing data, text messages, data visualization, customer support cases, contact management, multi-step forms, etc.

Custom UI extensions could also be used to extend Pipedrive’s own functionality such as calculating data based on Pipedrive information and detecting duplicate deals.


How do custom UI extensions work?


A custom UI extension is an embedded iframe within Pipedrive’s UI that showcases your app’s content in the form of a contextual, external webpage.

The webpage, which is going to be embedded has to be hosted externally on the app service’s side. It has to have its own publicly accessible URL along with frontend and backend capabilities. Any JS framework and language to build the frontend and backend of the custom UI extension can be used.

11651165

Data flow for custom UI extensions

When a custom UI extension gets loaded or reloaded, an iframe request with query parameters will be sent. This should be validated in the app’s backend using the provided JWT. The webpage from the URL you provide in Marketplace Manager should then render while the SDK initializes with id. Pipedrive will now load the iframe with your external webpage.

The iframe request will contain the following query parameters:

Parameter

Explanation/value(s)

Examples

userId

userId=12345

companyId

companyId=54321

token

JWT that identifies which user and which PD company is loading the iframe

token=xxxxx.yyyyy.zzzzz

id

Unique ID/runtime token for the iframe that has to be passed to the SDK

id=56789

resource

deal/person/organization

resource=deal

view

details

view=details

selectedIds

Entity ID that shows the ID of the selected entity

selectedIds=3

The JWT (token) has to be validated server-side. You will have to initialize the SDK with the provided id.

  • The JWT secret can be specified in Marketplace Manager when adding your custom UI extension. If no value is added in the Marketplace Manager, we will use the client secret as the JWT secret value by default.

Note: The SDK will try to read the id from the URL itself. As such, in most cases, the id will not have to be passed manually. It has to be manually passed only if you modify the iframe URL, e.g. with redirects.


SDK


📘

Want to see what the code for custom UI extensions looks like? Check out our example apps on GitHub and run them yourself.

To add a custom UI extension, it is mandatory to use the SDK to initialize the webpage and communicate with the main Pipedrive window.

SDK contents

Our SDK contains the following features, of which you’ll find the code examples in our Github SDK readme.

Verification
Our SDK verifies the iframe using the unique extension id.

Actions
Snackbar
A small "popup" that displays information to the user and disappears after some time.

Confirmation modal
A prompt that enables the user to verify an item. All contents can be customized with the result being passed back to the SDK.

Resize panel
The ability to adjust the height of the iframe. The height can also be provided when initializing the SDK, so it is already displayed with your defined height.

Get signed token
A new JSON Web Token (JWT) that is valid for 5 minutes will be generated.

JSON modal
A popup modal that allows a JSON modal action. At the moment, this cannot be prefilled.

Custom modal
A popup modal with an iframe embedded in it. You can open a custom modal with prefilled data, use the CLOSE_MODAL command to close the custom modal and subsequently, receive an update with the CLOSE_CUSTOM_MODAL event. View our example app to see how this works.

New deal/person/organization modal
A popup modal that enables the user to create a Deal, Person or Organization where the most important fields, such as names, can be prefilled.

Events
Panel collapse and expand
Apps can subscribe to panel expand/collapse events to find out when a user changes the visibility of a custom panel.

Close modal
Apps can subscribe to CLOSE_CUSTOM_MODAL events to find out when a user closes a custom modal.


What to consider when building custom UI extensions?


You have to host your own web content
The web content to be displayed within the iframe for all custom UI extensions has to be hosted externally on your side, along with all frontend and backend capabilities.

Design of your web content
Please consider the design of your web page and how it would look within the Pipedrive web app. Check out Pipedrive’s design assets and make use of any components from there.

Height and width
When defining the height and/or width of a custom UI extension, please consider the actual size of the page to be rendered in the iframe and avoid overflow: auto in CSS.

Custom panel name and icon

App panel

For custom panels, your custom panel’s name and icon will be displayed in the header of the panel. As your app's icon will be displayed next to the title of the custom panel and it'll be minimized, please consider how recognizable your icon is when it's displayed in the custom panel.

The icon can be added via the General information section of Marketplace Manager, while the custom panel's name can be added via the App extensions section.


Custom UI extensions in App approval process


What if my app has already been approved?
If you already have an app or an integration available in the Pipedrive Marketplace, please create a new test app for the development of custom UI extensions to make sure they work properly.

Remember that any changes saved when updating a public app in the Marketplace Manager will all be immediately visible to your app users.



Did this page help you?