@pipedrive/custom-app-surfaces-sdk

Custom UI extensions SDK

This SDK provides interactivity between custom UI extensions and Pipedrive.

Learn more about custom UI extensions from Developer documentation.

npm install --save @pipedrive/custom-app-surfaces-sdk

Table of contents

• Initialization
• Commands
  • Show snackbar
  • Show confirmation dialog
  • Resize
  • Get signed token
  • Open modal
  • Close modal
• Events
  • Surface visibility
  • Close custom modal

Initialization

In order to display a custom UI extension to a user, this SDK has to be initialized. In the iframe request, query id attribute is passed, which has to be provided to the SDK constructor. The SDK will try to read it from the URL query. If the URL is modified (e.g. with redirects), then it has to be passed manually.

import SurfaceSDK from '@pipedrive/custom-app-surfaces-sdk';

// SDK detects identifier from URL and uses default surface size
const sdk = await new SurfaceSDK().initialize();

// Pass in id manually and provide surface size
const sdk = await new SurfaceSDK({ identifier: '123abc' })
  .initialize({ size: { height: 500 } });

Commands

Commands can be invoked with the execute method. On successful command execution, promise resolves. On error, it rejects.

sdk.execute(/* ... */)
  .then((data) => {
    // handle data
  }).catch((err) => {
    // handle error
  })

try {
  const data = await sdk.execute(/* ... */)
} catch (err) {
  // handle error
}

Show snackbar

Shows snackbar with provided message and link

Parameters

Example

await sdk.execute(Command.SHOW_SNACKBAR, {
  message: 'Action completed',
  link: {
    url: 'https://app.pipedrive.com',
    label: 'View'
  },
});

Show confirmation dialog

Shows confirmation dialog with provided title and description

Parameters

Response

Example

const { confirmed } = await sdk.execute(Command.SHOW_CONFIRMATION, {
  title: 'Confirm',
  description: 'Are you sure you want to complete this action?'
});

Resize

Resizes custom UI extension with provided height and width

Custom panel - only height can be changed and the value must be between 100px and 750px.

Custom modal - both height and width can be changed. The minimum height is 120px and the minimum width is 320px . The maximum height and width are limited to the user's browser dimensions.

Parameters

Example

await sdk.execute(Command.RESIZE, { height: 500 });

Get signed token

A new JSON Web Token (JWT) that is valid for 5 minutes will be generated. It can be verified using the JWT secret which you can add from Marketplace Manager when configuring a surface. If it’s not specified, use app’s client secret instead. JWT contains Pipedrive user and company ids.

JWT can be used to assure that the surface is loaded by Pipedrive. It can be passed to your API requests and be verified on the server side. Note that JWT expires in 5 minutes so use this command to get a new one.

Response

Example

const { token } = await sdk.execute(Command.GET_SIGNED_TOKEN);

Open modal

Opens an JSON modal, custom modal or a new Pipedrive Deal, Organization or Person modal

JSON modal action

Parameters for JSON modal

Response

Example

const { status } = await sdk.execute(Command.OPEN_MODAL, {
  type: Modal.JSON_MODAL,
  action_id: 'Open settings'
});

Custom modal

Parameters for custom modal

Response

Example

const { status } = await sdk.execute(Command.OPEN_MODAL, {
  type: Modal.CUSTOM_MODAL,
  action_id: 'Open settings',
  data: {
    item: 'xyz'
  }
});

New deal modal

Parameters for new deal modal

Response

Example

const { status, id } = await sdk.execute(Command.OPEN_MODAL, {
  type: Modal.DEAL,
  prefill: {
    title: 'Important deal'
  }
});

New person modal

Parameters for new person modal

Response

Example

const { status, id } = await sdk.execute(Command.OPEN_MODAL, {
  type: Modal.PERSON,
  prefill: {
    name: 'Some name',
    organization: 'Some organization'
  }
});

New organization modal

Parameters for new organization modal

Response

Example

const { status, id } = await sdk.execute(Command.OPEN_MODAL, {
  type: Modal.ORGANIZATION,
  prefill: {
    name: 'Some organization',
  }
});

Close modal

Closes an active modal window; applicable only for custom modal.

Example

await sdk.execute(Command.CLOSE_MODAL);

Events

Subscribe to events triggered by user.

const stopReceivingEvents = sdk.listen(event, ({ error, data }) => {
  // if error is present, handle error
  // handle data
});

stopReceivingEvents(); // Call this function to stop receiving events

Custom panel visibility

Subscribe to custom panel visibility changes that are triggered by the user.

Panel surface - user collapses or expands the panel

Response

Example

sdk.listen(Event.VISIBILITY, ({ error, data }) => {
  // handle event
});

Close custom modal

Subscribe to custom modal events that are triggered by this SDK's CLOSE_MODAL command or user interaction with the custom modal.

Panel surface - user closes the custom modal

Example

sdk.listen(Event.CLOSE_CUSTOM_MODAL, () => {
  // handle event
});