In this topic we will describe how to interact with captures.
Before you can do this you need to make sure you have the capture script configured on your site.

We will tell you more about the javascript API to interact with captures.
We will describe the following:

• Triggers: what exactly triggers the capture script
• Methods: how can you hook into events
• Specific integrations: specific example of hooking into events
• Technical info: more technical info about the dsdc namespace

Triggers

Events

Capture data is saved and posted to the API on these (sometimes custom) events:

• js: when the capture script is loaded and initialised [turned off by default in capture.js init function]
• dom: when the DOM is ready (meaning: the DOM has loaded)
• load: when stylesheets and images have also loaded [turned off by default in capture.js init function]
• unload: when the tab is closed or reloaded

These are saved in capture.event.eventType, and these names can be used with Methods to hook into these events (see further below).

The js and load events can be enabled by adding a custom snippet, using the dsdcSettings.
An example of this can be found in the examples.

Interactions

Captures also happen on various user interactions.
Roughly speaking, we track clicks (mouse or touch event) and certain keyboard interactions (copy, paste, but also form submits by pressing the enter key);

We subdivide into 2 kinds:

• formSubmit: a form submit (can be via keyboard enter or clicking a submit button)
• interaction: the other interactions: clicking in the page using mouse or touch, + some specific keyboard stuff (copy and paste)

These names are also used by the Methods.

Methods

You can use methods that are passed to the dsdc() command queue, to do things like hook into events and interactions or even prevent captures from happening at all. This is done by adding them to a script (or script tag, examples further down)

preventCapture

This one is used to prevent data captures from happening, either for individual events or interactions, or for all captures.
By default, all events and interactions mentioned, do data capture EXCEPT these:

• js
• load

window.dsdc('preventCapture', [value], [trigger]);

