Как интегрировать Digital Fraud Protection

По этой инструкции вы подключите DFP к своему сайту: добавите JavaScript-скрипт на страницы, настроите расшифровку ответа DFP на бекэнде и встроите его в бизнес-логику.

1. Выберите, по какому домену ваш сайт будет обращаться к API DFP

В ходе интеграции вы встроите скрипт в нужные страницы своего сайта. Этот скрипт будет отправлять запросы к API DFP. Он может обращаться к API через:

Стандартный адрес https://fp.servicepipe.tech/fp/. Работает по умолчанию, ничего настраивать не нужно.
Ваш поддомен. В этом случае мы выделим для вас IP, а вам нужно настроить A-запись своего поддомена на этот IP.

Если хотите использовать свой поддомен, сообщите нам. Если нет, ничего делать не нужно, просто переходите к шагу 2.

Ниже в примерах используется стандартный адрес API — https://fp.servicepipe.tech/fp/.

2. Получите токен и секретный ключ

Мы передадим вам два значения:

CUSTOMER-TOKEN — токен для загрузки JavaScript-библиотеки и вызова API;
секретный ключ — им ваш бэкенд будет расшифровывать payload.

Секретный ключ храните только на бэкенде. Не добавляйте его в код страницы и не передавайте в браузер пользователя.

3. Подключите скрипт к сайту

Добавьте JavaScript-библиотеку DFP на страницы, где хотите проверять клиентское окружение и признаки ботовой активности:

<script src="https://fp.servicepipe.tech/fp/v1/<CUSTOMER-TOKEN>/fp.js"></script>

После загрузки скрипта на странице станет доступен класс ServicepipeFP. Через него вы будете вызывать DFP из кода страницы.

4. Создайте экземпляр `ServicepipeFP`

На шагах 4-11 вы настроите клиентский код: создадите экземпляр ServicepipeFP, зададите опции, запустите сбор данных, передадите дополнительные параметры, получите результат DFP и отправите его на бэкенд.

Пример готового клиентского кода:

const fp = new ServicepipeFP(
  "https://fp.servicepipe.tech/fp/",
  "<CUSTOMER-TOKEN>",
  {
    prework: true,
    maxRetries: 3
  }
);

await fp.initSP();
await fp.run();

const dfpOptions = {
  customData: JSON.stringify({
    event: "login_attempt"
  })
};

const result = await fp.get(dfpOptions);

await fetch("/api/dfp/check", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify(result)
});

Создайте объект ServicepipeFP и передайте в него адрес API DFP и ваш токен:

const fp = new ServicepipeFP(
  "https://fp.servicepipe.tech/fp/",
  "<CUSTOMER-TOKEN>"
);

Если используете свой поддомен, укажите его вместо стандартного адреса:

const fp = new ServicepipeFP(
  "https://fp-check.example.com/fp/",
  "<CUSTOMER-TOKEN>"
);

5. (Опционально) настройте поведение библиотеки

Минимальная рекомендация: включите prework — с ним DFP будет работать быстрее, при этом опция не несёт никаких минусов.

При создании ServicepipeFP можно передать третий аргумент — объект с настройками. Они управляют тем, как библиотека будет собирать данные и что будет делать, если запрос к API DFP не удался.

Пример добавления:

const fp = new ServicepipeFP(
  "https://fp.servicepipe.tech/fp/",
  "<CUSTOMER-TOKEN>",
  {
    prework: true,
    maxRetries: 3,
    fullScan: false
  }
);

Доступны три опции:

Опция Что делает

Опция	Что делает
`prework`	Запускает часть методов сбора данных заранее, во время инициализации `ServicepipeFP`. Благодаря этому, при вызове `get` () библиотеке нужно будет выполнить меньше работы — ведь часть операций уже будет сделана. В результате DFP будет работать быстрее.
`maxRetries`	Задаёт, сколько раз можно повторить запрос к API DFP, если первая попытка не удалась.
`fullScan`	Позволяет включить дополнительные методы сбора данных. Например: надёжное обнаружение открытия текущий браузерной вкладки пользователем, дополнительные проверки для обнаружения популярных инструментов автоматизации. Полный список методов можно запросить у наших инженеров. Эти методы позволяют получить более точный результат анализа, но значительно замедляют исполнение скрипта. По умолчанию дополнительные методы выключены. Если хотите включить, согласуйте это с нашими инженерами.

