The Anatomy of an App — The Front-End
In our last post in the “Anatomy of an App” series, we looked at building a seamless install experience for your Freshworks app. Today, we will take a closer look at crafting a front-end experience for your app using the capabilities of our platform.
App Manifest
A manifest file packed with an app describes how and where the app is rendered within a Freshworks product. An app can be rendered in multiple locations within a Freshworks product, as defined by the “location” key in its manifest file. You could render the same HTML in each location, or shoot for variety. You could also pick a background location if your app does not require a visible component. You can select the app location based on the expectations of your users, the context your app will need to work within, and the amount of real-estate your app will require.
Your front-end app can pack its own script, style, and graphic assets within the app, or choose to pull them down from a URL (typically a CDN). All local assets, including the HTML, are pulled from the app folder of your App project.
The following example demonstrates an app manifest that requires the app to be accessible from two locations on the Ticket Details page in Freshdesk. The app’s packaged assets are also visible to the left.
App publishing tip: When choosing whether to pull assets from a CDN or pack them within the App, remember that any code that directly interacts with the SDK (using a client object) needs to be packed within the app. As described in our earlier post on the Freshworks Marketplace review process, our app reviewers will expect to be able to review this code before it goes live.
In-Context APIs
Your app is unlikely to run in complete isolation from the product front-end, and will therefore need to interact and exchange data with the page it loads within. For example, you will want to take note of who is currently logged in. You might also want to fetch the status of the current Freshdesk ticket or perhaps complete a particular action when the ticket status changes.
In-context APIs enable your app to do the following:
- Access data from the page your app renders in.
- Subscribe for events generated by user interactions on the page.
- Manipulate the user experience on the page.
Let’s try to build a simple app that does the following:
- Checks if the name of the logged-in user is “Baggins”
- Sets the ticket priority to “Urgent”
- Disables changing the priority
- Displays a notification threatening to release Orcs from Mordor if Mr. Baggins tries to assign the ticket to someone else.
We shall build this on top of the Ticket Background sample app. The app manifest, the code snippet from app.js, and a screenshot of the front-end experience for this app are displayed below. The complete app is available in our sample apps repository as well.
We used the Global Data API to fetch the logged-in user, the Interface APIs to set and disable ticket properties, an Event API to watch for when the assigned agent is changed, and another Interface API to display a notification.
Outgoing Requests
A rich app will want to exchange data with API endpoints, including those belonging to one of the Freshworks products themselves. As apps are served from Freshworks domains, outgoing requests from the front-end app will require working around the CORS restrictions a secure browser will dictate on your app. Handily enough, the platform provides a Request Proxy to help mitigate this problem. Just make a request using the built-in request client that directs requests via our proxy and you are covered.
API endpoints will expect your requests to be authenticated. In our last post in this series, we looked at three ways of capturing authentication information for your app as installation parameters. We recommend capturing these parameters as “secure” parameters to prevent them from inadvertently being exposed to app users. These parameters can then be referenced within request headers or the request body using our EJS-like templates. The proxy will ensure that the substitution takes place outside the browser before the request is made.
Let’s try extending the app we built earlier to use a secure installation parameter to make a search request against the TMDB movie database. We achieve this by:
- Adding https://developers.themoviedb.org as a whitelisted domain in the manifest.json file.
- Introducing api_key as a secure installation parameter in iparams.json
- Making a request to the API by referencing the api_key in a template.
Do checkout the complete app in our sample apps repository.
Build Your Own Front-End App
We have just completed a quick stroll through the various features the Freshworks platform supports on a front-end app. So pick a location for your app and grab a sample template from our CLI, or start with one of our many sample apps. We are excited to see where your unexpected journey with Freshworks front-end apps will lead you today.
Come back again soon for Part 3, where we take a close look at the back-end of your app and understand why Serverless Apps are such a hit on our platform.
