Skip to main content
Ce guide vous accompagne dans l’ajout de OneSignal à votre application Android avec Android Studio. Vous installerez notre SDK, configurerez les notifications push et les messages in-app, et enverrez des messages de test pour confirmer que tout fonctionne correctement. Si c’est la première fois que vous utilisez OneSignal, suivez les étapes dans l’ordre. Si vous êtes expérimenté, n’hésitez pas à accéder directement aux sections dont vous avez besoin.
Vous utilisez un assistant de codage IA ? Pour une installation pilotée par l’IA, utilisez ce prompt :

É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.
Si votre entreprise possède déjà un compte OneSignal, demandez à être invité en tant qu’administrateur pour configurer l’application. Sinon, créez un compte gratuit pour commencer.
Ces étapes connectent votre application OneSignal à Firebase Cloud Messaging (FCM). Vous n’avez besoin de le faire qu’une seule fois par application.
  1. Connectez-vous à https://onesignal.com et créez ou sélectionnez votre application.
  2. Accédez à Settings > Push & In-App.
  3. Sélectionnez Google Android (FCM) et cliquez sur Continue pour parcourir l’assistant de configuration.
  4. Téléversez votre JSON de compte de service FCM.
  5. Continuez l’assistant de configuration pour obtenir votre App ID. Celui-ci sera utilisé pour initialiser le SDK.
Pour les instructions complètes de configuration, consultez notre guide Configuration push mobile.

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
Si vous avez ignoré l’Étape 0 (Configuration de FCM dans OneSignal), vous pouvez tout de même terminer la configuration Android Studio ci-dessous. Complétez l’Étape 0 avant de tester ou d’envoyer des notifications push.

Étape 1. Ajouter le SDK OneSignal

  1. Dans Android Studio, ouvrez votre fichier build.gradle.kts (Module: app) ou build.gradle (Module: app)
  2. Ajoutez OneSignal à votre section dependencies :
build.gradle.kts de l'application dans Android Studio avec la dépendance implementation OneSignal ajoutée

Exemple montrant l'ajout de OneSignal au fichier build.gradle.kts de votre application.

  1. Synchroniser Gradle : Cliquez sur Sync Now dans la bannière qui apparaît ou allez dans File > Sync Project with Gradle Files
Vérifiez que la synchronisation Gradle se termine avec succès sans conflits de dépendances.

Étape 2. Créer et configurer la classe Application

La bonne pratique est d’initialiser OneSignal dans la méthode onCreate 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 :
  1. File > New > Kotlin Class/File (ou Java Class)
  2. Nom : ApplicationClass (ou le nom de votre choix)
Boîte de dialogue New Kotlin Class d'Android Studio avec ApplicationClass comme nom

Exemple montrant la création d'une nouvelle classe Kotlin nommée ApplicationClass.

Ajoutez le code OneSignal suivant à la classe Application. Remplacez YOUR_APP_ID par votre App ID OneSignal réel depuis le tableau de bord > Settings > Keys & IDs.
ApplicationClass.kt dans Android Studio montrant OneSignal initWithContext et requestPermission

Exemple de fichier ApplicationClass.kt.

L’initialisation dans une Activity (comme MainActivity) n’est pas recommandée car elle peut ne pas être appelée lors des démarrages à froid de l’application depuis des liens profonds ou des notifications. Initialisez toujours OneSignal dans votre classe Application pour plus de fiabilité.
Enregistrer la classe Application :
  1. Ouvrez le fichier AndroidManifest.xml de votre application
  2. Dans votre balise <application>, ajoutez android:name=".ApplicationClass" (remplacez .ApplicationClass par le nom réel de votre classe si vous l’avez défini différemment).
AndroidManifest.xml
Vérifiez si votre balise <application> contient tools:node="replace". Ce marqueur supprime les composants fusionnés des bibliothèques, y compris PermissionsActivity de OneSignal. Le flux de permission de notification plante alors avec ActivityNotFoundException. Retirez tools:node="replace". Si vous devez uniquement remplacer un seul attribut, utilisez tools:replace="android:theme" (ou l’attribut que vous modifiez).
Balise application de l'AndroidManifest.xml avec android:name défini sur .ApplicationClass

AndroidManifest.xml avec le nom .ApplicationClass.

Vérifiez que l’application se compile et s’exécute sans erreurs.

É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ée ic_stat_onesignal_default. Utilisez une silhouette monochrome sur fond transparent, sinon Android affichera un carré blanc.
  1. Générez les densités avec Android Asset Studio.
  2. Placez ic_stat_onesignal_default dans chaque dossier de densité : de res/drawable-mdpi/ (24×24) à res/drawable-xxxhdpi/ (96×96).
Consultez Icônes de notification pour les grandes icônes, la couleur d’accentuation et le comportement de l’icône de lanceur d’Android 17.

Étape 4. Tester l’intégration

Vérifier la création de l’abonnement :
  1. Lancez l’application sur un appareil ou un émulateur avec Google Play Services.
  2. Vérifiez dans Dashboard > Audience > Subscriptions. Le statut affiche Never Subscribed.
  3. Acceptez la demande de permission lorsqu’elle apparaît.
  4. Actualisez le tableau de bord. Le statut passe à Subscribed.
