Étape 0. Configurer FCM dans OneSignal (requis pour envoyer des push)
Vous pouvez installer et initialiser le SDK Android OneSignal sans avoir terminé cette étape. Cependant, les notifications push ne seront pas envoyées tant que les identifiants Firebase Cloud Messaging (FCM) ne sont pas configurés dans votre application OneSignal.Étapes pour configurer votre application OneSignal.
Étapes pour configurer votre application OneSignal.
- Connectez-vous à https://onesignal.com et créez ou sélectionnez votre application.
- Accédez à Settings > Push & In-App.
- Sélectionnez Google Android (FCM) et cliquez sur Continue pour parcourir l’assistant de configuration.
- Téléversez votre JSON de compte de service FCM.
- Continuez l’assistant de configuration pour obtenir votre App ID. Celui-ci sera utilisé pour initialiser le SDK.
Contrat de configuration et prérequis
Cette section résume les outils, versions et hypothèses utilisés tout au long du guide.- Version du SDK :
5.6.1+(dernière version : consultez les releases) - Instructions de configuration IA :
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md - Dépôt du SDK :
https://github.com/OneSignal/OneSignal-Android-SDK - Android Studio : Meerkat | 2024.3.1+
- API Android : 23+ minimum (Android 6.0+), 31+ recommandé (Android 12+)
- Appareil/Émulateur : Android 7.0+ avec Google Play Services installé
- Dépendance requise :
com.onesignal:OneSignal:[5.6.1, 5.99.99] - Classe Application : Requise pour une initialisation correcte du SDK
- Format de l’App ID : UUID de 36 caractères (exemple :
12345678-1234-1234-1234-123456789012). Disponible dans Dashboard > Settings > Keys & IDs. - Initialisation :
OneSignal.initWithContext(this, "YOUR_APP_ID") - Optimisation de la batterie : Peut affecter les notifications en arrière-plan
- Recommandé : Attribuer un External ID via
OneSignal.login("user_id")pour unifier les utilisateurs sur tous les appareils
Étapes de configuration Android
À la fin des étapes ci-dessous, vous aurez :- Le SDK OneSignal installé et initialisé dans votre application Android
- La demande de permission pour les notifications push fonctionnant correctement sur un appareil réel
- Un push de test et un message in-app envoyés avec succès
Étape 1. Ajouter le SDK OneSignal
- Dans Android Studio, ouvrez votre fichier
build.gradle.kts (Module: app)oubuild.gradle (Module: app) - Ajoutez OneSignal à votre section
dependencies:

Exemple montrant l'ajout de OneSignal au fichier build.gradle.kts de votre application.
- Synchroniser Gradle : Cliquez sur Sync Now dans la bannière qui apparaît ou allez dans File > Sync Project with Gradle Files
Étape 2. Créer et configurer la classe Application
La bonne pratique est d’initialiser OneSignal dans la méthodeonCreate de votre classe Application pour garantir une configuration correcte du SDK sur tous les points d’entrée.
Créez une classe Application si vous n’en avez pas encore :
- File > New > Kotlin Class/File (ou Java Class)
- Nom :
ApplicationClass(ou le nom de votre choix)

Exemple montrant la création d'une nouvelle classe Kotlin nommée ApplicationClass.
YOUR_APP_ID par votre App ID OneSignal réel depuis le tableau de bord > Settings > Keys & IDs.

Exemple de fichier ApplicationClass.kt.
- Ouvrez le fichier
AndroidManifest.xmlde votre application - Dans votre balise
<application>, ajoutezandroid:name=".ApplicationClass"(remplacez.ApplicationClasspar le nom réel de votre classe si vous l’avez défini différemment).

