Configuration du SDK Web Angular

Aperçu

Ce guide explique comment configurer les notifications push dans votre application Angular en utilisant le package onesignal-ngx, couvrant tout de l’installation à la configuration et à la gestion des service workers.

Exigences

Application et plateforme OneSignal configurées. Consultez Configuration Web Push pour commencer.

Installation

Installez le package onesignal-ngx en utilisant votre gestionnaire de packages préféré :

npm install --save onesignal-ngx

Initialisation

Importez le service OneSignal et initialisez-le dans votre composant racine :

import { OneSignal } from 'onesignal-ngx';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  constructor(private oneSignal: OneSignal) {
    this.oneSignal.init({
      appId: 'YOUR-ONESIGNAL-APP-ID',
    });
  }
}

Attendre l’initialisation

Vous pouvez gérer la promesse retournée par init() de deux manières :

// Option 1 : async/await
await this.oneSignal.init({ appId: 'YOUR-APP-ID' });
// poursuivre avec d'autres logiques

// Option 2 : .then()
this.oneSignal.init({ appId: 'YOUR-APP-ID' }).then(() => {
  // sûr d'interagir avec les API OneSignal
});

Personnaliser les options d’initialisation

Vous pouvez personnaliser votre initialisation avec des paramètres init supplémentaires.

Paramètres du Service Worker

Pour éviter les conflits avec le propre service worker d’Angular (utilisé dans les configurations PWA), spécifiez une portée et un chemin uniques pour le service worker OneSignal. Si vous ne l’avez pas encore fait, vous devrez télécharger le fichier Service Worker OneSignal à ajouter à votre site. Le fichier OneSignalSDKWorker.js doit être accessible publiquement. Vous pouvez le placer dans votre répertoire public, à la racine de niveau supérieur ou dans un sous-répertoire. Cependant, si vous placez le fichier dans un sous-répertoire et/ou avez un autre service worker pour votre site, assurez-vous alors de spécifier le chemin. Consultez Service Worker OneSignal pour plus de détails.

Option	Description
`serviceWorkerParam`	Portée contrôlée par le worker OneSignal. Recommandation : Utilisez un sous-chemin personnalisé (par ex., `"/onesignal/"`).
`serviceWorkerPath`	Chemin vers votre fichier service worker OneSignal hébergé (par ex., `"onesignal/OneSignalSDKWorker.js"`). Doit être accessible publiquement.

Exemple :

this.oneSignal.init({
  appId: 'YOUR-APP-ID',
  serviceWorkerParam: {
    scope: '/onesignal/'
  },
  serviceWorkerPath: 'onesignal/OneSignalSDKWorker.js'
});

Héberger le worker

Racine publique (par défaut) : /OneSignalSDKWorker.js
Dossier personnalisé (recommandé) : par ex., /onesignal/OneSignalSDKWorker.js comme défini à l’étape précédente.

Vérifier l’hébergement du service worker

Visitez le chemin dans votre navigateur pour confirmer qu’il est accessible. Si vous avez utilisé la racine :

https://your-site.com/OneSignalSDKWorker.js

Si vous utilisez le chemin d’exemple :

https://your-site.com/onesignal/OneSignalSDKWorker.js

Il devrait retourner du JavaScript valide.

Important pour les utilisateurs d’Angular CLI

Si le fichier n’est pas servi, assurez-vous qu’il est listé dans votre angular.json sous le tableau assets :

json

"assets": [
  "src/assets",
  "onesignal/OneSignalSDKWorker.js"
]

Notes importantes

Éviter l’initialisation en double en développement
- Lors de tests dans un environnement de développement, vous pourriez voir le SDK OneSignal s’initialiser deux fois, ce qui peut causer des erreurs de console.
- Cela se produit en raison de <React.StrictMode> qui fait s’exécuter les effets deux fois en développement. Pour résoudre ce problème, supprimez <React.StrictMode> de votre composant racine pendant le développement.

Le mode strict n’affecte que le développement—il n’impacte pas les builds de production.

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

Lancez votre site sur un appareil de test.

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.
Cliquez sur Autoriser dans l’invite native pour vous abonner aux notifications push.

Invite de permission native du navigateur demandant à l'utilisateur d'autoriser ou bloquer les notifications

Vérifiez votre tableau de bord OneSignal

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. 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.

Ajouter aux abonnements de test.

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 votre abonnement.

Nommez l’abonnement afin de pouvoir identifier facilement votre appareil plus tard dans l’onglet Test Users.

Créer un segment d'utilisateurs de test.

Allez dans Audience > Segments > New Segment.

Nommez le segment.

Nommez le segment Test Users (le nom est important car il sera utilisé plus tard).

Ajoutez le filtre Test Users et cliquez sur Create Segment.

