Skip to content
Dropsolid Help Center home page
Product documentation
Personalisation

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

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.

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

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__* = text
  • lt__* = long text, text fields where the value can be longer than 255 characters
  • lo__* = long, eg. 1
    • a signed 64-bit integer with a minimum value of -263 and a maximum value of 263-1.
  • do__* = double, eg. 1.1
    • a double-precision 64-bit IEEE 754 floating point number, restricted to finite values.
  • da__* = date
    • permitted values:
      • strings containing formatted dates, e.g. "2015-01-01" or "2015/01/01 12:10:30"
      • a number representing milliseconds-since-the-epoch
      • a number representing seconds-since-the-epoch
  • bo__* = boolean
    • permitted values:
      • False values: false, "false", ""
      • True values: true, "true"

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

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

The key te__value cannot be changed and the value can only be numbers between 0 and 9.

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 transfered to the already existing profile.

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 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.io or at +3293950290.