Skip to content
Dropsolid Help Center home page
Product documentation
Products

Javascript API

In this topic we will describe the technical aspect on 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

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
  • mouseup: when the visitor clicks on the site with a mouse
  • touchstart: when the visitor presses the touchscreen
  • touchend: when the visitor lets go of the touchscreen and the touchpoint has moved 40 or more pixels away from the original starting point
  • touchClick: when the visitor lets go of the touchscreen and the touchpoint has moved less than 40 pixels away from the original starting point (both horizontally and vertically)
  • manual: this is a capture that is manually triggered through the use of the dsdc.sendCapture() function

These are saved in capture.event.te__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.

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)

You can find examples in the use cases.

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
  • touchstart
  • touchend
  • manual

touchstart and touchend get triggered with every touch a user does on their device.
This includes just scrolling, which adds a large amount of extra duplicate captures with no real added value.
So we disable them by default, to not overload on captures.

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 to prevent all data captures:

window.dsdc('preventCapture', true);

Example to prevent all data captures except for mouse clicks:

window.dsdc('preventCapture', true);
window.dsdc('preventCapture', false, 'mouseup');

Example to prevent data capture for formSubmit:

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

Example to capture data from scroll events:

window.dsdc('preventCapture', false, 'touchstart');
window.dsdc('preventCapture', false, 'touchend');

// Because these are prevented by default, we also have to update the default settings
dsdcSettings.preventCapture.touchstart = false;
dsdcSettings.preventCapture.touchend = false;

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.

Data format

We use prefixes before the property names to be able to correctly save this data in the elasticsearch database which Unomi uses. If you want to add your own property to the capture, then you will need to use these prefixes as well. The permitted values for each property are based on input values allowed by elasticsearch.

te__*

The prefix te__ stands for text and is meant for properties containing text.

Permitted values
  • a string value
  • a list of string values
Examples
  • "text example"
  • ["text example", "another text example"]
lt__*

The prefix lt__ stands for long text and is meant for properties containing text fields where the value can be longer than 255 characters.

Permitted values
  • a string value
  • a list of string values
Examples
  • "text example but one with way more words"
  • ["text example but one with way more words", "text example but one with way more words than the previous element in this list"]
lo__*

The prefix lo__ stands for long and is meant for properties containing numbers.

Permitted values
  • a signed 64-bit integer with a minimum value of -263 and a maximum value of 263-1
  • a list of integer values
Examples
  • 1
  • [1, 2, 3, 4]
do__*

The prefix do__ stands for double and is meant for properties containing decimal numbers.

Permitted values
  • a double-precision 64-bit IEEE 754 floating point number, restricted to finite values
  • a list of float values
Examples
  • 1.1
  • [1.1, 2.2, 3.3, 4.4]
da__*

The prefix da__ stands for data and is meant for properties containing dates.

Permitted values
  • a string containing a formatted date
  • a number representing milliseconds-since-the-epoch
  • a number representing seconds-since-the-epoch
  • a list of strings containing formatted dates
Examples
  • "2015-01-01"
  • "2015/01/01 12:10:30"
  • 1646317725
bo__*

The prefix bo__ stands for boolean and is meant for properties containing booleans.

Permitted values
  • False values:
    • false
    • "false"
    • ""
  • True values:
    • true
    • "true"
Prefix examples

Example of 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'   
}

Note that only the deepest keys need these prefixes.

If you want to add an object with multiple properties, then the object itself does not need the prefix, but the deepest properties do.

An example for this can be found in the use cases.

afterResponse

This will be triggered after the capture gets sent to the API. It will return the response 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.

Specific integrations

Merging Unomi profiles based on a property

Keep track of the same visitor across multiple devices or browsing sessions by letting Unomi seamlessly merge profiles.

You can find examples in the use cases.

Config structure

The merge identifier configuration has a general structure, which you always add to the data capture:

{
  "te__mergeIdentifier_1": "myMergeValue"
}

How to enable

You can enable this by setting a merge identifier in your capture data. The merge identifier is a profile property you want Unomi to check, which can be any property you want, like a Mautic id, or an email address. This property has to be of type string.

This means that if 2 profiles in Unomi have the same value for this property, these 2 profiles will be merged into one, because Unomi will see them as the same visitor.