Éditeur de segment avec le filtre Test Users sélectionné et le segment nommé Test Users

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

Obtenez votre clé API d'application et votre ID d'application.

Dans votre tableau de bord OneSignal, allez dans Settings > Keys & IDs.

Mettez à jour le code fourni.

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 -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.

Exécutez le code dans votre terminal.

Vérifiez les images et la livraison confirmée.

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.

Notification push développée sur Chrome macOS affichant une image personnalisée

Vérifiez la livraison confirmée.

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.

Rapports de messages de notifications push

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 web push. Cette section s’étend à l’identification des Utilisateurs 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). Définissez l’External ID avec la méthode login 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 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 et la Segmentation avancées permettant des cas d’utilisation plus avancés. Définissez les tags avec les méthodes addTag et 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 pour créer des abonnements email.
Utilisez la méthode addSms 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.

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) : Empêche la collecte de données jusqu’à ce que le consentement soit donné.
setConsentGiven(true) : Active la collecte de données une fois le consentement accordé.

Pour en savoir plus sur la confidentialité et la sécurité :

Données collectées par le SDK

Examinez les données que le SDK OneSignal collecte auprès des utilisateurs.

Gestion des données personnelles

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 pour plus de détails.

Événements de notification push

Écouteur d’événement de clic : Détecter quand une notification est tapée.
Écouteur du cycle de vie au premier plan : 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 : Détecter quand l’External ID est défini.
Observateur de permission : Suivre l’interaction spécifique de l’utilisateur avec l’invite d’autorisation push native.
Observateur de changement d’abonnement push : 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 :

Migrer vers OneSignal

Passez d’un autre fournisseur de push à OneSignal.

Intégrations

Connectez OneSignal avec des outils et plateformes tiers.

Boutons d'action

Ajoutez des boutons interactifs aux notifications push.

Messagerie multilingue

Envoyez des messages localisés aux utilisateurs dans leur langue préférée.

Vérification d'identité

Sécurisez votre intégration SDK avec la vérification d’identité côté serveur.

Résultats personnalisés

Suivez les événements de conversion personnalisés liés à vos messages.

Configuration et référence du SDK Web

Configuration web push

Activez toutes les fonctionnalités clés de web push pour votre intégration.

Référence du SDK Web

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.

Besoin d’aide ?Discutez avec notre équipe d’assistance ou envoyez un e-mail à support@onesignal.comVeuillez inclure :

Les détails du problème que vous rencontrez et les étapes de reproduction si disponibles
Votre OneSignal App ID
L’External ID ou le Subscription ID le cas échéant
L’URL du message que vous avez testé dans le OneSignal Dashboard le cas échéant
Tous les journaux ou messages d’erreur pertinents

Nous serons ravis de vous aider !

Documentation développeur

SDK mobiles

SDK web

Activités en direct

Configuration desktop et montre

Documentation Index

​Aperçu

​Exigences

​Installation

​Initialisation

​Attendre l’initialisation

​Personnaliser les options d’initialisation

​Paramètres du Service Worker

​Héberger le worker

​Vérifier l’hébergement du service worker

​Important pour les utilisateurs d’Angular CLI

​Notes importantes

​Tester l’intégration du SDK OneSignal

​Vérifier les abonnements web push

​Configurer les abonnements de test

​Envoyer un push de test via l’API

Rapports de messages de notifications push

​Identification des utilisateurs

​Attribuer un External ID

​Ajouter des tags de données

​Ajouter des abonnements email et/ou SMS

​Confidentialité et consentement de l’utilisateur

Données collectées par le SDK

Gestion des données personnelles

​Écouter les événements push, utilisateur et in-app

​Événements de notification push

​Changements d’état de l’utilisateur

​Configuration avancée et capacités

Migrer vers OneSignal

Intégrations

Boutons d'action

Messagerie multilingue

Vérification d'identité

Résultats personnalisés

​Configuration et référence du SDK Web

Configuration web push

Référence du SDK Web

Aperçu

Exigences

Installation

Initialisation

Attendre l’initialisation

Personnaliser les options d’initialisation

Paramètres du Service Worker

Héberger le worker

Vérifier l’hébergement du service worker

Important pour les utilisateurs d’Angular CLI

Notes importantes

Tester l’intégration du SDK OneSignal

Vérifier les abonnements web push

Configurer les abonnements de test

Envoyer un push de test via l’API

Identification des utilisateurs

Attribuer un External ID

Ajouter des tags de données

Ajouter des abonnements email et/ou SMS

Confidentialité et consentement de l’utilisateur

Écouter les événements push, utilisateur et in-app

Événements de notification push

Changements d’état de l’utilisateur

Configuration avancée et capacités

Configuration et référence du SDK Web