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

# SDK web

> Notifications push et messages in-app sur votre site, avec un service worker et une clé SDK.

`@dexnotify/web` abonne le navigateur par le Web Push standard (VAPID), l’enregistre comme appareil, remonte clics, événements et conversions, et affiche les messages in-app. Il fonctionne sur Chrome, Edge, Firefox et Safari (macOS, et iOS 16.4+ pour un site ajouté à l’écran d’accueil). Sans dépendance.

## Avant de commencer

1. **La plateforme Web** de l’application configurée dans le dashboard : une paire VAPID (`npx web-push generate-vapid-keys`), l’expéditeur (`mailto:` ou `https://`) et l’origine du site. Voir [Notifications push](https://docs.dexnotify.com/push/introduction.md).
2. **Une clé SDK** (portée `sdk:device`), préréglage « Clé SDK ». Elle est faite pour être publique : elle n’ouvre que les routes de l’appareil. Une clé serveur ne doit jamais aller dans une page.
3. **HTTPS** : les service workers l’exigent (`localhost` passe en développement).

## Installation

```bash theme={null}
npm install @dexnotify/web
```

Servez ensuite le service worker depuis la racine du site, sous `/dexnotify-sw.js`. Deux façons :

```bash Copie theme={null}
cp node_modules/@dexnotify/web/dist/sw.js public/dexnotify-sw.js
```

```js public/dexnotify-sw.js theme={null}
importScripts("https://cdn.jsdelivr.net/npm/@dexnotify/web@1/dist/sw.js");
```

> [!TIP]
>
> Votre site a déjà un service worker ? Ajoutez-y la ligne `importScripts(…)` et passez son enregistrement : `initialize({ serviceWorkerRegistration })`.

## Initialiser

```ts theme={null}
import { DexNotify } from "@dexnotify/web";

void DexNotify.initialize({
  apiKey: "dxn_sdk_…",
  applicationId: "SHOP-482913",
  onError: (error) => console.warn("[dexnotify]", error.code, error.message),
});
```

Sans module, par une balise :

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/@dexnotify/web@1/dist/dexnotify.global.js"></script>
<script>
  DexNotify.initialize({ apiKey: "dxn_sdk_…", applicationId: "SHOP-482913" });
</script>
```

Avec Next.js ou Nuxt, appelez `initialize` dans un effet côté client : hors du navigateur, il ne fait rien. **Aucune méthode ne rejette** : les échecs passent par `onError`.

## Demander l’autorisation

Les navigateurs pénalisent une demande non sollicitée, et Safari comme Firefox exigent un geste de l’utilisateur. Placez-la derrière un bouton :

```ts theme={null}
if (DexNotify.Notifications.canRequestPermission()) {
  bouton.hidden = false;
  bouton.onclick = () => DexNotify.Notifications.requestPermission();
}
```

Accordée, le navigateur est abonné et enregistré aussitôt. `initialize({ requestPermission: true })` demande dès le chargement, à vos risques.

> [!NOTE]
>
> Sur le web, l’appareil naît de l’abonnement : avant l’autorisation, il n’existe pas encore. Les tags posés avant sont gardés et partent à ce moment-là.

## Utilisateurs et tags

```ts theme={null}
// À la connexion : ce navigateur devient celui de ce client.
await DexNotify.login(customer.id);

await DexNotify.User.addTags({ plan: "pro", ville: "Dakar" });
await DexNotify.User.removeTag("essai");

// À la déconnexion.
await DexNotify.logout();
```

## Événements et conversions

```ts theme={null}
DexNotify.User.trackEvent("panier_valide", { montant: 25000 });
DexNotify.Session.addOutcomeWithValue("achat", 25000);
```

Les événements alimentent les segments et les déclencheurs in-app ; les conversions sont attribuées au dernier push ou in-app cliqué. Une session commence au chargement, puis après 30 minutes d’onglet caché.

## Clics et abonnement

```ts theme={null}
DexNotify.Notifications.addEventListener("click", (notification) => {
  console.log(notification.notificationId, notification.url, notification.data);
});

DexNotify.User.pushSubscription.addEventListener("change", ({ current }) => {
  console.log(current.optedIn);
});

// Désabonnement sans perdre l'appareil, puis réabonnement.
await DexNotify.User.pushSubscription.optOut();
await DexNotify.User.pushSubscription.optIn();
```

Le clic ouvre le lien web du message (`webUrl`, sinon `deeplink` s’il est une adresse `https`), ou reprend l’onglet du site.

## Messages in-app

Les messages in-app publiés s’affichent seuls, selon leurs déclencheurs et leur audience. Ils sont rendus dans un Shadow DOM, que les styles du site n’atteignent pas ; le HTML d’un message tourne dans une iframe isolée, sans accès à la page.

```ts theme={null}
DexNotify.InAppMessages.addTrigger("page", "panier");
DexNotify.InAppMessages.setPaused(true); // pendant un paiement, par exemple
DexNotify.InAppMessages.addEventListener("click", (event) => console.log(event.elementId));
```

`initialize({ inAppMessages: false })` les désactive.

## Consentement

```ts theme={null}
DexNotify.setConsentRequired(true); // avant initialize
void DexNotify.initialize(options);

// Une fois le consentement recueilli :
DexNotify.setConsentGiven(true);
```

Tant que le consentement manque, rien ne quitte le navigateur.


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