> ## Documentation Index
> Fetch the complete documentation index at: https://doc.youverify.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégrer le SDK Fraud Insights

> Intégrez le SDK Fraud Insights de Youverify pour collecter des signaux d'appareil et de comportement sur le web et sur mobile.

Le SDK Fraud Insights collecte en arrière-plan des signaux d'appareil et de comportement et les envoie au service Behavioral de Youverify afin d'enrichir le score de risque. Il s'applique à toutes les plateformes, web et mobile, et vos utilisateurs ne le voient jamais.

> [!NOTE]
>
> Ce guide s'applique à toutes les plateformes sur lesquelles vous utilisez Fraud Insights, et pas seulement au web. Le modèle de session, les événements et la configuration ci-dessous sont identiques partout. Les étapes d'installation et les exemples de code utilisent le package JavaScript, `youverify-behavioral-web-sdk`, que vous pouvez ajouter à n'importe quelle application web.

## Fonctionnalités

* **Gestion des sessions** : identifiants de session automatiques et suivi du début et de la fin de session.
* **Signaux d'appareil et de comportement** : fondés sur FingerprintJS et des heuristiques du navigateur.
* **Suivi d'événements** : envoyez des événements personnalisés avec des identifiants d'utilisateur ou d'entité et des métadonnées facultatifs.
* **Réponses typées** : une structure `GetDeviceResponse` riche pour l'analyse des risques.

## Installation

> [tab] npm
>
> ```bash theme={null}
> npm install youverify-behavioral-web-sdk
> ```

> [tab] yarn
>
> ```bash theme={null}
> yarn add youverify-behavioral-web-sdk
> ```

Importez le SDK dans votre application :

```ts theme={null}
import YouverifyBBS, { GetDeviceResponse } from 'youverify-behavioral-web-sdk';
```

## Configuration

Créez une instance avec `new YouverifyBBS(props)` :

```ts theme={null}
const bbs = new YouverifyBBS({
  publicKey: 'YOUR_PUBLIC_KEY',
  applicationName: 'My Web App',
  sandboxEnvironment: true,
  onLoad: (result: GetDeviceResponse) => {
    console.log('BBS loaded', result.sessionId, result.id);
  },
  onError: (error: Error) => {
    console.error('BBS error', error);
  },
  onSessionStart: (sessionId: string) => {
    console.log('Session started', sessionId);
  },
  onSessionEnd: () => {
    console.log('Session ended');
  },
});
```

### Propriétés

**publicKey** `string` *required*

Votre **Public Merchant Key** (clé marchand publique). Vous la trouverez dans la section **API / Webhook** de votre tableau de bord Youverify. Elle peut être utilisée sans risque côté client.

**applicationName** `string` *required*

Nom logique de l'application qui intègre le SDK.

**sandboxEnvironment** `boolean` (default: true)

`true` utilise l'environnement sandbox (préproduction). `false` utilise la production.

**onLoad** `(result: GetDeviceResponse) =\> void`

Appelée après une réponse de signal réussie, par exemple après `get()`.

**onError** `(error: Error) =\> void`

Appelée chaque fois que le SDK rencontre une erreur.

**onSessionStart** `(sessionId: string) =\> void`

Appelée lorsqu'une session est initialisée.

**onSessionEnd** `() =\> void`

Appelée lorsque `close()` se termine et que la session prend fin.

## API principale

### `get(entityId?)`

Initialise ou reprend une session et envoie le signal initial. Renvoie `Promise<void>`.

```ts theme={null}
await bbs.get('user-123');
```

* Le premier appel envoie un événement `session_start`.
* Les appels suivants dans la même session envoient un événement personnalisé « Session resumed ».
* Il déclenche `onLoad(result: GetDeviceResponse)` avec l'ensemble des données d'appareil et de session.

### `sendEvent(eventTitle, entityId?, meta?)`

Envoie un événement comportemental personnalisé pour la session en cours. Renvoie `Promise<void>`.

```ts theme={null}
await bbs.sendEvent('Checkout Started', 'user-123', {
  step: 'payment',
  cartValue: 199.99,
});
```

### `close(entityId?)`

Envoie un événement `session_end` et efface l'état local de la session. Renvoie `Promise<void>`.

```ts theme={null}
await bbs.close('user-123');
```

### `getSessionId()`

Renvoie l'identifiant de la session en cours, ou `null` s'il n'y en a pas.

```ts theme={null}
const sessionId = bbs.getSessionId();
```

### `getSessionDuration()`

Renvoie le temps écoulé, en millisecondes, depuis le début de la session.

```ts theme={null}
const durationMs = bbs.getSessionDuration();
```

## Environnements

Le SDK choisit les URL du backend à partir de la configuration de la build et de l'option `sandboxEnvironment`.

| Paramètre | Environnement |
| - | - |
| `sandboxEnvironment: true` | Sandbox (préproduction) |
| `sandboxEnvironment: false` | Production |

Utilisez la Public Merchant Key de la section **API / Webhook** de votre tableau de bord, en vous assurant qu'elle correspond à l'environnement utilisé.

## Exemples d'utilisation

### Balise script (UMD)

```html theme={null}
<script src="/dist/index.umd.cjs"></script>
<script>
  const bbs = new YouverifyBBS({
    publicKey: 'YOUR_PUBLIC_KEY',
    applicationName: 'Sample Page',
    onLoad: (result) => {
      console.log('Loaded', result.sessionId, result.id);
    },
    onError: (err) => {
      console.error('BBS error', err);
    },
  });

  bbs.get();

  async function sendSampleEvent() {
    await bbs.sendEvent('Sample Button Clicked', 'user-123', {
      source: 'demo',
    });
  }
</script>
```

### React

```tsx theme={null}
import React, { useEffect, useMemo, useState } from 'react';
import YouverifyBBS, { GetDeviceResponse } from 'youverify-behavioral-web-sdk';

export function BBSProvider() {
  const [sessionId, setSessionId] = useState<string | null>(null);
  const [ready, setReady] = useState(false);

  const bbs = useMemo(
    () =>
      new YouverifyBBS({
        publicKey: 'YOUR_PUBLIC_KEY',
        applicationName: 'My React App',
        onSessionStart: setSessionId,
        onLoad: (res: GetDeviceResponse) => {
          setSessionId(res.sessionId);
          setReady(true);
        },
        onError: (err: Error) => {
          console.error('BBS error', err);
        },
      }),
    [],
  );

  useEffect(() => {
    bbs.get();
    return () => {
      bbs.close();
    };
  }, [bbs]);

  const trackClick = async () => {
    await bbs.sendEvent('Button Clicked', 'user-123', { page: 'home' });
  };

  if (!ready) return <div>Loading behavioral signals...</div>;

  return (
    <div>
      <p>Session ID: {sessionId}</p>
      <button onClick={trackClick}>Track behavioral event</button>
    </div>
  );
}
```

## Prise en charge des navigateurs

* Navigateurs modernes compatibles ES2015+.
* L'API Fetch est requise, ou un polyfill.

> [!NOTE]
>
> Transmettez toujours, comme `publicKey`, la Public Merchant Key qui correspond à votre environnement (sandbox ou production). Privilégiez des noms d'événements explicites et joignez des données `meta` pour des analyses plus riches.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.