• value: boolean, indicate whether to prevent captures or not
• trigger: string (optional), what event or interaction name captures you want to prevent (eg. only for formSubmit) (don't use if you want ALL captures to be prevented)

Example: Prevent all data captures:
window.dsdc('preventCapture', true);

Example: Prevent data capture for formSubmit:
window.dsdc('preventCapture', true, 'formSubmit');

beforeRequest

This will be triggered before the capture gets sent to the API.
It will return the capture in a json object with key requestData.

It is used as follows:

• window.dsdc('beforeRequest', [trigger], [handler]);
• trigger: string (optional), what event or interaction name captures you want to execute the handler on (don't use if you want to execute the handler or ALL captures)
• handler: a function in which you can read the capture (and modify + send back, if needed)

For reference, here are all the event and interaction names again:

Events:

• js: [turned off by default in capture.js init function]
• dom
• load: [turned off by default in capture.js init function]
• unload

Interactions:

• interaction
• formSubmit

To actually update the capture (add or delete data) you need to use the dsdc.updateCapture() function.
More info about this function in the Technical info part.

The js and load events can be enabled by adding a custom snippet, using the dsdcSettings.
An example of this can be found in the examples.

Data format

We use prefixes before our property names to be able to correctly save this data in the database.
If you want to add your own property to the capture, then you will need to use these prefixes as well.

• te__*  = text
• lt__*   = long text, text fields where the value can be longer than 255 characters
• lo__*  = long, 64 bit integer, eg. 1
• do__* = double, 64 bit float, eg. 1.1
• da__* = date
• bo__* = boolean

Example: Add a text property for the day of the week:
dayOfWeek => te__dayOfWeek
birthday => da__birthday
Example of this data in the capture:

{ 
  te__dayOfWeek: 'Monday',
  da__birthday: '2020-09-28T09:26:12.621Z' 
}

afterResponse

This will be triggered after the capture gets sent to the API.
It will return the reponse of the API in a json object with key responseData.

It is used as follows:

• window.dsdc('afterResponse', [trigger], [handler]);
• trigger: string (optional), what event or interaction name captures you want to execute the handler on (don't use if you want to execute the handler or ALL captures)
• handler: a function in which you can read the after the capture has been sent to the API

For reference, here are all the event and interaction names again:

Events:

• js: [turned off by default in capture.js init function]
• dom
• load: [turned off by default in capture.js init function]
• unload

Interactions:

• interaction
• formSubmit

The js and load events can be enabled by adding a custom snippet, using the dsdcSettings.
An example of this can be found in the examples.

Example: read capture BEFORE capture is saved and sent to API

<script>
    window.dsdc = window.dsdc || function() {(dsdc.q=dsdc.q||[]).push(arguments)};dsdc.l=+new Date;

    window.dsdc('beforeRequest', function(data) {

        // read the capture data before script is loaded
        console.log(data.requestData);
    });

</script>

Example: read & modify capture BEFORE it was saved and sent to API (remove data from capture)

<script>
    window.dsdc = window.dsdc || function() {(dsdc.q=dsdc.q||[]).push(arguments)};dsdc.l=+new Date;

    window.dsdc('beforeRequest', function(data) {

        changedCapture = data.requestData

        // make a change, eg. remove the cookies from capture
        changedCapture.browserData.browser.dataCookies = {};

        // use a global function to pass the modified capture back to the main script
        dsdc.updateCapture(changedCapture);
    });

</script>

Example: read & modify capture BEFORE it was saved and sent to API (add day of the week to capture)

<script>
    window.dsdc = window.dsdc || function() {(dsdc.q=dsdc.q||[]).push(arguments)};dsdc.l=+new Date;

    window.dsdc('beforeRequest', function(data) {

        changedCapture = data.requestData

        // make a change, eg. add the day of the week to the capture
        var today = new Date();
        changedCapture.te__dayOfWeek = today.toLocaleDateString("en-US", {weekday: 'long'});
        
        // use a global function to pass the modified capture back to the main script
        dsdc.updateCapture(changedCapture);
    });

</script>

Example: read & modify capture BEFORE it was saved and sent to API (add birthday with date of today to capture)

<script>
    window.dsdc = window.dsdc || function() {(dsdc.q=dsdc.q||[]).push(arguments)};dsdc.l=+new Date;

    window.dsdc('beforeRequest', function(data) {

        changedCapture = data.requestData

        // make a change, eg. add today to the capture as birthday
        changedCapture.da__birthday = (new Date()).toISOString();
        
        // use a global function to pass the modified capture back to the main script
        dsdc.updateCapture(changedCapture);
    });

</script>

Example: read response AFTER capture is saved and sent to API

<script>
    window.dsdc = window.dsdc || function() {(dsdc.q=dsdc.q||[]).push(arguments)};dsdc.l=+new Date;

    window.dsdc('afterResponse', function(data) {

        // read the response data after the capture is sent to the API
        console.log(data.responseData);
    });

</script>

Example: prevent all data captures

<script>
    window.dsdc = window.dsdc || function() {(dsdc.q=dsdc.q||[]).push(arguments)};dsdc.l=+new Date;

    window.dsdc('preventCapture', true);

</script>

Example: prevent data captures for form submits only

<script>
    window.dsdc = window.dsdc || function() {(dsdc.q=dsdc.q||[]).push(arguments)};dsdc.l=+new Date;

    window.dsdc('preventCapture', true, 'formSubmit');

</script>

Example: prevent all data captures on Sundays

<script>
    window.dsdc = window.dsdc || function() {(dsdc.q=dsdc.q||[]).push(arguments)};dsdc.l=+new Date;

    var today = new Date();
    if (today.getDay() == 0) {
        window.dsdc('preventCapture', true);
    }

</script>

Example: enable the js and load events, which are prevented by default

<script>
    window.dsdcSettings = window.dsdcSettings || {};
    dsdcSettings.preventCapture = dsdcSettings.preventCapture || {};

    // Set the preventCapture of these events to false
    // This means they are no longer prevented
    dsdcSettings.preventCapture.js = false;
    dsdcSettings.preventCapture.load = false;

    console.error(dsdcSettings);
</script>

Specific integrations

Send Mautic id to unomi

This can be done by adding the following snippet to GTM. This snippet can be added in the same way the capture script is added.

This script will try to get the mauticId of the user of the site and add it to the capture data before sending it to the API.

<script>
    // enable namespace that handles the queue and methods
    window.dsdc = window.dsdc || function () { (dsdc.q = dsdc.q || []).push(arguments) }; dsdc.l = +new Date;

    // Now BEFORE each capture happens, we'll check if we can find a Mautic ID
    // and send it along with the capture data

    // this is the function that looks for the ID and appends it to the capture data
    var getMauticIdHandler = function (data) {
        // temp store our capture data & potential Mautic id
        var changedCapture = data;

        // Get the Mautic ID value with the mtcId function that can also be used in console. (returns undefined if it doesn't exist)
        var mauticId = window.mtcId;

        // append the ID to the capture if any found
        if (mauticId !== null && mauticId !== undefined) {
            changedCapture.requestData.te__mautic_id = mauticId;

            // send the changed data back to the main script
            dsdc.updateCapture(changedCapture.requestData);
        }
    }

    // This method will make sure to execute the function
    // BEFORE each capture is saved (so for every event)
    window.dsdc('beforeRequest', getMauticIdHandler);
</script>

Send unomi profile segment uuids & human readable names to Mautic

This can be done by adding the following snippet to GTM. This snippet can be added in the same way the capture script and the previous script are added.

To use this integration, you need to create 2 custom fields in Mautic, 1 for the unomi profile segment uuids and 1 for the unomi profile segment names.

These labels and aliases are just examples. You can choose what label and what alias you want to give your custom field.
Just remember that you will need to update the alias names in the snippet if you are not using the same alias as us.

<script>
    // enable namespace that handles the queue and methods
    window.dsdc = window.dsdc || function () { (dsdc.q = dsdc.q || []).push(arguments) }; dsdc.l = +new Date;

    // this is the function that reads the profile segment uuids and human readable names and sends them to Mautic
    var sendToMauticHandler = function (data) {
        // create a string of all the uuids of the segments, separated by ", "
        var segmentsUuid = data.responseData.profile.profileSegments.join(", ");
        // if the user doesn't belong to a segment, use the standard value "_unknown"
        if (segmentsUuid == "") {
            segmentsUuid = "_unknown";
        }

        // create a string of all the names of the segments, separated by ", "
        var segmentsNames = data.responseData.profile.profileSegmentNames.join(", ");
        // if the user doesn't belong to a segment, use the standard value "_unknown"
        if (segmentsNames == "") {
            segmentsNames = "_unknown";
        }
        // Sending the segment uuids and the segmentNames of the profile to mautic
        mt('send', 'pageview', { personalisation_segment_u: segmentsUuid, personalisation_segment_l: segmentsNames });
    }

    window.dsdc('afterResponse', sendToMauticHandler);

</script>

Combination of sending Mautic id to unomi and unomi profile segment uuids & names to Mautic

If you want to implement both of these at the same time, you can combine the 2 above snippets into 1. If you combine them, then this is the snippet you would end up with:

<script>
    // enable namespace that handles the queue and methods
    window.dsdc = window.dsdc || function () { (dsdc.q = dsdc.q || []).push(arguments) }; dsdc.l = +new Date;

    // Now BEFORE each capture happens, we'll check if we can find a Mautic ID
    // and send it along with the capture data

    // this is the function that looks for the ID and appends it to the capture data
    var getMauticIdHandler = function (data) {

        // temp store our capture data & potential Mautic id
        var changedCapture = data;

        // Get the Mautic ID value with the mtcId function that can also be used in console. (returns undefined if it doesn't exist)
        var mauticId = window.mtcId;

        // append the ID to the capture if any found
        if (mauticId !== null && mauticId !== undefined) {
            changedCapture.requestData.te__mautic_id = mauticId;

            // send the changed data back to the main script
            dsdc.updateCapture(changedCapture.requestData);
        }
    }

    // This method will make sure to execute the function
    // BEFORE each capture is saved (so for every event)
    window.dsdc('beforeRequest', getMauticIdHandler);

    // If you want to minimize the amount of times this is done,
    // you can associate the Mautic retrieval with a specific event instead,
    // eg. on script load:
    // window.dsdc('beforeRequest', 'js', getMauticIdHandler);


    // this is the function that reads the profile segment uuids and human readable names and sends them to Mautic
    var sendToMauticHandler = function (data) {
        // create a string of all the uuids of the segments, separated by ", "
        var segmentsUuid = data.responseData.profile.profileSegments.join(", ");
        // if the user doesn't belong to a segment, use the standard value "_unknown"
        if (segmentsUuid == "") {
            segmentsUuid = "_unknown";
        }

        // create a string of all the names of the segments, separated by ", "
        var segmentsNames = data.responseData.profile.profileSegmentNames.join(", ");
        // if the user doesn't belong to a segment, use the standard value "_unknown"
        if (segmentsNames == "") {
            segmentsNames = "_unknown";
        }

        // Sending the segment uuids and the segmentNames of the profile to mautic
        mt('send', 'pageview', { personalisation_segment_u: segmentsUuid, personalisation_segment_l: segmentsNames });
    }

    window.dsdc('afterResponse', sendToMauticHandler);

</script>

Technical info

We use a namespace: dsdc = Dropsolid data capture.
This is a global object which contains all our functions, methods and variables.
In every example, the first code line is enabling this namespace, which allows you to use the methods present in that namespace.

The function dsdc.updateCapture(capture) is used to update a capture, before the capture gets sent to the API.
As parameter to the function, you have to give a capture object. Mostly you will just read the capture from the capture script, update this one and then send this updated capture to the dsdc.updateCapture() function.
But you can also just create your own capture to send to this function.
Example usage of this function can be found in the examples previously shown.

The namespace dsdcSettings can be used to enable the events that are disabled by default.
An example of this usage can be found in the examples previously shown.