For a real quick start on app building, checkout the Hello app tutorial.
For a Generative AI powered app development experience, checkout the Freddy copilot.Notes:
- Most of the steps in this section require you to use the appropriate developer tool to craft your app.
- Apps built to work on the Freshworks platform are compatible with the latest and immediately preceding version of the following browsers: Google Chrome, Firefox, Edge, Safari
- Install prerequisites.
- Install the FDK + CLI.
- Create an app.
- Build the app.
- Test the app.
- Validate and pack the app.
- Submit the app.
Node Version Manager (NVM) enables you to install and work with multiple versions of Node.js. You can use NVM to install Node.
To install NVM,on Linuxon MacOSon Windows
Run the following command to install the cURL utility.
sudo apt install curl
Use the following cURL command to run the installation script.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
Note: This command automatically adds the requisite nvm configuration to the .bashrc file that is used to load the configuration to a terminal session However, if the .bashrc file is modified, the file should be refreshed for the configuration to be applied to a terminal session. To refresh the .bashrc file and load any nvm configuration changes in the current terminal session, run the source ~/.bashrc command.
To verify the NVM installation, run the following command.
Ensure that the installed nvm version is 0.39.3 or later. If you are on an earlier version of NVM, upgrade to version 0.39.3 or later.
To use NVM and install Node, run the following command.
nvm install 18
Note:With the latest FDK version, support for building apps on earlier versions of Node.js is unavailable.
Run the following command to verify the Node installation.
Note:On Windows, if the Node version is not displayed, run the nvm on command to enable NVM.
Run the following command to set the default Node version.
nvm alias default 18
On MacOS, install the build tools that are required to start using Node.
Run the following command to install the XCode CLI tool.
Run the following command to verify the installation.
Install the FDK + CLINotes:
- Ensure to use npm for CLI installation. Also, ensure to use the npm version that is shipped with Node. For information on supported Node versions, see . Use of any other npm version or use of alternative package managers such as YARN can affect the CLI installation and dependencies management.
- Uninstall the previous CLI version by using the npm uninstall fdk -g command.
To install the latest CLI version, run the following command.
npm install https://cdn.freshdev.io/fdk/latest.tgz -g
To install the CLI version that immediately precedes FDK 9.0.0, run the following command.
npm install https://dl.freshdev.io/cli/fdk.tgz -g
Note:This FDK/CLI version is compatible only with Node.js 14; it involves the use of platform version 2.2 for building apps. Support for Node.js 14.xx and platform version 2.2 will be deprecated by December, 2023. Ensure to migrate to FDK 9.0.0 before the deprecation. For any migration related information, see Migration guide.
Run the following command to verify the CLI installation.
Ensure that the installed CLI version is 9.0.0 or later. If you are on an earlier version, migrate to the latest FDK version.
Create an app
From the command line, navigate to the empty directory in which you want to create an app.
Run the fdk create command. A prompt to choose a product is displayed.
Select freshsales and press Enter. A prompt to choose a template is displayed.
Select your_first_app. A new app is created based on the your_first_app template.
Alternatively, navigate to the command line and run the following command to create a front-end app.
fdk create --product freshsales --template your_first_app
The following directories and files are created as a result of the fdk create command.
|Important:When building an app, do not modify the default folder/file names.
|Contains all the files required for a front-end app or the front-end component of an app.
|By default, contains the app logic to display a sample text and button (to open a modal) in the left navigation pane or in the Overview section of the Lead details, Contact details, Deal details, and Sales details pages.
|Contains the app icon. The icon file should be of SVG type with a resolution of 64 x 64 pixels.
|Contains the code to receive and send information between the Freshsales Classic UI and app instance.
|Contains the HTML code required for the app's UI, which is rendered in an IFrame.
|Contains the installation parameters and OAuth configuration files.
|Specifies all the installation parameters whose values are set when the app is installed. For more information, see App settings.
|Contains the files in which the app debugging information is captured.
|Contains all debugging information, warnings, and errors generated when an app is created, run, packed or validated.
|Contains details such as the platform version the app uses, product to which the app belongs, event listeners for serverless apps, SMI functions that can be invoked from the app's front end component, request templates that the app code uses, and npm packages (dependencies) that the app uses.
- The iparam_test_data.json file has been deprecated. Before testing the app, navigate to http://localhost:10001/custom_configs and enter appropriate values for the configured installation parameters.
- If you use React, Ember, Vue, or any other front-end framework, include the source files of your app in the src directory (which is auto-created when you use the your_first_react_app or your_first_vue_app template), to ensure quick app reviews.
Build the app
Important:After you build a global app that works across modules and publish it to our marketplace, in the subsequent versions of the app, you cannot remove modules (that is, downgrade the number of modules).
After creating the default front-end app files, to build the app,
Implement your app logic.
Navigate to app.js and replace the default code with your app logic.
Use our front-end methods to formulate your app logic.
For your app to react to app initialization, activation, or deactivation, use the appropriate app lifecycle methods.
For your app to retrieve the information about the different objects on the product UI and use the information to process the app logic, use the appropriate data method.
- For your app to react to the events (such as button clicks or changes/updates to field values) that occur on the product UI, use the appropriate event methods.
- For your app to trigger certain actions on the product UI, use the appropriate interface methods.
Use our developer toolkit to help solve specific requirements of your app.
To use external libraries, use our provision to include external libraries into your app files.
To place secure http calls from your app to a third-party domain, use the request method.
To enable communication between the various instances of your app, use the instance method.
To enable your app to access third-party resources that require an OAuth authentication, use the provision to place OAuth requests.
To persist and use data throughout your app’s lifecycle, use our data storage tools.
Test the app
Important:To test your app, use the latest version of Chrome.
From the command line, navigate to the directory that contains the app related files and run the fdk run command.
Log in to your Freshsales Classic account.
To the Freshsales Classic account URL, append ?dev=true.
Example URL: https://subdomain.freshsales.io/leads/1?dev=true.
To allow the Chrome browser to connect to the test server that runs on HTTP,
Navigate to Settings > Advanced > Privacy and security > Site settings > Insecure content.
In the Allow section, click Add and enter the account URL.
Example URL: https://subdomain.freshsales.io
From the homepage of your account, navigate to the appropriate location where your app is to be deployed, verify that the app is rendered and test your app’s function.
- The extent of app testing is captured through the code coverage summary. For apps to be successfully published in the Freshworks Marketplace, each component in the coverage summary should be at least 80%. For more information, see Code coverage.
- When testing your app, if you run into any issue, for a quick resolution from the support team, attach detailed logs of the output in your support ticket.
Validate and pack the app
To validate the app code for errors and pack the app for submission:Notes:
- In the following procedure, <DIR> is the directory path to the folder containing the app files that are validated for errors or packed.
- Ensure that at least one module apart from the common module is registered in the app manifest.
- A front-end app built for the common module is accessible from a product’s left navigation pane - either from the full-page-app placeholder or CTI app placeholder. For a front-end app built to work with only the common module, do not include caller_agent, call, caller_metrics, notification, or chat_user as the other module(s), if they are the only modules other than common. This is because the products that support these modules do not support app deployment on the left-navigation pane.
- Ensure that the iparams.json > <iparam-name>.modules contains only modules that are registered in the app manifest.
- If you are a developer who has been building apps for our ecosystem in the product-based landscape and migrating to the module landscape, when configuring iparams, ensure not to use the domain, api_key iparam types and the corresponding type_attributes. You can use the text type to obtain the domain value from your app users.
From the command line, navigate to the directory that contains the app related files and run the following command.
From the command line, run the following command.
fdk validate --app-dir <DIR>
If there are errors in the code, corresponding violations are displayed. Ensure to fix all violations before packing the app. Reference: App validation.
To fix all lint errors for which auto-fix support is available, run the following command.
fdk validate --app-dir -fix <DIR>
To pack the app for submission, run one of the following commands.
fdk pack --app-dir <DIR>
A dist/<app_directory>.zip file is generated.
Submit the app
To publish the app to the Freshworks Marketplace, navigate to the developer portal and upload the validated and packed app file. You can use the Login button in the header of this webpage to navigate to the developer portal.
For detailed app submission steps, see App submission process.