Your First App

The goal of this tutorial is to help you understand the basics of app development using the Freshworks app development platform.

To do this, we will create a new app and understand how it works. Every time you create a new app using the Freshworks CLI, you have to choose a starting template. For this tutorial, we will choose the your_first_app template. This app will be visible in the ticket details page and will show the Freshdesk logo along with the name of the ticket requester as shown below:

Create

Note:
Before proceeding, ensure that you have installed Node.js and the Freshworks CLI.


Let’s get started by creating the app. First open the terminal window, and navigate to the directory under which you want to create your apps. Note that this directory must be empty. $ fdk create --template your_first_app

The app will be created with the directories and files shown below:

Code Walkthrough

Let’s take a closer look at the files that were created.


README.md

It is considered a sacred pact amongst developers to maintain a proper README file so that when there is a change in ownership of the code base, the new developer will have an easier time understanding various nuances of the code.


manifest.json

The manifest file is used to store configuration information for the app.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
{ "platform-version": "2.0", "product": { "freshdesk": { "location": { "ticket_sidebar": { "url": "template.html", "icon": "icon.svg" } } } } }
EXPAND ↓

The platform-version key is automatically generated and used to infer the platform version that your app uses. This will be used to ensure backward compatibility when a new version of the framework is released.

The product key is used to specify the product and the location in which the app will be rendered. This app is to be rendered in the ticket_sidebar location that is in the ticket details page. The URL and icon are used to specify the path (from the /app directory) to the template file and icon that will be rendered for that location.

You can see a full list of where apps can be rendered by visiting the App Locations section.


app/icon.svg
This is the app icon that was specified in the manifest file. It will be displayed in the right hand side of the ticket details page. It is expected to be of type SVG with a resolution of 64x64 pixels.


app/freshdesk_logo.png
This is the Freshdesk logo that is displayed by the app.


app/template.html
Apps in the new Freshdesk UI are rendered inside an iframe. This file contains the HTML markup for the app. It is a simple template that displays an image along with text that is dynamically generated in the app.js file.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
<html> <head> <script src="https://static.freshdev.io/fdk/2.0/assets/fresh_client.js"></script> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.0/jquery.min.js"></script> <script src="app.js"></script> <link rel="stylesheet" type="text/css" href="https://static.freshdev.io/fdk/2.0/assets/freshdesk.css"> <link rel="stylesheet" type="text/css" href="style.css"> </head> <body> <div class="logo"></div> <p id="apptext"></p> </body> </html>
EXPAND ↓

template.html includes the following:

  • fresh_client.js - This JS library enables the app to communicate with the parent page. This is mandatory as the app runs in an Iframe and needs to communicate with the parent page in order to access data, listen to events, and trigger interface actions.
  • JQuery - This is used by app.js in line 9 where it adds text to the #apptext element.
  • app.js - Establishes a connection with the parent page to retrieve information about the ticket requester.
  • freshdesk.css - Importing this css file ensures that the app maintains a UI that is consistent with the parent page. Anytime the parent page is redesigned, we will update this stylesheet to ensure that the app remains consistent.
  • style.css - App specific stylesheet that contains style information for the various UI components of the app.


app/app.js

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$(document).ready( function() { app.initialized() .then(function(_client) { var client = _client; client.events.on("app.activated", function(payload) { client.data.get("contact") .then(function(data) { $("#apptext").text("Ticket created by " + data.contact.name); }) .catch(function(e) { console.log("Exception - ", e); }) }); }) });
EXPAND ↓

The new Freshdesk web interface is built as a single page application. Single page applications do not reload the entire page when the context is changed, only the relevant sections are modified. If an agent is already on a ticket page and navigates to a new ticket, only certain sections of the page will be reloaded.

To enable the app to refresh itself at the right time, the ticket page will emit an app.activated() event. Apps in the ticket_sidebar location start off in a collapsed state. When the agent expands the app for the first time in the page, the app will receive the app.activated() event. If the agent navigates to another ticket and then expands the app (for the first time in that page), the app.activated() event will be emitted again.

When the ticket page is loaded for the first time, the app.js registers for the app.initialized() method. In the callback, it receives a client object and registers for the app.activated() method. The core logic of the app, which is to retrieve the ticket requester’s name and append it to a string is contained within this callback.

Since apps are rendered within an iframe, the app and the underlying page communicate through APIs and this is made possible using the client object. The client.data.get('contact') method uses a Data API to retrieve the ticket requester details and parses it to get the requester’s name.


app/style.scss

App specific stylesheet that contains style information for the various UI components of the app. Contains the style information for the Freshdesk logo that is part of the app as well as the div block that contains the image and the accompanying text.

Copied Copy
1
2
3
4
5
6
7
.logo { background: url("freshdesk_logo.png"); background-repeat: no-repeat; background-size: contain; height: 25px; margin-top: 25px; }
Next Steps

Now that you understand the basic components of an app, why not build your own?

If you run into any issues, you can reach out to us at support@freshdesk.com or via the chat icon at the bottom right corner of the screen.

Log in with your Freshdesk account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.