Custom Floating Window Demo App

This is a demo app that makes use of the Floating window app extension to render a persistent iframe inside Pipedrive. It makes use of Next.js for frontend and API routes, Prisma ORM for data storage and Pipedrive SDK for securely communicating with Pipedrive APIs. The app also showcases the use of cookies for session management inside the window.

We can split the configuration and installation steps into three stages. Let's get it running. ✨

Stage 1: Cloning the App, installing dependencies and making it publicly reachable

1. Clone the repository and switch to the app directory using the cd command.

2. After you have switched to the app directory using the terminal, install the required dependencies using the npm install command.

3. The app makes use of Prisma ORM to provide data storage. Based on the schema we have defined in prisma/schema.prisma you can create an actual database using the following command npx prisma db push.

% npx prisma db push
Environment variables loaded from .env
Prisma schema loaded from prisma/schema.prisma
Datasource "db": SQLite database "dev.db" at "file:./dev.db"

SQLite database dev.db created at file:./dev.db

🚀  Your database is now in sync with your Prisma schema. Done in 28ms

✔ Generated Prisma Client (4.6.1 | library) to ./node_modules/@prisma/client in 58ms

4. This command will create an SQLite database at prisma/dev.db.

5. The app will run on port 3000. For the floating window to work, the app URL should be publicly accessible. Use ngrok to expose port 3000 using the ngrok http 3000 command.

6. Now that we have performed the core steps in stage 1, the next step is to create an app in Pipedrive and add a floating window.

Stage 2: Creating a Pipedrive App with Floating Window App Extension.

1. Follow the app creation steps mentioned in the documentation but make sure that it is a private app (since it is for demo purposes only).
2. At the minimum, you must provide the app name and callback URL, which is http://localhost:3000/api/auth/callback.
3. Since we are creating a floating window app, we need to define the right scopes and the iframe URL in addition to the minimum required fields for a private app.
4. Make sure you select the following scopes - Deals (Full Access), Activities (Full Access), Contacts (Full Access), Search for all data and Phone calls integration.
5. Navigate to the App Extensions section and click on the + Custom Floating Window button under the Custom UI Extensions subsection.
6. Provide a name for the window along with the description and iframe URL. This URL is the one generated by ngrok, and it looks like this: https://example.ngrok.io/.
7. Make sure you choose the appropriate entry point option - Phone number and Calls tab. Once everything is filled, click on the Add Floating Window button. You can also find more details related to this step in the documentation.
8. Now that we have filled in all the details scroll to the top of the page and hit the Save button in the top right corner.

Stage 3: Configuring the .env file, installing and running the app

1. Open the newly created app in Marketplace Manager. Copy the client ID and secret credentials and fill it in the .env file of the app.
2. The app already contains a .env.example file, which can be used as a reference.
3. Run the npm run dev command in the root of the app directory to start the app.
4. To install the app in the account, navigate to http://localhost:3000/api/auth/login. Provide the required authorization and complete the installation.
5. Once the installation is complete, you can navigate to the Pipedrive account and click on the App icon from the App Dock section to render the floating window.
6. The control center can be accessed via http://localhost:3000/admin. It lets you provide a phone number to simulate an incoming call.