Why is merging necessary?

If the user comes from different devices or browsers, our system does not know that it is the same user. But there is a special mechanism which helps Dashly to join all sessions from different devices together and collect information about user in one card.

How it works

The merging is based on the User ID parameter, which must be sent during sign in (and sign up) of the user. In order to set a User ID, you need to call the script on the browser side:

dashly.auth('5231', '49672bf861335d68040fedb25c90a580dd33c6748dc82d8fe76d508ebcef2b4b');

First argument is User ID.
The second argument is a hash calculated by the HMAC SHA 256 function. The hash text is the User ID. The key is User Auth Key, you can find it in the admin panel (click on Settings icon => Developers).
User ID does not have to be a number, strings up to 255 characters are allowed. Bug it is recommended that you use a numeric identifier.
That is, you can use not only the user id from your system as User ID, but also an email or a phone. The main thing is that two rules are fulfilled:

  • User ID must be unique for each user.
  • User ID can not be changed during user’s lifetime. For example, email should not be used as User ID if user can change it.

Important! If you get 403 errors in your browser console when sending dashly.auth, check the validity of the hash generation in this online generator.

Important! It is important to understand that security is based on the secrecy of User Auth Key (a system with shared secret), so this key can not be used on the browser side (JavaScript) at all, the hash generation should be done only on the server side. If the key is no longer a secret, unscrupulous users will be able to read other people's messages or perform events on behalf of someone else's.

Example of PHP hash generation:

$userId = '...';
$hash = hash_hmac('sha256', $userId, 'userauth-secret-key');
echo "dashly.auth('$userId', '$hash');"

Thus, your user does not see the secret key, and he will be assigned User ID = 2. This method can be called only once after authorization (actual for Single Page App), or it can be called multiple times (if you insert the code through Backend into each page, when the user is authorized, ie, for example via PHP) - this is OK, too.

Why are users not merged by email automatically?

Since we collect emails from any field, an attacker can input other user’s email. This way, he will easily pretend being any other person, will be able to read other person’s messages and perform actions on other person’s behalf.

Why need all those difficulties with HMAC?

Example. If you’re writing a backend in PHP (for example), and you would just write dashly.auth(<?php echo $userID ?>); then in the browser it would look something like dashly.auth(1234); The intruder seeing that you are sending UserId = 1234, can open the console and start bruteforcing other ids (he can type dashly.auth(1235) for example, so he will pretend being a user with Userid = 1235). Thus, he easily impersonates any other person, can read his messages and make events on his behalf. If a hash is added, the secret key with which the hash is calculated, is known only to your backend (thus source code is unknown to the attacker) and dashly. When you’re calling the auth method, dashly, knowing the UserID and knowing the secret key, calculates the hash by itself. Then it checks if this calculated hash matches what was sent. If it does not match, then the request is rejected and the union does not occur.

Server-side user merging

At the moment REST API can not be used to merge users. But we’re working on it and such functionality can appear in the future.