Invite de permission push Android demandant l'autorisation d'afficher des notifications

Invite de permission push Android

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

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

Après avoir autorisé les permissions push, actualisez le tableau de bord pour voir le statut de l'abonnement passer à 'Subscribed'

Un abonnement mobile est créé lorsque l’utilisateur ouvre votre application pour la première fois sur un appareil, ou s’il la désinstalle puis la réinstalle sur le même appareil. Après qu’il a accepté la demande de permission, le statut dans le tableau de bord doit afficher Subscribed.

Créer un utilisateur de test et un segment

  1. À côté de l’abonnement, sélectionnez Options > Add as test user et saisissez un nom.
  2. Allez dans Audience > Segments > New Segment.
  3. Nom : Test Users, ajoutez le filtre Test Users > Create Segment.
Menu Options sur un enregistrement d'abonnement avec Add as test user en surbrillance

Ajouter un utilisateur de test

Créer un segment 'Test Users' avec le filtre Test Users.

Créer un segment 'Test Users' avec le filtre Test Users

Vous pouvez maintenant envoyer des messages de test à cet appareil et au segment Test Users.

Envoyer un push de test via l’API

  1. Accédez à Settings > Keys & IDs.
  2. Dans 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éé précédemment.
Les images dans les notifications push apparaissent en petit dans la vue réduite. Développez la notification pour voir l'image complète.

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

Statistiques de livraison montrant la réception confirmée (indisponible sur les forfaits gratuits)

Confirmez que l’appareil de test a reçu une notification avec votre icône personnalisée (si configurée) et la grande image une fois développée. Sur les forfaits payants, Dashboard > Delivery > Sent Messages peut afficher la réception confirmée.
  • Pas de notification reçue ? Consultez Push mobile non affiché.
  • Pas d’icône personnalisée ? Vérifiez que le nom de l’icône est ic_stat_onesignal_default et qu’elle se trouve dans les bons dossiers drawable.
  • Des problèmes ? Copiez-collez la requête API et un journal du début à la fin du lancement de l’application dans un fichier .txt. Ensuite, partagez les deux avec support@onesignal.com.

Tester les messages in-app

  1. Fermez l’application pendant plus de 30 secondes
  2. Tableau de bord > Messages > In-App > New In-App > sélectionnez le modèle Welcome
  3. Audience : segment Test Users
  4. Déclencheur : On app open
  5. Planification : Every time trigger conditions are satisfied
  6. Cliquez sur Make Message Live
  7. Ouvrez l’application
Ciblage du segment 'Test Users' avec un message in-app.

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

Exemple de personnalisation du message de bienvenue in-app.

Exemple de personnalisation du message de bienvenue in-app

Options de planification des messages in-app.

Options de planification des messages in-app

Message de bienvenue in-app affiché sur les appareils.

Message de bienvenue in-app affiché sur les appareils

L’appareil de test devrait afficher le message de bienvenue in-app. Consultez Configuration des messages in-app pour plus de détails.
Vous ne voyez pas le message ?
  • Démarrez une nouvelle session
    • Forcez la fermeture puis rouvrez l’application, ou fermez-la/mettez-la en arrière-plan pendant au moins 30 secondes avant de la rouvrir. Dans les deux cas, une nouvelle session est démarrée. Consultez Sessions.
    • Pour en savoir plus, consultez comment les messages in-app sont affichés.
  • Toujours dans le segment Test Users ?
    • Si vous avez réinstallé ou changé d’appareil, ajoutez à nouveau l’appareil aux utilisateurs de test et confirmez qu’il fait partie du segment Test Users.
  • Des problèmes ?
    • Suivez le guide Obtenir un journal de débogage en reproduisant les étapes ci-dessus. Cela générera des journaux supplémentaires que vous pourrez partager avec support@onesignal.com et nous vous aiderons à investiguer le problème.
Vous disposez maintenant d’abonnements, d’utilisateurs de test et d’un segment. Vous avez envoyé un push avec une image via l’API Créer un message et un message in-app. Continuez ci-dessous pour identifier les utilisateurs et ajouter plus de fonctionnalités.
Vous avez configuré avec succès le SDK OneSignal et appris des concepts importants comme :Continuez avec ce guide pour identifier les utilisateurs dans votre application et configurer des fonctionnalités supplémentaires.

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.
OneSignal génère des identifiants uniques en lecture seule pour les abonnements (Subscription ID) et les utilisateurs (OneSignal ID).Définir l’External ID via notre SDK est fortement recommandé pour identifier les utilisateurs à travers tous leurs abonnements, quelle que soit la manière dont ils ont été créés.En savoir plus sur la méthode 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înes clé-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.
Consultez Tags et Événements personnalisés pour plus de détails.

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’abord login() 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.

Un profil utilisateur avec des abonnements push, e-mail et SMS unifiés par External ID

Bonnes pratiques pour la communication multicanal
  • 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. Appelez consentRequired avant initWithContext.

Demander les permissions push

Au lieu d’appeler requestPermission() 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ès OneSignal.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

Fonctionnalités universelles

Pour la documentation complète des méthodes du SDK, consultez la référence du SDK mobile.

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. Ajoutez android: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. Ajoutez ic_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éfinissez OneSignal.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.
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 !