API JavaScript SDK

Здесь описаны функция start(), методы агента и данные, которые они возвращают. Установка и первый запрос показаны в быстром старте.

import { start } from '@fingerru/agent'

const agent = start({
  apiKey: 'pk_live_example',
  loadTimeout: 10_000,
  cache: { storage: 'sessionStorage', duration: 3600 },
})

const visitor = await agent.get({ timeout: 5_000 })

start(options)Скопировать ссылку

start() создаёт агента и сразу его возвращает. Функция проверяет параметры, но ничего не загружает и не отправляет. Скрипт сбора данных загружается при первом вызове get().

Если параметр задан неверно, start() сразу выбрасывает FingprintAgentError. Коды этих ошибок перечислены на странице Ошибки SDK.

endpointСкопировать ссылку

Укажите endpoint, если запросы к Fingprint должны идти через ваш поддомен. Передайте только origin — протокол и домен:

const agent = start({
  apiKey: 'pk_live_example',
  endpoint: 'https://metrics.example.com',
})

Допустим только http: или https:. Путь, query, hash, логин и пароль в адресе не допускаются: https://metrics.example.com/api вызовет ошибку INVALID_ENDPOINT.

Если endpoint не задан, SDK использует адреса Fingprint по умолчанию.

cacheСкопировать ссылку

По умолчанию каждый вызов get() собирает данные и отправляет запрос. Включите кеш, чтобы в течение заданного времени повторные вызовы возвращали сохранённый результат без нового запроса:

const agent = start({
  apiKey: 'pk_live_example',
  cache: { storage: 'localStorage', duration: 3600 },
})

Как выбрать storage:

• memory — результат хранится в памяти страницы и пропадает после перезагрузки;
• sessionStorage — результат живёт до закрытия вкладки;
• localStorage — результат доступен во всех вкладках сайта, пока не истечёт duration.

В кеш попадает только результат get(): user, requestId. Собранные данные браузера в нём не хранятся. Запись привязана к apiKey и адресу запроса, поэтому агенты с разными ключами не читают кеш друг друга.

Если выбранное хранилище недоступно, например его запрещают настройки браузера, SDK хранит результат в памяти. Ошибки кеша не прерывают get().

agent.get(options?)Скопировать ссылку

get() возвращает идентификатор посетителя от Fingprint API. Метод собирает данные браузера, отправляет их POST-запросом и возвращает Promise<VisitorResult>.

const visitor = await agent.get({ ignoreCache: true })

Если несколько одинаковых вызовов get() выполняются одновременно, SDK отправляет один запрос и возвращает его результат всем вызовам.

VisitorResultСкопировать ссылку

type VisitorResult = {
  user: string
  requestId?: string
  cacheHit?: boolean
}

После успешного ответа SDK сохраняет user в localStorage под ключом __uident_id и передаёт его в следующих запросах. Если localStorage недоступен, get() всё равно вернёт результат.

Подключение через CDNСкопировать ссылку

В IIFE-сборке те же функции доступны через глобальный объект FingprintAgent:

const agent = FingprintAgent.start({ apiKey: 'pk_live_example' })

Параметры и методы совпадают с npm-пакетом. Как подключить скрипт, показано на странице JavaScript.