@fingerru/vue 1.0.0-next.0 → 1.0.0-next.2

package/README.md

@@ -1,7 +1,6 @@
 # @fingerru/vue
 
-Vue 3-обёртка над `@fingerru/agent`. Подключите плагин один раз при создании
-приложения и получайте данные visitor через Composition API или Options API.
+Vue 3 SDK для идентификации посетителей сайта.
 
 ## Установка
 
@@ -9,9 +8,12 @@ Vue 3-обёртка над `@fingerru/agent`. Подключите плагин
 pnpm add @fingerru/vue @fingerru/agent
 ```
 
-## Подключение плагина
+## Быстрый старт
 
-Создайте Fingprint-плагин при инициализации приложения:
+### 1. Подключите плагин
+
+Зарегистрируйте `createFingprint()` при создании приложения. Передайте публичный
+ключ проекта в `apiKey`:
 
 ```ts
 import { createApp } from 'vue'
@@ -27,84 +29,74 @@ createApp(App)
   .mount('#app')
 ```
 
-`endpoint` — полный абсолютный URL API или proxy. Если его не передавать,
-`@fingerru/agent` использует URL по умолчанию, встроенный в bundle.
+При необходимости укажите `endpoint` для своего API или proxy, `runtimeUrl` для
+своего CDN и `loadTimeout` для времени загрузки runtime.
 
-```ts
-createFingprint({
-  apiKey: 'pk_live_example',
-  endpoint: 'https://api.example.com/api/visit',
-  runtimeUrl: 'https://cdn.example.com/agent.min.js',
-  loadTimeout: 10_000,
-  cache: {
-    storage: 'sessionStorage',
-    duration: 3600,
-  },
-})
+### 2. Используйте `useVisitorData`
+
+Composable возвращает visitor-данные и состояние запроса:
+
+```vue
+<script setup lang="ts">
+import { useVisitorData } from '@fingerru/vue'
+
+const { data, error, isLoading } = useVisitorData({ immediate: true })
+</script>
+
+<template>
+  <p v-if="isLoading">Получаем данные…</p>
+  <p v-else-if="error">Не удалось получить данные: {{ error.message }}</p>
+  <p v-else>Visitor: {{ data?.user }}</p>
+</template>
 ```
 
-## Composition API
+Передайте `{ immediate: true }`, чтобы выполнить запрос после монтирования
+компонента. По умолчанию запрос запускается только после вызова `getData()`.
+
+## Запрос по действию пользователя
 
-`useVisitorData()` доступен в компонентах, которые находятся внутри приложения
-с подключённым `createFingprint()`. Он возвращает реактивные refs `data`,
-`error`, `isLoading` и `isFetched`, а также метод `getData()`.
+Используйте `getData()`, когда идентификатор нужен при конкретном действии,
+например при отправке формы:
 
 ```vue
 <script setup lang="ts">
 import { useVisitorData } from '@fingerru/vue'
-import { watch } from 'vue'
 
-const { data, error, isFetched, isLoading, getData } = useVisitorData({
-  // Укажите true, если идентификация нужна сразу после mount.
-  immediate: false,
-})
+const { getData, isLoading } = useVisitorData()
 
-watch(data, (visitor) => {
-  if (visitor) {
-    console.log(visitor.user)
-  }
-})
+async function handleSubmit() {
+  const visitor = await getData()
+  console.log(visitor.user)
+}
 </script>
 
 <template>
-  <button type="button" :disabled="isLoading" @click="getData()">Получить visitor</button>
-
-  <p v-if="isLoading">Получаем visitor…</p>
-  <p v-else-if="error">{{ error.message }}</p>
-  <p v-else-if="isFetched">Visitor: {{ data?.user }}</p>
+  <button :disabled="isLoading" @click="handleSubmit">Отправить</button>
 </template>
 ```
 
-В `<template>` Vue автоматически разворачивает refs. В обычном TypeScript-коде
-используйте `.value`, например `data.value?.user`.
-
-По умолчанию запрос не запускается автоматически. Передайте
-`{ immediate: true }`, чтобы выполнить его после монтирования компонента.
-Повторные вызовы `getData()` одного composable во время активного запроса
-получают один и тот же `Promise`.
+Для `useVisitorData()` можно задать `timeout` и `ignoreCache`; эти же параметры
+можно передать непосредственно в `getData()`.
 
