App development process

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
  1. Install prerequisites.
  2. Install the FDK + CLI.
  3. Create an app.
  4. Build the app.
  5. Test the app.
  6. Validate and pack the app.
  7. Submit the app.

Install prerequisites

The FDK is built as a Node.js application and it requires installation of the following components in your system.

  • Node Version Manager/NVM (Optional)
  • Node.js v18.13.0 or later

Note:If Node.js v18.13.0 or later is installed already on the system, skip this section and proceed with the FDK installation via NPM step.

There are following two methods to install the prerequisites.

Use this method to install Node.js v18.18.2 and the FDK together on your system via Homebrew (on MacOS and Linux) or Chocolatey (on Windows).

Note:If you already have Homebrew or Chocolatey installed on your system, skip this section and proceed with the FDK installation step. Otherwise, refer to the following information on installing Homebrew or Chocolatey.

  • For MacOS or Linux: Install the latest version of HomeBrew.

  • For Windows: Install the latest version of Chocolatey.

    Note:If Chocolatey is already installed on your system, run the following command to run PowerShell scripts in the current session, bypassing any execution policy restrictions: Set-ExecutionPolicy Bypass -Scope Process -Force;

Install the FDK + CLI

Based on the installation information provided in the prerequisites section, refer to the steps in the following tabs to install FDK.

Notes:
  • If you already have the FDK v9.0.0 or later, and Node.js v18.13.0 or later installed on your system, you can skip this step and proceed to create an app.
  • If you already have Node.js v18.13.0 or later installed on your system, refer to the information available in the via NPM tab to install FDK.
  1. Run the following command to enable Homebrew to access the Freshworks CLI repository and auto-configure the CLI.

    brew tap freshworks-developers/homebrew-tap
  2. Run the following command to install the latest CLI version.

    brew install fdk

    This command performs the following tasks:

    • Creates the custom_node_location folder in your system.

      Note:The terminal displays the location where the custom_node_location folder is created.

    • Installs Node.js version 18.18.2, compatible with the CLI, into the custom_node_location folder.

    • Installs the Freshworks CLI in the same custom_node_location folder.

  3. Add the following command to the appropriate environment file (.bash_profile, .bashrc, or .zshrc) on your system. This command loads the necessary settings required for using the CLI commands.

    source "$(brew --repository freshworks-developers/homebrew-tap)/path.bash.inc"
  4. Apply the changes made to the environment file in the current terminal by either closing and reopening the terminal or by running the source ~/.{file_name} command. For example, source ~/.bashrc.

  5. Run the following command to verify the CLI installation.

    fdk version

    Ensure that the installed CLI version is 9.1.1 or later.

Notes:
  • To uninstall the currently installed CLI version, use the brew uninstall fdk command.
  • After uninstalling the CLI, to remove the CLI repository from the list of tapped repositories in your Homebrew configuration, use the brew untap freshworks-developers/homebrew-tap command.
  • The Developer portal and SDK Terms of use apply to the use of the CLI.

Create an app

  1. From the command-line, navigate to the empty directory in which you want to create an app.

  2. Run the following command, to create and set the requisite environment configuration for developing a global app.

    fdk config set --scope local global_apps.enabled true

    The configs.json file (with the global_apps attribute) is created in the app directory.

    Note: As the configuration is scoped to local, the FDK treats only the app in the current app directory as a global app. As a result, during app building, all global app features and validations are applicable only to the app in the current app directory.

  3. Run the fdk create command. A prompt to choose a template is displayed.

  4. Select common-starter-template. A new app with the following directories/files is created based on the template.

    Directories and files that the create command generatesDirectories and files that the create command generates for common-starter-template
    Directory/FileDescription
    Important:When building an app, do not modify the default folder/file names.
    app/Contains all the files required for a front-end app or the front-end component of an app.
    app/index.htmlContains files to render the front-end components of an app. This is the first page that is loaded when the app is activated. When building an app, if the app uses Data method, Request method, Installation settings, or Data store, update the index.html file with the following client JS resource:
    <script async src="{{{appclient}}}"></script>
    app/scripts
    (All js files are ES6 compatible)
    Contains all the javascript files required to support the front-end functionality of an app.
    app/scripts/app.jsPlaceholder file for your app logic (app code).
    app/stylesContains the styles required for the front-end components of an app.
    app/styles/styles.cssContains CSS rules that are incorporated to HTML files, when referenced.
    app/styles/imagesContains images that can be used in the app.
    app/styles/images/icon.svgContains the app icon. If you intend to extend the app, you can replace the icon.svg file. The icon file should be of SVG type with a resolution of 64 x 64 pixels.
    config/Contains the installation parameters and OAuth configuration files.
    config/iparams.jsonSpecifies all the installation parameters whose values are set when the app is installed. For more information, see App settings.
    log/Contains the files in which the app debugging information is captured.
    log/fdk.logContains all debugging information, warnings, and errors generated when an app is created, run, packed or validated.
    manifest.jsonContains details such as the platform version the app uses, module on which the app is deployed, placeholders for the front-end app rendering, request templates that the app code uses, and FDK version used to build, test, validate, and pack the app.
    README.mdContains additional instructions, information, and specifications.

    Note:To ensure quick app reviews, if you use React or any other front-end framework, include the source files of your app in the src directory (which is auto-created when you use fdk create and select react-starter-template to create your app files).

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,

  1. Configure the app manifest.

  2. Implement your app logic.

    1. Navigate to app.js and code your app logic.

    2. Use our front-end methods to formulate your app logic.

    3. Use our developer toolkit to help solve specific requirements of your app.

  3. Use Crayons (the Freshworks component library) to construct your app’s UI.

  4. Configure app settings.

Test the app

Important:To test your app, use the latest version of Chrome.

  1. From the command line, navigate to the directory that contains the app related files and run the fdk run command. The FDK starts the local test server. The test URLs to access the product UI, the App Settings page (or Custom installation page), and the URL to the serverless events simulation page are displayed.

  2. Navigate to the system settings page at http://localhost:10001/system_settings. All modules configured in the App manifest are listed.

  3. In the system settings page,

    1. Select the modules for which you want to test the app logic. The Enter account URL section is displayed, with a prompt to enter the account URLs for all selected modules.
    2. In the Enter account URL section, enter valid account URL(s) for the product(s) to which the selected modules belong. During app testing, this URL plays the role of the currentHost. Based on the currentHost, the currentHost.subscribed_modules and currentHost.endpoint_urls are determined. In the response payload of the currentHost data method, the determined values are used.
    3. Click Continue.
  4. If you have configured installation parameters for the app, the App Settings page is displayed at http://localhost:10001/custom_configs. Enter appropriate values for the installation parameters and click Install. Note:If you have not configured any installation parameters, a page is displayed with information on the configured system settings. A message stating that the app does not have an installation page is displayed.

  5. Log in to the Freshworks product account where you want to test the app deployment.

  6. To the default account URL displayed in the address bar, append ?dev=true.

    Example URL: https://subdomain.freshservice.com/helpdesk/tickets/1?dev=true

  7. Navigate to the appropriate location where the app is intended to be deployed, verify that the app is rendered, and test the app’s function.

Notes:
  • 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, chat_conversation, 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.
  1. From the command line, navigate to the directory that contains the app related files and run the following command.

    fdk validate

    Or

    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.

  2. To fix all lint errors for which auto-fix support is available, run the following command.

    fdk validate --app-dir -fix <DIR>
  3. To pack the app for submission, run one of the following commands.

    fdk pack
    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.