Storing data in Happeo Pages

The WidgetSDK exposes 2 important functionalities: storing content and configurations in Happeo. The difference between the two is that the content field is a string that gets indexed in Happeo search and the configuration does not, being a key-value-based storage system.

For detailed information, please refer to the WidgetSDK Github wiki page (https://github.com/happeo/widgets-sdk/wiki/API-requests).

Storing content

To store content in Happeo, use the getContent() function to retrieve the stored data. Additionally, you can use setContent() to set the data. Note that this is a string field and if you store complex data into it, remember the indexing of data. Instead of storing a stringified object with keys, consider using a stringified array.

Storing configuration

Configurations are not indexed, but are available in the data payload for the page viewers. This means that you should not store anything there that users could not see. For this, use the JWT token to store the data on a remote server and use the server for such operations.

For example, if your widget integrates with Service X and Service X has an API key, do not store the API key in the JavaScript source or in the content or configurations. The custom widget source is public and everything else is accessible to the user. In this case, use the call getJWT() to fetch the user token and identify the user in your remote server. The shared secret is available on the custom widgets page.

Using external data sources

The custom widget JavaScript source is always public to the internet; therefore, you should never store any credentials in the JavaScript. To make safe and secure requests to external services, we recommend using the JWT token delivered to the widget through the WidgetSDK.

The token can be accessed by the getJWT() request and is signed with the shared secret available in the custom widget edit page (admin panel). The token includes the following information:

{
    user: {
        id: "happeo-id",
        primaryEmail: "userPrimaryEmail"
    },
    organisation: {
        id: "organisation-id"
    }
}

Below is an example flow on authorizing a user to an external service using OAuth through your widget. To get the token to the user, there are 2 options:

1. Deliver the OAuth token to the user as a cookie and let your JavaScript use the OAuth token to make remote calls.
2. Store the OAuth token in your database and use the JWT token data to fetch the correct token for the correct user. This should be used if the token is not a full OAuth token, for example, if it doesn't expire.