Events that occur when an app is installed from the Freshworks Marketplace, updated to the latest version, or uninstalled are termed as app setup events. An app setup event is a synchronous event and you can enable your app to decide whether the event should reach completion. For example, if a webhook has to be registered during app installation, you can use the app setup event to disallow installation if the webhook registration fails. You can configure event listeners in the manifest.json file. When an app setup event occurs, the corresponding event listener invokes a callback method defined in server.js and passes a standard payload to the method.

Configure Events

To register an app setup event and the corresponding callback:

1. From your app’s root directory, navigate to the manifest.json file.
2. Include the events attribute, specifying the app setup event (possible events: onAppInstall, afterAppUpdate, and onAppUninstall) and the corresponding callback methods as follows:
   Copied Copy

   1
   2
   3
   4
   5
   "events": {
       "<eventName>": {
           "handler": "<eventCallbackMethod>"
       }
     }

   Note: Include only one callback method for an event.
   

3. Navigate to the server.js file.
4. In the exports block, enter the callback function definition as follows:
   Copied Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   exports = {
     // args is a JSON block containing the payload information
     // args["iparam"] will contain the installation parameter values
     //eventCallbackMethod is the call-back function name specified in manifest.json
     eventCallbackMethod: function(args) {
       console.log("Logging arguments from the event: " + JSON.stringify(payload));
       // If the setup is successful
       renderData();
       // If there is an error during the setup
       renderData({message: "Error message"});
       }
     };

   EXPAND ↓

When an app setup event occurs, a payload is passed to the callback method.

1
2
3
4
5
6
7
8
9
10
11
{
  "account_id" : "value",
  "domain" : "value",
  "event"  : "value",
  "region"  : "value",
  "timestamp"  : "value",
  "iparams" : {
      "Param1" : "value",
      "Param2" : "value"
    }
}

onAppInstall

When an app user clicks the Install button corresponding to the app, the onAppInstall event is triggered.
For app installation to reach completion, in the callback function definition, use the renderData() method without any arguments.
To disallow app installation if a mandatory action fails, use an error object as the argument - renderData({error-object}).

error-object attribute

For example,

Register the onAppInstall event by using the following sample manifest.json content:

1
2
3
4
5
"events": {
  "onAppInstall": {
    "handler": "onAppInstallCallback"
  }
}

Define the corresponding callback that allows completion of installation by using the following sample server.js content:

1
2
3
4
5
6
7
exports = {
  onAppInstallCallback: function(payload) {
    console.log("Logging arguments from onAppInstallevent: " + JSON.stringify(payload));
    // If the setup is successful
    renderData();
  }
}

Define the corresponding callback that disallows installation if a mandatory action fails, by using the following sample server.js content:

1
2
3
4
5
6
7
exports = {
  onAppInstallCallback: function(payload) {
    console.log("Logging arguments from onAppInstallevent: " + JSON.stringify(payload));
    // If there is an error during the setup, see screenshot below
    renderData({message: "Invalid API Key"});
  }
}

1
2
3
4
5
6
7
8
9
10
11
{
  "account_id" : "13",
  "domain" : "https://web.freshteam.com",
  "event" : "onAppInstall",
  "timestamp" : 1496400354326,
  "region" : "US",
  "iparams": {
    "username": "Rachel",
    "url": "https://web.freshteam.com"
  }
}

afterAppUpdate

After you upload a new version of your app, in the Apps gallery > MANAGE APPS an Update button is displayed next to the app (for admin users). If the admin clicks the button and updates the app, the new app version is installed and the afterAppUpdate event is triggered.

In your new version’s app files, you can:

1. Subscribe to the event by registering the event and its corresponding callback function.
2. Use the registered callback function to carry out certain app actions. To let an app user continue using the updated version, in the callback function definition, as part of the app logic, use the renderData() method without any arguments.
3. If any mandatory action that must be carried out as part of the app setup (update) fails, if the mandatory parameters that are required to carry out the app actions are unavailable, or in any such error scenarios, use the registered callback function to revert to the earlier installed app version. To perform this, use an error object as the argument of the renderData() method - renderData({error-object}).

For example,

Register the afterAppUpdate event by using the following sample manifest.json content:

1
2
3
4
5
"events": {
    "afterAppUpdate": {
        "handler": "afterAppUpdateCallback"
    }
}

Define the corresponding callback that does not interrupt usage of the updated app, by using the following sample server.js content:

1
2
3
4
5
6
7
exports = {
    afterAppUpdateCallback: function(payload) {
        console.log("Logging arguments from afterAppUpdate event: " + JSON.stringify(payload));
        // To continue usage of the updated app.
        renderData();
    }
}

Define the corresponding callback that reverts the app to the earlier installed version if a mandatory action fails, by using the following sample server.js content:

1
2
3
4
5
6
7
exports = {
    afterAppUpdateCallback: function(payload) {
        console.log("Logging arguments from afterAppUpdate event: " + JSON.stringify(payload));
        // To revert to earlier installed app version.
        renderData({message: "Updating to the latest version of the app failed due to network error."});
    }
}

onAppUninstall

When an app user clicks the Uninstall button corresponding to the app, the onAppUninstall event is triggered.
For app uninstallation to reach completion, in the callback function definition, use the renderData() method without any arguments.
To disallow app uninstallation if a mandatory action fails, use an error object as the argument - renderData({error-object}).

error-object attribute

For example,

Register the onAppUninstall event by using the following sample manifest.json content:

1
2
3
4
5
"events": {
    "onAppUninstall": {
      "handler": "onAppUninstallCallback"
    }
  }

Define the corresponding callback that allows completion of uninstallation by using the following sample server.js content:

1
2
3
4
5
6
7
exports = {
    onAppUninstallCallback: function(payload) {
      console.log("Logging arguments from onAppUninstallevent: " + JSON.stringify(payload));
      // If all mandatory uninstallation actions are successful
      renderData();
    }
  }

Define the corresponding callback that disallows uninstallation if a mandatory action fails, by using the following sample server.js content:

1
2
3
4
5
6
7
exports = {
    onAppUninstallCallback: function(payload) {
      console.log("Logging arguments from onAppUninstallevent: " + JSON.stringify(payload));
      // If there is an error during uninstallation
      renderData({message: "Uninstallation failed due to network error"});
    }
  }

1
2
3
4
5
6
7
8
9
10
11
{
  "timestamp" : 1496400354326,
  "account_id" : "13",
  "domain" : "https://web.freshteam.com",
  "event" : "onAppUninstall",
  "region" : "US",
  "iparams": {
    "username": "Rachel",
    "domain": "https://web.freshteam.com"
  }
}

Testing

Note: For testing, we recommend that you use the latest version of Chrome browser.

You can test your app on your computer by simulating events, and you can test different scenarios by directly modifying the payload.

Note:
As the testing is only a simulation of events, an actual event will not be recorded in the back end. If you need an actual conversation/contact to be created, it is recommended that you publish your app as a custom app and test the operation manually.

To simulate events for testing, follow the given steps.

1. From the command line, navigate to your project directory and run the following command $ fdk run

2. In the browser, enter the following URL to test the app: http://localhost:10001/web/events.

3. Select the event that you want to simulate.

4. Once you select an event, the corresponding event payload is displayed. Edit the values and then click Simulate. When you edit the payload, ensure that you adhere to the JSON format.