Building an App

A Freshdesk app project typically consists of the following

The logo.png file in the assets folder is the Freshdesk logo that is created as part of the sample project. You can replace it with your own assets while building your app.

Folder/File Description
app/ This folder contains three files:
  • app.js
  • style.scss
  • template.html
app/app.js The brains of your app. The app will react to user input and data based on what you've defined in this file.
app/style.scss Contains the style sheets for the app
app/template.html Contains the HTML elements required for building the UI of the app.
assets/ This folder will contain the logos and other image assets your app may need. Supported file formats are:
  • PNG
  • JPG
  • GIF
  • CSS
  • JS
You can reference files from the asset folder in the app.js, style.scss, and template.html files by using the following format: {{'filename.png' | asset_url}} Where, filename.png is a file in the assets folder.
config/ This folder contains at least two files:
  • iparam_en.yml
  • iparam_test_data.yml
An additional iparam file will be required for each language that you support. Based on the language in the support portal of the customer, the relevant iparam file will be used. The English version will be displayed by default.
config/iparam_en.yml This file contains all the parameters that the user will have to specify/set when they install the app.
config/iparam_test_data.yml If you wish to test the app locally, you will need to specify parameter values here.
manifest.yml Contains some details about your app and its characteristics. Any additional instructions or specifications the developer may want to outline can be mentioned here.
Creating a new project

To create a new app project, run the following command: $ frsh init [project folder name]

If project folder name is not provided, then the project template is created in the current directory itself if it is empty.

Local Testing

If you wish to locally test your apps - that is, run the app on your local developer machine, view the rendered app in your Freshdesk developer account - then, follow these steps:

  1. Make sure you have this Chrome Extension installed.
  2. Now, open your console and in your project folder, execute the following command to run the SDK server: $ frsh run
  3. With the browser extension installed and the local SDK server running, visit your Freshdesk account and go to the ticket details/contact details page where you’ve enabled your app. You will be able to see the code you wrote on your local machine running inside your account.

    During local testing, you may see a shield icon in the browser address bar as shown below: 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.

If your app is modifying data during testing, it will be changed/reflected in the account where the local testing occurs. In such cases, it is recommended that you create a separate Freshdesk account solely for developing apps.

Validating and Packaging apps

The final step to building your app is to package it. There are two commands related to packaging:

  1. Validation: To run all the validations to verify if there are any problems in the app project. $ frsh validate
  2. Packaging: To package the project and ready it for submission to the Marketplace. $ frsh pack

Pack also runs all validations, but fails on the first validation issue faced. On a successful run, pack generates the file dist/<foldername>.zip file. This is the build that needs to be uploaded in the developer portal for submitting to the Marketplace.

Once the app has been packaged, you can submit it for review via the Freshdesk Developer Portal.

Best Practices

The following best practices MUST be followed if you want your app to be listed in the public Marketplace. We also strongly recommend that you follow them even if you are building a custom app i.e an app that is only installed on your account.

  • Do not directly access UI elements within the app directly, always use this.$container and then find the element. jQuery(this.$container).find(element) It's possible that two apps can have an element with same ID. If customer has installed both the apps then there might be a collision between the elements and an action in first app might trigger the second app instead of first app.
  • Do not declare global variables within the app, all variables should be app/function specific. This is for the same reason as the first point.
  • Please avoid any irrelevant console logging. Apart from being unnecessary, if customer information is printed in the console, it could result in security or privacy issues.