Документация

ДАРА ОТПЕЧАТОК — облачный сервис идентификации посетителей. Один тег <script> даёт каждому браузеру на вашем сайте постоянный visitor_uuid, а серверу сайта — профиль посетителя: визиты, устройство, признак нескольких аккаунтов на одном устройстве.

Быстрый старт

<script src="https://fingerprint.daratech.ru/sdk/dara-fingerprint.js"></script>
<script>
  DaraFingerprint.init({
    apiUrl: 'https://fingerprint.daratech.ru/api',
    apiKey: 'pk_ВАШ-ПУБЛИЧНЫЙ-КЛЮЧ'
  });
</script>

Ключи сайта

Ключ передаётся заголовком X-API-Key или Authorization: Bearer sk_…. Посетители, сессии и совпадения видны только в пределах сайта: по ключу другого сайта методы отвечают 404.

Конфигурация SDK

Параметры DaraFingerprint.init(options):

Как работает

Посетитель — это cookie dara_visitor на вашем сайте. Отпечаток устройства личностью не считается: у одинаковых устройств он одинаковый. Два человека с iPhone одной модели, версии iOS и языка дают один и тот же отпечаток — и получают разные visitor_uuid.

SDK собирает сигналы браузера, сервер считает из них хеш устройства. Если cookie потерялась, прежний visitor_uuid возвращается (match: "restored") только при выполнении всех условий:

• устройство уникально на сайте: не iOS и не iPadOS, за 30 дней с ним не было трёх и более посетителей, защита браузера от отпечатков не меняет его сигналы;
• за 30 дней с этим устройством был ровно один посетитель;
• он заходил из той же сети (IPv4 /24, IPv6 /48), и в этой сети не больше 20 посетителей сайта;
• он не активен прямо сейчас из другой сети.

Иначе создаётся новый посетитель, а совпадение по устройству записывается как возможное: оно видно в /visitor/info и в кабинете, но профиль не меняет. Разные люди автоматически не склеиваются.

Cookie на сервере

Safari (ITP) ограничивает cookie, записанные из JavaScript, семью днями. Cookie из ответа вашего сервера живёт полный срок. Продлевайте её на каждом ответе страницы, если значение — UUID:

// PHP, до вывода страницы
$uuid = $_COOKIE['dara_visitor'] ?? '';
if (is_string($uuid) && preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i', $uuid)) {
    setcookie('dara_visitor', strtolower($uuid), [
        'expires'  => time() + 400 * 86400,
        'path'     => '/',
        'secure'   => true,
        'samesite' => 'Lax',
        'httponly' => false,   // SDK читает cookie из JavaScript
    ]);
}

Сигналы

В хеш устройства входят сигналы, которые не меняются у одного браузера:

• Canvas и AudioContext — различия отрисовки и звукового движка
• Math — платформенные отличия тригонометрических функций
• GPU: WebGL Renderer и Vendor
• Экран, colorDepth, devicePixelRatio, количество точек касания
• Ядра CPU, объём памяти, платформа
• Часовой пояс (IANA-название) и языки

User-Agent с версией браузера, тип сети, доступная область экрана, Do Not Track и число плагинов сохраняются в сессии, но в хеш не входят: у одного человека они меняются.

POST /session/init

SDK вызывает этот метод автоматически. Ключ — публичный.

POST https://fingerprint.daratech.ru/api/session/init
Content-Type: application/json
X-API-Key: pk_ВАШ-ПУБЛИЧНЫЙ-КЛЮЧ

{
  "visitor_uuid":      "<UUID из cookie dara_visitor>",
  "session_uuid":      "<UUID вкладки>",
  "fingerprint_data":  { "canvasFp": "…", "gpuRenderer": "…", "screen": "1920x1080", … },
  "page_url":          "https://example.com/",
  "user_agent":        "Mozilla/5.0...",
  "screen_resolution": "1920x1080"
}

