Developing a Marketplace App

Phase 1: Build a custom app for your own workspace

The first step to building a Marketplace App is to build a Custom App. Please note, usage of the Copilot SDK is required for Marketplace apps.

Testing session tokens

Many Marketplace Apps require access to the session token, which includes information about:

The currently logged-in internal user.
The current client-user. Note, when client ID is present it doesn’t necessarily mean the client is the logged in user. It can be:
1. A logged-in client.
2. A client that’s being previewed by an internal user.
The company ID associated with the client.
The workspace ID where the app is installed and is being rendered.

For more information on session tokens, visit the session token section of the guide to Setting up the SDK.

During development you’ll likely be developing on [localhost:3000](http://localhost:3000) and by default you won’t have a session token to work with. In order to generate a session token for testing purposes you can take the token from the URL of the iFrame rendered in your Copilot workspace. For instance, if we’d like to test a token that has a client ID we can take the following steps:

Once your custom app has been created, visit the installed version of your app in your client portal.
Using the element inspector, find the iFrame element where your app is rendered. The simplest way to do that is to search for the following selector in the element inspector: iframe[src*="YOURAPPURL.com"]. If you’re using a domain supplied by Vercel, for example, that selector would be: iframe[src*="vercel.app"].
Take the token query parameter from the iFrame URL and paste it into your localhost URL. For instance, if the iFrame app URL is: https://myapp.vercel.app?token=12345 then your localhost URL should read: http://localhost:3000?token=12345.
Call the getTokenPayload function in the SDK to get the values in the token.

Phase 2: Update the code to work on any workspace

Once you’ve got a functioning app, it’s time to make sure the code is general enough to support a variety of workspaces. Let’s go through some of the considerations necessary to accomplish this.

Workspace customization

Each workspace has various customizations and metadata associated with it, like the name of the workspace, brand colors, fonts, and logo images on the customization page. You can fetch these workspace customizations by calling the retrieveWorkspace function in the SDK and using the supplied values in your app.

Some values are simply to implement, like the workspace name. Let’s get into some of the more advanced values here.

Using color values

Colors are returned as a valid CSS color value and can be injected into your app in your chosen way of authoring CSS.

Color	Description
colorSidebarBackground	The background color of the left hand sidebar of a client portal.
colorSidebarText	The text color in the left hand sidebar of a client portal.
colorAccent	The accent color chosen by the workspace admin.

Fetching fonts

Fonts are returned as a human readable font label. In order to load the appropriate font you’ll have to do a little parsing of the font family name and fetch the font file from Google Fonts. For instance, let’s say the retrieveWorkspace endpoint returns font: "Rubik Scribble"; In order to fetch this font you’ll need to replace the space with a plus sign and inject it into the following code:

import Head from 'next/head'
import type { CopilotAPI } from 'copilot-node-sdk';

export function FontDownloader({ copilot }: { copilot: CopilotApi }) {
  const workspace = await copilot.retrieveWorkspace();
  const fontFamily = workspace.font.split(' ').join('+');
	return (
	  <Head>
			<link rel="preconnect" href="https://fonts.googleapis.com">
			<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
			<link href=`https://fonts.googleapis.com/css2?family={fontFamily}&display=swap` rel="stylesheet">
		</Head>
	);
}

Using images

Images are also returned from the workspace endpoint. These images can be helpful to reinforce the branding of the workspace the app is installed in. Before using these images, consider the “Client branding” option that lets a workspace owner toggle between displaying their own branding and displaying their clients’ branding.

Image	Description
squareIconUrl	A cropped logo that is guaranteed to be a square.
fullLogoUrl	The unprocessed logo image.

Handling the “Enable companies” toggle

Each Copilot workspace has the option to enable or disable companies, this is particularly useful when a service business targets individual people rather than corporate clients. When the retrieveWorkspace endpoint returns isCompaniesEnabled: false, your app should avoid displaying companies in its UI.

Relying on custom fields

Custom fields are a powerful way to associate clients with arbitrary data. However, when developing marketplace apps you can no longer rely on custom fields that are saved on clients in your development workspace. To fetch the list of custom fields that are available in a workspace, call the List Custom Fields API endpoint.