Your First App

The goal of this tutorial is to help you understand the basics of app development. Here, you will build an app using the Freshworks platform.

For this tutorial, we will choose the your_first_app template. This app will be visible on the Ticket Details page and will display 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.

To get started, open the terminal window and navigate to the directory under which you want to create your app. Note that this directory must be empty.

$ fdk create --template your_first_app

The app is created with the following directories and files.

Code Walkthrough

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

README.md

Developers need to maintain a proper README file so when there is a change in ownership of the code base, a new developer can easily understand the 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 is used to ensure backward compatibility when a new version of the framework is released.

The product key is used to specify the product and location in which the app is rendered. This app is to be rendered in the ticket_sidebar location in the Ticket Details page. url and icon specify the path (from the /app directory) to the template and icon files rendered in that location.

You can view the complete list of where apps can be rendered in the App Locations section.

app/icon.svg
This is the app icon specified in the manifest file. It is displayed at the right-hand side of the Ticket Details page. The app icon file is of SVG type with a resolution of 64 x 64 pixels.

app/freshdesk_logo.png
This is the Freshdesk logo 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 which 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 ↓

The template.html file includes the following:

  • fresh_client.js - This JS library enables the app to communicate with the parent page. The file 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 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 update this stylesheet so that the app remains consistent.
  • style.css - App specific stylesheet that contains style information for 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 UI 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 are reloaded.

To enable the app to refresh itself at the right time, the ticket page triggers an app.activated() event. Apps in the ticket_sidebar location are initially in a minimized state. When the agent expands the app for the first time on the page, the app receives the app.activated() event. If the agent navigates to another ticket and then expands the app (for the first time on that page), the app.activated() event is triggered again.

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

As apps are rendered in an IFrame, the app and underlying page communicate through APIs by 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

The app specific stylesheet which contains style information for various UI components of the app. For this app, the file contains style information for the Freshdesk logo which is part of the app as well as the div block that contains the image and 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 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.