{
  "success":       true,
  "visitor_uuid":  "0f8c2a4e-…",        // запишите в cookie dara_visitor
  "session_id":    42,
  "match":         "cookie",            // cookie | restored | new
  "confidence":    1.0,                 // 1.0 cookie, 0.9 restored, 0 new
  "is_identified": false,               // есть email или телефон
  "is_ambiguous":  false,               // в истории, вероятно, несколько людей
  "fp_version":    2,
  "merged_from":   null,                // устарело: "fingerprint" при match = restored
  "visit_count":   7,
  "first_visit":   "2026-04-12 09:23:11",
  "recent_visits": [
    { "date": "2026-05-24 14:00:00", "browser": "Chrome", "os": "Windows 10", "device_type": "desktop" }
  ]
}

visitor_uuid обязательно в формате UUID, иначе ответ 400. Если uuid принадлежит другому сайту, выдаётся новый.

POST /visitor/info

Профиль посетителя для сервера сайта. Ключ — секретный. Посетитель чужого сайта — 404.

{
  "success": true,
  "visitor": { "uuid": "…", "is_identified": true, "email": "…", "phone": null, "total_visits": 7, … },
  "ambiguous": false,
  "device": {
    "hash_prefix": "3fa1c9d2",
    "is_common": false,                 // true — по устройству людей не различить
    "common_reason": null,              // low_entropy_platform | many_visitors | many_networks | unstable_signals
    "visitors_on_device_90d": 2
  },
  "possible_matches": [
    { "visitor_uuid": "…", "confidence": 0.6, "reasons": ["same_device"],
      "is_common_device": false, "last_seen_at": "…", "is_identified": true }
  ],
  "multi_account": {
    "suspected": true,                  // на этом устройстве другой аккаунт с другим email
    "other_identified": 1,
    "same_browser_emails": 0,           // другие email из форм этого же браузера
    "confidence": 0.6
  },
  "current_session": null, "sessions": [ … ], "identification_events": [ … ],
  "linked_profiles": [ … ], "collected_data": [ … ]
}

Возможные совпадения: 0,3 — общее устройство, 0,6 — уникальное устройство из разных сетей, 0,8 — уникальное устройство из одной сети. Для общего устройства multi_account.suspected всегда false.

POST /collect/field

Данные из форм: email, телефон, имя. Ключ — секретный. session_uuid необязателен: без него данные привязываются к последней сессии посетителя на сайте. Совпадения email и телефона ищутся только среди посетителей вашего сайта.

{
  "visitor_uuid": "0f8c2a4e-…",
  "field_type":   "email",              // email | phone | name | text
  "field_name":   "registration_email",
  "field_value":  "user@example.com"
}

С callback

DaraFingerprint.init({
  apiUrl: 'https://fingerprint.daratech.ru/api',
  apiKey: 'pk_ВАШ-ПУБЛИЧНЫЙ-КЛЮЧ'
}).onReady(function (result) {
  console.log('visitor_uuid:', result.visitor_uuid);
  console.log('Как узнан:',    result.match);          // cookie | restored | new
  console.log('Есть контакты:', result.is_identified);
});

// То же событием
window.addEventListener('dara:ready', function (e) {
  console.log(e.detail.visitor_uuid, e.detail.match, e.detail.is_ambiguous);
});

PHP

Проверка при регистрации: нет ли на этом устройстве другого аккаунта. Сервер берёт uuid из cookie и вызывает API секретным ключом.

function daraCall(string $path, array $data): array
{
    $ch = curl_init('https://fingerprint.daratech.ru/api' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 3,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'Authorization: Bearer ' . getenv('DARA_SECRET_KEY'),   // sk_…
        ],
        CURLOPT_POSTFIELDS => json_encode($data),
    ]);
    $raw = curl_exec($ch);
    return $raw !== false ? (json_decode($raw, true) ?? []) : [];
}

$uuid = $_COOKIE['dara_visitor'] ?? '';
if (preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i', $uuid)) {
    daraCall('/collect/field', [
        'visitor_uuid' => $uuid,
        'field_type'   => 'email',
        'field_name'   => 'registration_email',
        'field_value'  => $email,
    ]);
    $info = daraCall('/visitor/info', ['visitor_uuid' => $uuid]);
    $possibleMultiAccount = !empty($info['multi_account']['suspected']);
}