prework

Запускает часть методов сбора данных заранее, во время инициализации ServicepipeFP.

Благодаря этому, при вызове get () библиотеке нужно будет выполнить меньше работы — ведь часть операций уже будет сделана. В результате DFP будет работать быстрее.

maxRetries

Задаёт, сколько раз можно повторить запрос к API DFP, если первая попытка не удалась.

fullScan

Позволяет включить дополнительные методы сбора данных. Например:

надёжное обнаружение открытия текущий браузерной вкладки пользователем,
дополнительные проверки для обнаружения популярных инструментов автоматизации.

Полный список методов можно запросить у наших инженеров. Эти методы позволяют получить более точный результат анализа, но значительно замедляют исполнение скрипта.

По умолчанию дополнительные методы выключены. Если хотите включить, согласуйте это с нашими инженерами.

6. Добавьте инициализацию библиотеки

Добавьте вызов initSP (), чтобы библиотека получила конфигурацию с сервера Servicepipe:

await fp.initSP();

Если не вызвать initSP () явно, библиотека инициализируется при вызове get (). Но отдельный вызов делает интеграцию предсказуемее: вы заранее понимаете, когда библиотека готова к работе.

7. Добавьте сбор данных

Добавьте вызов run (), чтобы скрипт собрал параметры клиентского окружения:

await fp.run();

Если не вызвать run () явно, сбор данных произойдёт внутри get ().

Рекомендуем запускать сбор данных о клиентском окружении как можно раньше (например, при открытии страницы), а отправлять их в API DFP — в момент целевого действия (например, входа в аккаунт, отправки формы или подтверждения операции).

Так вы будете получать ответ DFP быстрее и его точность будет выше. Отправка данных настраивается на шаге 10.

8. (Опционально) передайте дополнительный контекст через `customData`

Дополнительные параметры для запроса DFP передавайте в объекте dfpOptions. Позже вы передадите этот объект методу get ().

customData — это произвольная строка с вашими данными. DFP вернёт её в неизменном виде внутри payload как поле custom_data.

Эта строка не используется при создании отпечатков. Она нужна только для ваших служебных целей, чтобы удобнее настраивать бизнес-логику. Например, можно передать тип события, идентификатор формы, источник сценария или любой другой контекст. Это поможет бэкенду понять, к какому действию относится результат DFP.

Пример: один и тот же пользователь может открыть страницу входа, отправить форму, подтвердить платёж или сменить пароль. Через customData вы связываете результат DFP с конкретным событием в своей системе.

Пример объекта dfpOptions с customData:

const dfpOptions = {
  customData: JSON.stringify({
    event: "login_attempt",
    form_id: "main_login"
  })
};

Не передавайте в customData пароли, платёжные данные, токены авторизации и другие секреты.

9. (Опционально) передайте `customID`

Используйте это поле только после согласования с нашими инженерами.

customID — это стабильный идентификатор пользователя, аккаунта или другого объекта в вашей системе. Он позволяет связать этот объект с его user_id ещё на стороне Servicepipe.

Как именно Servicepipe будет использовать эту связь, зависит от вашего сценария. Логику обработки customID, правила, которые нужно реализовать на стороне Servicepipe, и то, как результат отразится в ответе DFP, согласуйте с нашими инженерами. Такая настройка выполняется индивидуально для каждого клиента.

Чтобы передать customID, добавьте его в объект dfpOptions. Если используете и customData, и customID, передайте оба поля в одном объекте:

const dfpOptions = {
  customData: JSON.stringify({
    event: "login_attempt"
  }),
  customID: "account_12345"
};

10. Отправьте собранные данные в DFP и получите результат

Чтобы получить результат DFP, добавьте один из двух вызовов get ().

Если на предыдущих шагах вы создали объект dfpOptions, передайте его методу:

const result = await fp.get(dfpOptions);