-### Параметры запроса
+## Кеширование
 
-Параметры можно указать при создании composable или передать в конкретный
-вызов. Параметры вызова имеют приоритет:
+Кеширование выключено по умолчанию. Чтобы включить его, добавьте `cache` в
+настройки плагина:
 
 ```ts
-const { getData } = useVisitorData({ timeout: 5_000 })
-
-// Запрашивает новые данные, игнорируя cache.
-const visitor = await getData({ ignoreCache: true })
+createFingprint({
+  apiKey: 'pk_live_example',
+  cache: {
+    storage: 'sessionStorage',
+    duration: 3600,
+  },
+})
 ```
 
-| Параметр      | Описание                                                |
-| ------------- | ------------------------------------------------------- |
-| `immediate`   | Выполнить запрос после mount. По умолчанию — `false`.   |
-| `timeout`     | Максимальное время API-запроса в миллисекундах.         |
-| `ignoreCache` | Не использовать сохранённый результат для этого вызова. |
-
 ## Options API
 
-После подключения плагин добавляет типизированный `$fingprint` во все
-компоненты. Через него доступен `getVisitorData()`:
+Плагин добавляет `$fingprint` в компоненты. Для получения данных вызовите
+`this.$fingprint.getVisitorData()`:
 
 ```vue
 <script lang="ts">
@@ -112,23 +104,19 @@ import { defineComponent } from 'vue'
 
 export default defineComponent({
   methods: {
-    async getVisitorData(): Promise<void> {
+    async getVisitorData() {
       const visitor = await this.$fingprint.getVisitorData()
       console.log(visitor.user)
     },
   },
 })
 </script>
-
-<template>
-  <button type="button" @click="getVisitorData">Получить visitor</button>
-</template>
 ```
 
 ## Nuxt
 
-Fingerprinting использует browser runtime, поэтому подключайте плагин только
-на клиенте. Создайте `plugins/fingprint.client.ts`:
+Fingerprinting работает только в браузере. Зарегистрируйте SDK в клиентском
+плагине `plugins/fingprint.client.ts`:
 
 ```ts
 import { createFingprint } from '@fingerru/vue'
@@ -144,7 +132,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 })
 ```
 
-Публичный ключ передавайте через публичную runtime-конфигурацию:
+Передайте публичный ключ через runtime-конфигурацию:
 
 ```ts
 export default defineNuxtConfig({
@@ -155,3 +143,21 @@ export default defineNuxtConfig({
   },
 })
 ```
+
+Используйте `useVisitorData()` в клиентском компоненте, например в
+`components/VisitorData.client.vue`:
+
+```vue
+<script setup lang="ts">
+import { useVisitorData } from '@fingerru/vue'
+
+const { data, getData, isLoading } = useVisitorData()
+</script>
+
+<template>
+  <button :disabled="isLoading" @click="getData()">
+    Получить visitor
+  </button>
+  <p v-if="data">Visitor: {{ data.user }}</p>
+</template>
+```

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "@fingerru/vue",
-  "version": "1.0.0-next.0",
+  "version": "1.0.0-next.2",
   "description": "Vue SDK for the Fingprint service.",
+  "keywords": [
+    "browser",
+    "fingerprint",
+    "fingerprinting",
+    "browser fingerprint",
+    "visitor identification",
+    "identification",
+    "device fingerprint",
+    "fraud",
+    "fraud detection",
+    "fraud prevention",
+    "privacy",
+    "vue",
+    "vue 3"
+  ],
   "type": "module",
   "module": "./dist/index.js",
   "types": "./dist/types/index.d.ts",
@@ -16,7 +31,7 @@
     "dist"
   ],
   "dependencies": {
-    "@fingerru/agent": "1.0.0-next.0"
+    "@fingerru/agent": "1.0.0-next.2"
   },
   "devDependencies": {
     "vue": "^3.0.0",
@@ -26,7 +41,6 @@
   "peerDependencies": {
     "vue": "^3.0.0"
   },
-  "repository": "https://github.com/ifksco/fingerprint_agent",
   "license": "MIT",
   "sideEffects": false,
   "publishConfig": {