Events that occur when an app is installed from the Freshworks Marketplace 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 server.js file. When an app setup event occurs, the corresponding event listener invokes a callback method 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 server.js file.
2. In the exports block, enter the event (possible events: onAppInstall and onAppUninstall), corresponding callback, and callback function definition as follows:
   Note: Ensure to enter only one callback method for an event.
   Copied Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   exports = {
     events: [{ event: "eventName", callback: "eventCallbackMethod" }],
     eventCallbackMethod: function(payload) {
       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 ↓

Payload Attributes

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"
  }
}

The payload is a JSON object with the following attributes.

1
2
3
4
5
6
7
{
  "timestamp": 1583839686,
  "account_id": "12345",
  "domain": "https://sample.freshcaller.com",
  "event": "onAppInstall",
  "region": "US"
}

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}).

For example,

To register the onAppInstall event and the corresponding callback that allows completion of installation, use the following sample server.js content.

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

To register the onAppInstall event and the corresponding callback that disallows installation if a mandatory action fails, use the following sample server.js content.

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

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}).

For example,

To register the onAppUninstall event and the corresponding callback that allows completion of uninstallation, use the following sample server.js content.

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

To register the onAppUninstall event and the corresponding callback that disallows uninstallation, use the following sample server.js content.

1
2
3
4
5
6
7
8
exports = {
  events: [{ event: "onAppUninstall", callback: "onAppUninstallCallback" }],
  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"});
  }
}

Test

For information on how to test app setup events, see Test the App.