AndroidManifest.xml avec le nom .ApplicationClass.
Étape 3. Configurer les icônes de notification par défaut (recommandé)
Remplacez l’icône de cloche par défaut par une petite icône nomméeic_stat_onesignal_default. Utilisez une silhouette monochrome sur fond transparent, sinon Android affichera un carré blanc.
- Générez les densités avec Android Asset Studio.
- Placez
ic_stat_onesignal_defaultdans chaque dossier de densité : deres/drawable-mdpi/(24×24) àres/drawable-xxxhdpi/(96×96).
Étape 4. Tester l’intégration
Vérifier la création de l’abonnement :- Lancez l’application sur un appareil ou un émulateur avec Google Play Services.
- Vérifiez dans Dashboard > Audience > Subscriptions. Le statut affiche Never Subscribed.
- Acceptez la demande de permission lorsqu’elle apparaît.
- Actualisez le tableau de bord. Le statut passe à Subscribed.

Invite de permission push Android

Tableau de bord affichant un abonnement avec le statut 'Never Subscribed'

Après avoir autorisé les permissions push, actualisez le tableau de bord pour voir le statut de l'abonnement passer à 'Subscribed'
Créer un utilisateur de test et un segment
- À côté de l’abonnement, sélectionnez Options > Add as test user et saisissez un nom.
- Allez dans Audience > Segments > New Segment.
- Nom :
Test Users, ajoutez le filtre Test Users > Create Segment.

Ajouter un utilisateur de test

Créer un segment 'Test Users' avec le filtre Test Users
Envoyer un push de test via l’API
- Accédez à Settings > Keys & IDs.
- Dans le code fourni, remplacez
YOUR_APP_API_KEYetYOUR_APP_IDdans le code ci-dessous par vos clés réelles. Ce code utilise le segmentTest Usersque nous avons créé précédemment.

Les images apparaissent en petit dans la vue réduite de la notification. Développez la notification pour voir l'image complète.

Statistiques de livraison montrant la réception confirmée (indisponible sur les forfaits gratuits)
Tester les messages in-app
- Fermez l’application pendant plus de 30 secondes
- Tableau de bord > Messages > In-App > New In-App > sélectionnez le modèle Welcome
- Audience : segment Test Users
- Déclencheur : On app open
- Planification : Every time trigger conditions are satisfied
- Cliquez sur Make Message Live
- Ouvrez l’application

Ciblage du segment 'Test Users' avec un message in-app

Exemple de personnalisation du message de bienvenue in-app

Options de planification des messages in-app

Message de bienvenue in-app affiché sur les appareils
- La collecte d’abonnements, la configuration d’utilisateurs de test et la création de segments.
- L’envoi de push avec des images en utilisant les segments et notre API Créer un message.
- L’envoi de messages in-app.
Erreurs courantes et solutions
Gestion des utilisateurs
Précédemment, nous avons montré comment créer des abonnements mobiles. Nous allons maintenant passer à l’identification des utilisateurs à travers tous leurs abonnements (y compris push, e-mail et SMS) en utilisant le SDK OneSignal.Attribuer un External ID (recommandé)
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.login dans la référence du SDK.Ajouter des tags et des événements personnalisés
Les tags et les événements personnalisés ajoutent tous deux des données aux utilisateurs. Les tags sont des chaînesclé-valeur pour les propriétés de l’utilisateur (comme username, role ou status). Les événements personnalisés utilisent le format JSON et représentent généralement des actions (comme new_purchase ou abandoned_cart). Les deux peuvent alimenter la personnalisation des messages et les Journeys.
Ajouter des abonnements e-mail et/ou SMS
Vous pouvez contacter les utilisateurs via e-mail et SMS en plus des notifications push. Si l’adresse e-mail ou le numéro de téléphone existe déjà dans l’application OneSignal, le SDK l’ajoute à l’utilisateur existant et ne crée pas de doublons. Appelez d’abordlogin() afin que l’adresse soit rattachée à l’utilisateur identifié.

