Decibel Insight

Forcing Retention

For the need to be able to retain particular sessions that may fall outside of the standard retention sampling method (Settings > Edit Property  > Property > Sampling), this can be achieved by making use of the Decibel setRetention JavaScript end-point, which will ensure that if a users’ session is not within the retention sample, and therefore not being retained, it will begin to be retained from the point of calling the end-point.

The above percentage are of visitors which will be considered for retention; a session which is not within the retention rate will be deleted within processing. This allows clients to collect all user interaction during a session and determine at a later stage if the session is worth retaining through the ‘setRetention’ Decibel API call.

The endpoint that is required for forcing retention can be seen below:

decibelInsight('ready', function () {
    decibelInsight('setRetention', true); 

Or you can add this to all pages

decibelInsight('ready', function () {

 if (location.href === "..........") {   // page href logic
    decibelInsight('setRetention', true);



You can use the setRetention JavaScript API to retain all relevant journeys in the page in which this call is being made, on your property. For example, you may have a 20% Retention Sample Rate for your property but want to retain all journeys that reach your checkout. You can use the setRetention call on the Checkout page which would force retention of this session from the beginning of the Session, for those who were previously being sampled out.

Please note: When used, this will force a user to be retained (i.e. the session will be kept and not discarded). This will include the session from beginning to end, provided they are within the collection sample. If the client has a collection sample rate other than 100%, the session may not be retained. Also, if calling setCollection and then setRetention, the session will only have been collected from the point of the setCollection call, so only these pages of the session will be retained.

So, in the example wherein page 3, the setRetention call is being made; 

Page 1 > Page 2 > Page 3 (setRetention) > Page 4

The full session will be retained and data collected in all pages from 1-4, will be in the replay.

If pages are cross domains, although the retention call would work, it may also complicate the matter with CORS policy, so this would need to be checked too. However, if they are on the same domain, then it should work.

Meanwhile, the following example shows a session being marked for retention following a checkout button, being clicked on the website:

<script type="text/javascript">
   var buttonEl = document.querySelector('#checkoutButton');
   buttonEl.addEventListener('click', function(){
      decibelInsight('setRetention', true);



In order to test if triggering setRetention has been successful, you can do this by using the Decibel Google Chrome extension. Ensure you have Logging Enabled and are logged into the Decibel platform within the same browser session as your testing.

Upon triggering the setRetention in testing, you will see a Decibel log printed to the console, such as in the second line of the below image;

Further Examples

A few more examples can be seen below.

// Enable collection for the current session and future sessions for the current visitor.
decibelInsight('setRetention', true);

 // Enable collection for the current session and keep the visitor in the sample for up to three days.
decibelInsight('setRetention', true, 259200);

 // Disable collection for the current session only.
decibelInsight('setRetention', false, false);