App Setup Events

When a user installs or uninstalls an app from Marketplace, the following events are triggered:

The app setup events are synchronous, which means that the callback method for the event can decide whether to allow or disallow the completion of the event. For example, during installation, you want to register a webhook or store some initial values in a database. If these actions fail, the app may not function correctly and so the callback should disallow installation.

Payload

When an app setup event occurs, the corresponding method in the server.js file is invoked and the following payload is passed to the app.

Copied Copy
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" } }
EXPAND ↓

Attribute Type Description
account_id number Freshdesk account ID
domain string Freshdesk account domain
event string Name of the event
region string Region where the app is installed, will be either "US", "EU", "EUC", or "AUS"
timestamp number App Installation timestamp in the epoch format
iparams object Installation parameters
Registration

When an app setup event occurs, the appropriate method should be called for which an event listener is added. This is done in the following format.

server.js Copied Copy
1
2
3
4
5
6
7
8
9
10
11
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 ↓

Note:
1. Include the event and callback definition in the exports block.
2. Include only one callback method for an event.

onAppInstall

When you click the Install button, the onAppInstall event occurs and then the registered callback method is executed.

  • Use the renderData() method without any arguments for the app installation to proceed.
  • renderData();
  • Use the renderData() method if an error occurs in the callback. Here, the message should be of string type and should not exceed 60 characters.
  • renderData({message: "Installation failed due to network error."});

    The following format is used to include the event in the server.js file.

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

    Sample code with failure response

    Copied Copy
    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, see screenshot below renderData({message: "Invalid API Key"}); } }
    Sample Payload
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    { "account_id" : 13, "domain" : "sample.freshdesk.com", "event" : "onAppInstall", "timestamp" : 1496400354326, "region" : "US", "iparams": { "username": "Rachel", "url": "http://sample.freshdesk.com" } }
    EXPAND ↓
onAppUninstall

When you click the uninstall icon, the onAppUninstall event occurs and then the registered callback method is executed.

  • Use the renderData() method without any arguments to uninstall the app.
  • renderData();
  • Use the renderData() method if an error occurred in the callback. Here, the message should be of string type and should not exceed 60 characters.
  • renderData({message: "Uninstallation failed due to network error."});

    The following format is used to include the event in the server.js file.

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

    Sample code with failure response:

    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    exports = { events: [ { event: "onAppUninstall", callback: "onAppUninstallCallback" }], onAppUninstallCallback: function(payload) { console.log("Logging arguments from onAppUninstall event: " + JSON.stringify(payload)); // If there is an error during the setup, see screenshot below renderData({message: "Uninstallation failed due to network error."}); } }
    Sample Payload
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    { "timestamp" : 1496400354326, "account_id" : 13, "domain" : "sample.freshdesk.com", "event" : "onAppUninstall", "region" : "US", "iparams": { "username": "Rachel", "domain": "sample.freshdesk.com" } }
    EXPAND ↓
Testing

You can easily test your app in your machine by simulating events. Also, 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 ticket/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 local testing, follow the procedure outlined below.

  1. In your console, navigate to your project directory and execute the following command. $ fdk run
  2. Open your browser and enter the following URL to start testing your 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.
  5. If the event is successfully simulated, you will see Success displayed.
  6. If there is a problem, you will see Failed displayed. Check if the payload is valid and then resume testing.

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.