Insight lifecycle

An Insight can exist in three different states. These stages are used to determine how and if the Insights should be shown to the user. The different states are based on the relevance for the user and if the user has seen the Insight previously.

The Insights that are presented on the Insights Feed inside the WebUI are synchronized with the Insights you receive through the Insights API. That means if an Insight is acknowledged by the user in our WebUI, this change will be reflected in the Insights API. The inverse is also true; when you mark an Insight as acknowledged the same change will be reflected in the WebUI.

Created

We create Insights depending on trigger criteria which are defined for each Insight category. Once an Insight is created it is visible in the WebUI, or can be consumed through the API and shown to the user. The recommendation is that all Created Insights to be shown to the user and to highlight them in some way, to nudge the user to review the Insights.

Acknowledged

An Insight is set to be acknowledged when the user has seen it or interacted with it (i.e. the user has become aware of the message that the Insight conveyed). The Acknowledge Insight endpoint is used to mark an Insight as acknowledged. You can choose when to set an Insight to acknowledged, We recommend to when to acknowledge an Insight are as follows:

  • Mark an Insight as acknowledged if the user clicked on the Insight.
  • Mark an Insight as acknowledged if the Insight was visible within the viewport.
  • Mark all Insights on the page as acknowledged, as soon as the user visits the page in your application showing Insights.

We also recommend showing acknowledged Insights to the user, but without any highlighting or nudging for the user to re-visit them.

Resolved

An Insight should be resolved when its purpose is served and it is no longer relevant for the user. the Resolve Insight endpoint is used to mark the Insight as resolved. We recommend the Insight to be marked as resolved when:

  • The user explicitly removed an Insight from your UI.
  • The Insight is no longer valid because the underlying events that triggered the creation of the Insight are not true anymore (for example, "New subscription Found" Insight is automatically resolved if the subscription is deleted by the user.) Such Insights are automatically resolved by us.
  • When the user has taken all the recommended actions (and thus resolved underlying triggers) mentioned in the Insight. Such Insights are also automatically resolved by us.

We recommend that resolved insights are not shown in your UI. However, the Insights are still available from the API, which makes it possible to create an Insight history or archive page if required.