This snippet will ask Unomi to merge profiles which have myMergeValue as the merge identifier:

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

    // merge profiles
    var getCaptureHandler = function (data) {

        // temporary store our capture data & potential merge value
        var changedCapture = data.requestData;

        // add the merge property to the capture data under the key te__mergeIdentifier_1
        changedCapture.te__mergeIdentifier_1 = "myMergeValue";

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

    window.dsdc('beforeRequest', getCaptureHandler);
</script>

Keep a score of your visitors

Keep track of visitor engagement by keeping scores on their unomi profile. The scores can be used when creating segments to better categorize visitors.

You can find examples in the use cases.

Config structure

The scoring configuration for the data capture has a general structure, which you always add under the key scoring in the data capture:

{
  "scoring_group_1": {
    "scoring_value_1": {
      "te__operator": "+",
      "te__value": "1"
    }
  },
  "scoring_group_2": {
    "scoring_value_2": {
      "te__operator": "+",
      "te__value": "2"
    },
    "scoring_value_3": {
      "te__operator": "+",
      "te__value": "1"
    }
  }
}

Scoring is divided into groups which are once again divided into individual scores. The groups in the structure above are scoring_group_1, scoring_group_2, where group scoring_group_1 contains one score which is scoring_value_1, and where scoring_group_2 contains two scores which are scoring_value_2 and scoring_value_3.

scoring_group_1, scoring_group_2, scoring_value_1, scoring_value_2 and scoring_value_3 in the above structure can all be replaced by names you want, as long as they only use the allowed characters:

  • lower and upper case letters
  • numbers between 0 and 9
  • underscores

The key te__operator cannot be changed and the value can only be + or - and needs to be of type string.

The key te__value cannot be changed and the value can only be numbers between 0 and 9 and needs to be of type string.

How to enable

You can enable scoring by including configuration like in this snippet example in your capture data. This snippet example will ask Unomi to increase the score for scoring_value_1 in group scoring_group_1 by 1, and increase the score for scoring_value_2 by 2 and scoring_value_3 by 1 in group scoring_group_2 on each interaction (event) with the website:

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

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

        // get capture data
        var changedCapture = data.requestData;

        // add scoring configuration
        changedCapture.scoring = {
          "scoring_group_1": {
            "scoring_value_1": {
              "te__operator": "+",
              "te__value": "1"
            }
          },
          "scoring_group_2": {
            "scoring_value_2": {
              "te__operator": "+",
              "te__value": "2"
            },
            "scoring_value_3": {
              "te__operator": "+",
              "te__value": "1"
            }
          }
        };

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

Unomi will update the scores in a profile on each datacapture it receives if the data capture has a scoring configuration.

These scoring properties will be available when creating a segment when at least one profile has the scoring properties. The scores can be negative numbers.

Unomi also keeps track of the highest score and highest scoring name in a group. Both will be updated on each datacapture, which has scoring config, that Unomi receives. If there are two or more scoring names which have the same score, both will be found under te__highest_scoring in that group in the profile.

Remarks

Errors

If the configuration for a group or score is wrong, the group or score in the profile will not be updated. No exceptions will be thrown and you won't receive error messages, so make sure the configuration is correct.

Merging

When two profiles are merged, the scoring of the newest profile will be transferred to the already existing profile.

Send a capture with your own trigger or event

This function was introduced to enable users to send a capture to the API using their own events or triggers. That way, these don't have to wait for the preset event handlers, such as load and unload.

For example:

  • You get to a 'Thank you' page where you reach a Matomo goal. You have used the beforeRequest method to add the Matomo goals data to the capture. In this case you can use the sendCapture function to send the extended capture without having to wait for further interactions.

An example can be found in the use cases.

This is the snippet that you need to be able to use the dsdc.sendCapture() function 

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

    // turn the manual captures on (they are prevented by default)
    dsdcSettings.preventCapture.manual = false;
    window.dsdc('preventCapture', false, 'manual');
    // send the capture
    dsdc.sendCapture();
</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 use cases.

The function dsdc.sendCapture() is used to enable users to send a capture to the API using their own events or triggers.
Example usage of this function can be found in the use cases.

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 use cases.

Send us your question

Do you still have unanswered questions or do you want to make some adjustments to your project? Don't hesitate to ask us your question at support@dropsolid.com or at +3293950290.