> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Web SDK - Configuration du code personnalisé
> Guide complet pour configurer les notifications Web Push OneSignal à l'aide de l'intégration de code personnalisé. Configurez le SDK JavaScript, les service workers et les certificats Safari pour Chrome, Firefox, Safari et d'autres navigateurs Web.
export const SdkReleasesIframe = ({sdkFilter = undefined, viewMode = undefined, height, ...frameProps}) => {
const baseUrl = 'https://onesignal.github.io/sdk-releases';
const buildUrl = (theme, sdkFilter, viewMode) => {
const url = new URL(baseUrl);
const params = new URLSearchParams();
if (theme) {
params.set('theme', theme);
}
if (sdkFilter) {
params.set('sdk', sdkFilter);
}
if (viewMode) {
params.set('viewMode', viewMode);
}
if (params.toString()) {
url.search = params.toString();
}
return url.toString();
};
const detectTheme = () => {
if (document.documentElement.classList.contains('dark')) {
return 'dark';
}
return 'light';
};
const [theme, setTheme] = useState('light');
const [iframeSrc, setIframeSrc] = useState(() => {
const initialTheme = detectTheme();
return buildUrl(initialTheme, sdkFilter, viewMode);
});
useEffect(() => {
const currentTheme = detectTheme();
setTheme(currentTheme);
setIframeSrc(buildUrl(currentTheme, sdkFilter, viewMode));
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
const handleThemeChange = () => {
const newTheme = detectTheme();
setTheme(newTheme);
setIframeSrc(buildUrl(newTheme, sdkFilter, viewMode));
};
if (mediaQuery.addEventListener) {
mediaQuery.addEventListener('change', handleThemeChange);
} else {
mediaQuery.addListener(handleThemeChange);
}
window.addEventListener('storage', handleThemeChange);
const observer = new MutationObserver(handleThemeChange);
observer.observe(document.documentElement, {
attributes: true,
attributeFilter: ['class', 'data-theme']
});
return () => {
if (mediaQuery.removeEventListener) {
mediaQuery.removeEventListener('change', handleThemeChange);
} else {
mediaQuery.removeListener(handleThemeChange);
}
window.removeEventListener('storage', handleThemeChange);
observer.disconnect();
};
}, [sdkFilter, viewMode]);
const getIframeHeight = () => {
if (viewMode === 'table') {
return '450';
}
if (viewMode === 'mini') {
return '170';
}
return '800';
};
const iframeHeight = height || getIframeHeight();
return
;
};
Utilisez cette configuration avec code personnalisé uniquement si vous avez besoin d'une configuration avancée ou d'un contrôle programmatique. Pour la plupart des utilisateurs, nous recommandons :
* [Configuration push web typique](./web-push-setup)
* [Configuration WordPress](./wordpress)
* [Configuration Shopify](./shopify)
Si vous utilisez un framework JavaScript, suivez ces guides spécialisés :
* [Configuration Angular](./angular-setup)
* [Configuration React JS](./react-js-setup)
* [Configuration Vue JS](./vue-js-setup)
## Prérequis
* Site web HTTPS : Le push web ne fonctionne pas en HTTP ni en mode navigation privée/incognito.
* Accès au serveur : Vous devrez télécharger un fichier service worker sur votre site.
* Origine unique : Le push web suit la [politique de même origine](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy). Si vous avez plusieurs origines (domaines/sous-domaines), vous aurez besoin de plusieurs applications OneSignal (une par origine). Pour vous conformer à cette limitation du navigateur, vous pouvez :
* Rediriger le trafic vers une seule origine pour les abonnements.
* Créer plusieurs applications OneSignal, une par origine.
***
## Configurer votre application et plateforme OneSignal
Dans le tableau de bord OneSignal :
* Accédez à **Settings > Push & In-App > Web**.
* Sélectionnez le type d'intégration **Custom Code**.
### Configuration du site
Ajoutez les détails du site :
* **Site Name** : Le nom de votre site et le titre de notification par défaut.
* **Site URL** : L'[origine](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) exacte de votre site, par exemple `https://yourdomain.com`. Évitez d'utiliser `www.` si votre site n'est pas configuré ainsi. Consultez les [Prérequis](#requirements) si vous avez plusieurs origines.
* **Auto Resubscribe** : Activez cette option pour réabonner automatiquement les utilisateurs qui effacent leurs données de navigateur lorsqu'ils reviennent sur votre site (sans nouvelle invite d'autorisation).
* **Default Icon URL** : Téléchargez une image PNG ou JPG carrée de `256x256px` qui apparaît dans les notifications et les invites. Si non définie, une icône de cloche est utilisée par défaut.
#### Tests locaux
Pour tester sur localhost, utilisez une application OneSignal séparée de votre application de production et ajoutez `allowLocalhostAsSecureOrigin: true` à vos options `init`.
Si vous testez localhost sur HTTPS avec un certificat auto-signé, vous devrez peut-être indiquer à Chrome d'ignorer les certificats invalides avec `--allow-insecure-localhost`. Firefox et Safari fournissent des mécanismes intégrés pour ajouter des exceptions pour les certificats de sécurité.
```html theme={null}
```
### Certificat push web Safari (optionnel)
OneSignal fournit automatiquement des certificats Safari sans frais. N'activez cette option que si vous avez des certificats push web Safari existants que vous devez utiliser.
Si activé, téléchargez votre `Certificat push .p12 Safari Web` et entrez le mot de passe.
Cliquez sur **Save** pour continuer.
### Télécharger les fichiers service worker
Sur la page suivante de la configuration push web, vous recevrez le fichier service worker `OneSignalSDKWorker.js`.
Le SDK web recherche ce fichier à la racine de votre site par défaut, par exemple `https://yourdomain.com/OneSignalSDKWorker.js`. Vous pouvez modifier l'emplacement, le nom et la portée du fichier dans le code.
Configuration avancée du service worker, intégration personnalisée et migration depuis d'autres fournisseurs.
### Ajouter du code au site
Ajoutez ce code à la section `` de votre site web. Remplacez :
* `YOUR_ONESIGNAL_APP_ID` par votre App ID réel depuis le tableau de bord OneSignal
* `YOUR_SAFARI_WEB_ID` par votre Safari Web ID réel depuis le tableau de bord OneSignal
```html HTML theme={null}
```
### Support des push web iOS
Apple a commencé à prendre en charge les notifications push web sur les iPhone et iPad fonctionnant sous iOS 16.4+. Contrairement aux appareils Android où le push web fonctionne simplement si visité sur un navigateur compatible, Apple a ajouté quelques exigences supplémentaires telles qu'un fichier `manifest.json` et une action de l'utilisateur pour ajouter votre site à son écran d'accueil.
Ajoutez le fichier `manifest.json` requis et guidez les utilisateurs pour ajouter votre site à leur écran d'accueil.
***
## Tester l'intégration du SDK OneSignal
Ce guide vous aide à vérifier que votre intégration du SDK OneSignal fonctionne correctement en testant les notifications push et l'enregistrement des abonnements.
### Vérifier les abonnements web push
* Utilisez Chrome, Firefox, Edge ou Safari pendant les tests.
* **N'utilisez pas le mode Navigation privée ou Incognito.** Les utilisateurs ne peuvent pas s'abonner aux notifications push dans ces modes.
* Les invites devraient apparaître en fonction de votre configuration des [invites de permission](/docs/en/permission-requests).
* Cliquez sur **Autoriser** dans l'invite native pour vous abonner aux notifications push.
* Allez dans **Audience > Subscriptions**.
* Vous devriez voir une nouvelle entrée avec le statut **Subscribed**.
Vous avez créé avec succès un [abonnement web push](/docs/en/subscriptions).
Les abonnements web push sont créés lorsque les utilisateurs s'abonnent pour la première fois aux notifications push sur votre site.
### Configurer les abonnements de test
Les abonnements de test sont utiles pour tester une notification push avant d'envoyer un message.
Dans le tableau de bord, à côté de l'abonnement, cliquez sur le bouton **Options (trois points)** et sélectionnez **Add to Test Users**.
Nommez l'abonnement afin de pouvoir identifier facilement votre appareil plus tard dans l'**onglet Test Users**.
Allez dans **Audience > Segments > New Segment**.
Nommez le segment `Test Users` (le nom est important car il sera utilisé plus tard).
Vous avez créé avec succès un segment d'utilisateurs de test.
Nous pouvons maintenant tester l'envoi de messages à cet appareil individuel et à des groupes d'utilisateurs de test.
### Envoyer un push de test via l'API
Dans votre tableau de bord OneSignal, allez dans **Settings > [Keys & IDs](/docs/en/keys-and-ids)**.
Remplacez `YOUR_APP_API_KEY` et `YOUR_APP_ID` dans le code ci-dessous par vos clés réelles. Ce code utilise le segment `Test Users` que nous avons créé plus tôt.
```curl theme={null}
curl -X \
POST --url 'https://api.onesignal.com/notifications' \
--header 'content-type: application/json; charset=utf-8' \
--header 'authorization: Key YOUR_APP_API_KEY' \
--data \
'{
"app_id": "YOUR_APP_ID",
"target_channel": "push",
"name": "Testing basic setup",
"headings": {
"en": "👋"
},
"contents": {
"en": "Hello world!"
},
"included_segments": [
"Test Users"
],
"chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'
```
Exécutez le code dans votre terminal.
Si toutes les étapes de configuration ont été complétées avec succès, les abonnements de test devraient recevoir une notification.
Seul Chrome prend en charge les images. Les images apparaîtront petites dans la vue de notification réduite. Développez la notification pour voir l'image complète.
Dans votre tableau de bord, allez dans **Delivery > Sent Messages**, puis cliquez sur le message pour afficher les statistiques. Vous devriez voir la statistique **confirmed**, ce qui signifie que l'appareil a reçu la push.
Safari ne prend pas en charge la Livraison confirmée.
Consultez les statistiques de livraison, de clics et de conversion pour vos notifications push.
Vous avez envoyé avec succès une notification via l'API à un segment.
Si les notifications n'arrivent pas, contactez `support@onesignal.com` avec les éléments suivants :
* La requête et la réponse API (copiez-collez dans un fichier `.txt`)
* Votre Subscription ID
* L'URL de votre site Web avec le code OneSignal
***
## Identification des utilisateurs
La section précédente a couvert la création d'[Abonnements](/docs/en/subscriptions) web push. Cette section s'étend à l'identification des [Utilisateurs](/docs/en/users) sur tous leurs abonnements (y compris push, email et SMS) en utilisant le SDK OneSignal. Elle couvre les External IDs, les tags, les abonnements multicanaux, la confidentialité et le suivi des événements pour vous aider à unifier et engager les utilisateurs sur toutes les plateformes.
### Attribuer un External ID
Utilisez un External ID pour identifier les utilisateurs de manière cohérente sur tous les appareils, adresses e-mail et numéros de téléphone en utilisant l'identifiant utilisateur de votre backend. Cela garantit que votre messagerie reste unifiée sur tous les canaux et systèmes tiers (particulièrement important pour les [Intégrations](/docs/en/integrations)).
Définissez l'External ID avec la [méthode `login`](/docs/en/web-sdk-reference#login-external-id) du SDK chaque fois qu'un utilisateur est identifié par votre application.
OneSignal génère des ID uniques en lecture seule pour les abonnements (Subscription ID) et les utilisateurs (OneSignal ID).
Lorsque les utilisateurs téléchargent votre application sur différents appareils, s'abonnent à votre site Web et/ou vous fournissent des adresses e-mail et des numéros de téléphone en dehors de votre application, de nouveaux abonnements seront créés.
La définition de l'External ID via le SDK est fortement recommandée pour identifier les utilisateurs sur tous leurs abonnements, quelle que soit la façon dont ils sont créés.
### Ajouter des tags de données
Les [Tags](/docs/en/add-user-data-tags) sont des paires clé-valeur de données chaîne que vous pouvez utiliser pour stocker les propriétés des utilisateurs (comme `username`, `role` ou les préférences) et les événements (comme `purchase_date`, `game_level` ou les interactions utilisateur). Les tags alimentent la [Personnalisation des messages](/docs/en/message-personalization) et la [Segmentation](/docs/en/segmentation) avancées permettant des cas d'utilisation plus avancés.
Définissez les tags avec les [méthodes `addTag` et `addTags`](/docs/en/web-sdk-reference#addtag-%2C-addtags) du SDK au fur et à mesure que les événements se produisent dans votre application.
Dans cet exemple, l'utilisateur a atteint le niveau 6 identifiable par le tag appelé `current_level` défini sur une valeur de `6`.
Nous pouvons créer un segment d'utilisateurs ayant un niveau entre 5 et 10, et l'utiliser pour envoyer des messages ciblés et personnalisés :
### Ajouter des abonnements email et/ou SMS
Le SDK OneSignal crée automatiquement des abonnements web push lorsque les utilisateurs optent pour les recevoir. Vous pouvez également atteindre les utilisateurs via les canaux email et SMS en créant les abonnements correspondants.
* Utilisez la [méthode `addEmail`](/docs/en/web-sdk-reference#addemail-%2C-removeemail) pour créer des abonnements email.
* Utilisez la [méthode `addSms`](/docs/en/web-sdk-reference#addsms-%2C-removesms) pour créer des abonnements SMS.
Si l'adresse e-mail et/ou le numéro de téléphone existent déjà dans l'application OneSignal, le SDK l'ajoutera à l'utilisateur existant, il ne créera pas de doublons.
Vous pouvez afficher les utilisateurs unifiés via **Audience > Users** dans le tableau de bord ou avec l'[API View user](/reference/view-user).
Meilleures pratiques pour la communication multicanale
* Obtenez un consentement explicite avant d'ajouter des abonnements email ou SMS.
* Expliquez les avantages de chaque canal de communication aux utilisateurs.
* Fournissez des préférences de canal afin que les utilisateurs puissent sélectionner les canaux qu'ils préfèrent.
***
### Confidentialité et consentement de l'utilisateur
Pour contrôler quand OneSignal collecte les données utilisateur, utilisez les méthodes de contrôle du consentement du SDK :
* [`setConsentRequired(true)`](/docs/en/web-sdk-reference#setconsentrequired) : Empêche la collecte de données jusqu'à ce que le consentement soit donné.
* [`setConsentGiven(true)`](/docs/en/web-sdk-reference#setconsentgiven) : Active la collecte de données une fois le consentement accordé.
Pour en savoir plus sur la confidentialité et la sécurité :
Examinez les données que le SDK OneSignal collecte auprès des utilisateurs.
Gérez et protégez les données utilisateur conformément aux réglementations sur la confidentialité.
***
## Écouter les événements push, utilisateur et in-app
Utilisez les écouteurs du SDK pour réagir aux actions des utilisateurs et aux changements d'état.
Le SDK fournit plusieurs écouteurs d'événements auxquels vous pouvez vous connecter. Consultez notre [guide de référence du SDK](/docs/en/web-sdk-reference) pour plus de détails.
### Événements de notification push
* [Écouteur d'événement de clic](/docs/en/web-sdk-reference#click) : Détecter quand une notification est tapée.
* [Écouteur du cycle de vie au premier plan](/docs/en/web-sdk-reference#foregroundwilldisplay) : Contrôler comment les notifications se comportent au premier plan.
### Changements d'état de l'utilisateur
* [Écouteur d'événement de changement d'état utilisateur](/docs/en/web-sdk-reference#addeventlistener-user-state) : Détecter quand l'External ID est défini.
* [Observateur de permission](/docs/en/web-sdk-reference#permissionchange) : Suivre l'interaction spécifique de l'utilisateur avec l'invite d'autorisation push native.
* [Observateur de changement d'abonnement push](/docs/en/web-sdk-reference#addeventlistener-push-subscription-changes) : Suivre quand le statut de l'abonnement push change.
***
## Configuration avancée et capacités
Explorez davantage de capacités pour améliorer votre intégration :
Passez d'un autre fournisseur de push à OneSignal.
Connectez OneSignal avec des outils et plateformes tiers.
Ajoutez des boutons interactifs aux notifications push.
Envoyez des messages localisés aux utilisateurs dans leur langue préférée.
Sécurisez votre intégration SDK avec la vérification d'identité côté serveur.
Suivez les événements de conversion personnalisés liés à vos messages.
### Configuration et référence du SDK Web
Activez toutes les fonctionnalités clés de web push pour votre intégration.
Détails complets sur les méthodes disponibles et les options de configuration.
Félicitations ! Vous avez terminé avec succès le guide de configuration du SDK Web.
***
***
## FAQ
### Ai-je besoin de HTTPS pour les notifications push web ?
Oui. Tous les navigateurs modernes nécessitent HTTPS pour la prise en charge des notifications push. Si votre site utilise HTTP, vous devez migrer vers HTTPS avant de configurer le push web.
### Puis-je utiliser cette configuration avec une application monopage (SPA) ?
Oui. La configuration Custom Code est l'approche recommandée pour les SPA construites avec des frameworks comme React, Angular ou Vue. Consultez les guides spécifiques aux frameworks en [haut de cette page](#) pour [Angular](./angular-setup), [React](./react-js-setup) et [Vue](./vue-js-setup).
### Que se passe-t-il si un utilisateur efface ses données de navigateur ?
L'abonnement push de l'utilisateur est supprimé. Si **Auto Resubscribe** est activé, il est automatiquement réabonné la prochaine fois qu'il visite votre site.
***
## Pages associées
Configurez quand et comment les utilisateurs sont invités à s'abonner.
Référence API complète pour le SDK Web OneSignal.