This documentation is for the v2 development platform, which is used to build apps for the new Freshdesk Mint UI. To build apps on the existing UI, use the v1 platform.
In this section, you'll learn how to build a simple Freshdesk app from scratch. We will cover the following steps:
Step 1: Install Node
Step 2: Install the CLI
Step 3: Create your First App
Step 4: Test your App
Step 5: Validate and Pack
You will need to install Node.js to use the Freshworks CLI. You can install node.js from here (only versions 6.10.x are supported). Once installed, you can verify the version using the following command:
$ node –v
Windows users should install all required tools and configurations using the following command. $ npm install --global --production windows-build-tools
Install the CLI
You will need to install the Freshworks CLI in your development machine to build, test, and publish apps on the Freshdesk Marketplace.
By installing and using the CLI, you agree to these Terms and Conditions.
If you are using Mac/Unix, run the following command:Copied Copy
|sudo npm install http://dl.freshdev.io/cli/fdk-4.2.1.tgz -g|
If you are using command prompt (Windows), run this command to install the CLI:Copied Copy
|npm install http://dl.freshdev.io/cli/fdk-4.2.1.tgz -g|
The -g command option ensures that your installation is global. With a global installation, you will be able to call commands and work on your apps and CLI from anywhere within your machine.
Once you have installed the CLI, you can verify the version using the following command:$ fdk version
Create your First App
In this section, you will learn how to create a simple app that is visible in the ticket details page. The app will show the Freshworks logo and the name of the ticket requester.
Open the terminal window, navigate to the directory (my_first_app) under which you want to create your app, and run the following command: $ fdk create --template your_first_app
Once create is successful, the my_first_app directory will be updated with the app files as shown below:
The icon.svg file in the app directory is the product icon that is created as part of the sample project. You can replace it with your own assets while building your app.
|app/||This directory contains all files (HTML, JS, CSS, images, library) that are required for the front end component of your app. The JS files must follow the ES5 standard.|
|app/icon.svg||The icon.svg file in the app directory is the product icon that is created as part of the sample project. You can replace it with your own assets while building your app. Icon file should be of the type SVG with a resolution of 64x64 pixels.|
|app/template.html||Contains the HTML required for the app’s UI which will be rendered in an iframe.|
|config/||This directory contains the installation parameters and OAuth configuration files.|
|config/iparams.json||This file contains all the parameters that the user will have to specify/set when they install the app. For more information on the installation parameters and related APIs, see Installation Parameters.|
|config/iparam_test_data.json||If you wish to test the app locally, you will need to specify parameter values here.|
|manifest.json||Contains some details about your app and its characteristics.|
|README.md||Any additional instructions or specifications the developer may want to outline can be mentioned here.|
For detailed walkthrough of the app, see Code Walkthrough.
Test your App
You can locally render and test your app from your developer machine.
- Open your console, navigate to your project folder, and execute the following command: $ fdk run
- Log into your Freshdesk account (if you do not have a Freshdesk account, sign up here).
- Go to ticket details page, in the address bar, append the URL with ?dev=true. For example, the URL should look like - https://subdomain.freshdesk.com/helpdesk/tickets/1?dev=true During local testing, you may see a shield icon in the browser address bar. Clicking on the icon will display a warning message. This warning message is displayed as the support portal runs on HTTPS while the server that is used for local testing runs on HTTP. Click "Load unsafe scripts" to continue testing.
- In the home page, select the Tickets tab from the left navigation bar and click any ticket. The rendered app will be displayed on the right side of the page as shown below.
Validate and Pack
Now that you have tested the app, you can check if the app is error-free and package it for submission.
- Navigate to your project folder and run the following command: $ fdk validate [--app-dir DIR] where DIR is a relative or absolute path to the project directory.
- Once the validation is successful, you can pack the project by running the following command: $ fdk pack [--app-dir DIR] where DIR is a relative or absolute path to the project directory. The pack command generates the file dist/my_first_app.zip file. This is the file that needs to be uploaded in the developer portal for publishing it to the Freshdesk Marketplace. For information on the submission process, see Types of Apps section under Marketplace Listing.