Если вы не передаёте customData или customID, вызовите метод без аргументов:

const result = await fp.get();

Метод отправит собранные данные в Servicepipe и вернёт ответ с зашифрованным payload.

11. Отправьте ответ DFP на бэкенд

Передайте ответ DFP на свой бэкенд. Именно там должна происходить расшифровка payload, проверка результата и принятие решения.

await fetch("/api/dfp/check", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify(result)
});

12. Расшифруйте `payload` на бэкенде

Ответ DFP содержит поля для расшифровки:

cipher_type;
iv;
payload;
tag.

Бэкенд расшифровывает payload секретным ключом, который вы получили от нас. Пример расшифрованного payload:

{
  "details": {
    "bot_score": 0.1,
    "engine": "gecko",
    "hosting": false,
    "bot_hosting": false,
    "incognito": false,
    "mobile": false,
    "os": "linux",
    "vpn": false
  },
  "user_id": "3849965ed6d75d7dc67568d620950bbb",
  "referer_md5": "9f0b84073da2ef97a63c2f4179981a2e",
  "timestamp": 1777404974833,
  "version": 1,
  "custom_data": "{\"event\":\"login_attempt\",\"form_id\":\"main_login\"}"
}

О каждом поле подробнее читайте в статье Что значат поля из ответа DFP.

При получении success: false, сохраните request_id и передайте его в нашу тех. поддержку.

13. Проверьте свежесть результата

Ваш бэкенд должен сравнить значение поля timestamp с текущим временем UTC.

Не принимайте ответы старше нескольких секунд — это защитит ваш ресурс от replay-атак, то есть атак, в которых злоумышленник пытается выдать старый результат DFP за новый.

Если timestamp свежий, всё в порядке, можно продолжать обработку.

14. Обработайте данные в рамках своей бизнес-логики

Используйте значения полей user_id, bot_score, incognito, vpn, hosting, engine, os, mobile и custom_data в правилах своего сервиса, чтобы решать ваши бизнес-задачи: например, проверять входы в аккаунт.

Пример логики, которую можно настроить — обнаружение подозрительных попыток входа, основанное на user_id и bot_score. Ваш бэкенд:

Получает user_id из расшифрованного payload.
Проверяет, связан ли этот user_id с аккаунтом пользователя в вашей базе.
Если связь уже есть и bot_score низкий, обрабатывает вход по обычному сценарию.
Если user_id новый и при этом средний/высокий bot_score, запрашивает дополнительное подтверждение для входа.
Сохраняет user_id, результат дополнительной проверки и связь с аккаунтом, чтобы учитывать эти данные при следующих попытках входа.

Мы подготовили для вас готовые инструкции, как использовать DFP для конкретных бизнес-задач:

15. Проверьте интеграцию

После настройки проверьте интеграцию на своём ресурсе:

Откройте страницу, где подключён скрипт DFP.
Выполните действие, для которого вы настроили проверку: например, войдите в аккаунт, отправьте форму или подтвердите операцию.
Убедитесь, что браузер получил результат DFP и отправил его на бэкенд.
Проверьте, что бэкенд расшифровал payload, проверил timestamp, обработал другие поля из ответа DFP и применил ваши правила.

Как интегрировать Digital Fraud Protection

1. Выберите, по какому домену ваш сайт будет обращаться к API DFP

2. Получите токен и секретный ключ

3. Подключите скрипт к сайту

4. Создайте экземпляр ServicepipeFP

5. (Опционально) настройте поведение библиотеки

6. Добавьте инициализацию библиотеки

7. Добавьте сбор данных

8. (Опционально) передайте дополнительный контекст через customData

9. (Опционально) передайте customID

10. Отправьте собранные данные в DFP и получите результат

11. Отправьте ответ DFP на бэкенд

12. Расшифруйте payload на бэкенде

13. Проверьте свежесть результата

14. Обработайте данные в рамках своей бизнес-логики

15. Проверьте интеграцию

4. Создайте экземпляр `ServicepipeFP`

8. (Опционально) передайте дополнительный контекст через `customData`

9. (Опционально) передайте `customID`

12. Расшифруйте `payload` на бэкенде