Un profil utilisateur avec des abonnements push, e-mail et SMS unifiés par External ID
- Obtenez un consentement explicite avant d’ajouter des abonnements e-mail ou SMS.
- Expliquez les avantages de chaque canal de communication aux utilisateurs.
- Fournissez des préférences de canal pour que les utilisateurs puissent sélectionner les canaux qu’ils préfèrent.
Confidentialité et consentement utilisateur
Pour contrôler quand OneSignal collecte les données utilisateur, utilisez les méthodes de contrôle du consentement du SDK. AppelezconsentRequired avant initWithContext.
Demander les permissions push
Au lieu d’appelerrequestPermission() immédiatement à l’ouverture de l’application, adoptez une approche plus stratégique. Utilisez un message in-app pour expliquer la valeur des notifications push avant de demander la permission.
Pour les bonnes pratiques et les détails d’implémentation, consultez notre guide Demander les permissions push.
É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. Ajoutez-les dans votre classe Application aprèsOneSignal.initWithContext().
Événements de notification push
Changements d’état utilisateur
Cet exemple utilise l’observateur d’abonnement push. L’observateur d’état utilisateur et l’observateur de permission de notification sont disponibles dans la référence du SDK mobile.Événements de messages in-app
Des méthodes supplémentaires pour les messages in-app sont disponibles dans la référence du SDK mobile.Configuration avancée et fonctionnalités
Fonctionnalités spécifiques à Android
- Canaux de notification : Organisez les notifications en catégories (Android 8.0+)
- Extensions de service : Personnalisation avancée des notifications
- Huawei/HMS : Alternative à Google Play Services
Fonctionnalités universelles
- Liens profonds : Dirigez les utilisateurs vers des écrans spécifiques depuis les notifications
- Boutons d’action : Ajoutez des boutons interactifs aux notifications
- Vérification d’identité : Identification sécurisée des utilisateurs
- Suivi de localisation : Ciblage basé sur la localisation
- Intégrations : Connectez-vous aux plateformes d’analyse et de données
- Messagerie multilingue : Notifications localisées
FAQ
Pourquoi Android Studio ne peut-il pas résoudre OneSignal ?
La dépendance du SDK est manquante ou Gradle n’a pas été synchronisé. Ajoutez com.onesignal:OneSignal:[5.6.1, 5.99.99] au build.gradle de votre module d’application et utilisez File > Sync Project with Gradle Files.
Pourquoi ma classe Application est-elle introuvable ?
La classe n’est pas enregistrée dans le manifeste. Ajoutezandroid:name=".ApplicationClass" (ou le nom de votre classe) à la balise <application> dans AndroidManifest.xml.
Pourquoi l’émulateur indique-t-il que Google Play Services n’est pas disponible ?
L’image de l’émulateur n’inclut pas les Play Services. Utilisez un appareil avec le Play Store, ou une image système d’émulateur qui inclut les API Google.Pourquoi la notification affiche-t-elle l’icône Android par défaut ?
La petite icône est manquante ou mal nommée. Ajoutezic_stat_onesignal_default dans chaque dossier de densité res/drawable-*. Consultez Icônes de notification.
Pourquoi mon appareil de test n’a-t-il pas reçu de push ?
Les identifiants FCM ne sont pas configurés, ou l’appareil n’est pas abonné. Complétez l’Étape 0 et confirmez que le statut de l’abonnement est Subscribed. Consultez ensuite Push mobile non affiché.Pourquoi les messages in-app ne s’affichent-ils pas ?
Les messages in-app nécessitent une nouvelle session. Forcez la fermeture de l’application, ou mettez-la en arrière-plan pendant au moins 30 secondes, puis rouvrez-la. Confirmez que l’appareil fait toujours partie du segment Test Users. Consultez Sessions et comment les messages in-app sont affichés.Qu’est-ce qui provoque Manifest merger failed ?
Des valeurs android:name de <application> en conflit ou des permissions en double. Recherchez une seconde classe Application dans votre manifeste fusionné et ne conservez qu’un seul android:name.
Pourquoi les optimisations de batterie bloquent-elles les notifications ?
Certains fabricants (OEM) restreignent le travail en arrière-plan. Demandez aux utilisateurs de désactiver l’optimisation de la batterie pour votre application si les notifications s’arrêtent après la mise en veille de l’appareil.Comment obtenir plus de journaux ?
DéfinissezOneSignal.Debug.logLevel = LogLevel.VERBOSE (Kotlin) ou OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE) (Java), reproduisez le problème et capturez la sortie logcat. Consultez Obtenir un journal de débogage.
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