Passer au contenu principal
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 :
Integrate the OneSignal Android SDK into this codebase.

Follow the instructions at:
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md

​
É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. Saisissez les détails de votre clé serveur Firebase ou compte de service.
  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.2.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.6.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 le tableau de bord OneSignal > 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 :
implementation("com.onesignal:OneSignal:[5.6.1, 5.6.99]")
  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)
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. 
// FILE: ApplicationClass.kt
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml

package com.your.package.name // Replace with your actual package name

import android.app.Application
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

import com.onesignal.OneSignal
import com.onesignal.debug.LogLevel

class ApplicationClass : Application() {
    override fun onCreate() {
        super.onCreate()

        // Enable verbose logging to debug issues (remove in production)
        OneSignal.Debug.logLevel = LogLevel.VERBOSE

        // Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
        OneSignal.initWithContext(this, "YOUR_APP_ID")

        // Prompt user for push notification permission
        // In production, consider using an in-app message instead for better opt-in rates
        CoroutineScope(Dispatchers.IO).launch {
            OneSignal.Notifications.requestPermission(false)
        }
    }
}
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
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
        android:name=".ApplicationClass"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        ...
      </application>

  </manifest>
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é)

Personnalisez les icônes de notification pour correspondre à l’identité visuelle de votre application. Cette étape est facultative mais recommandée pour une apparence professionnelle.

​
É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 le tableau de bord > 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”
Exemple des invites de permission push iOS et 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'.
Vous avez créé avec succès un abonnement mobile. Les abonnements mobiles sont créés lorsque les utilisateurs ouvrent votre application pour la première fois sur un appareil ou s’ils désinstallent et réinstallent votre application sur le même appareil.

​
Créer un abonnement de test et un segment

  1. Cliquez sur ⋮ à côté de l’abonnement > Add to Test Subscriptions > nommez-le
  2. Allez dans Audience > Segments > New Segment
  3. Nom : Test Users, ajoutez le filtre Test Users > Create Segment
Ajouter un abonnement de test.
Créer un segment 'Test Users' avec le filtre Test Users.
Vous avez créé avec succès un segment d’utilisateurs de test.Vous pouvez maintenant tester l’envoi de messages à cet appareil individuel et à des groupes d’utilisateurs de test.

​
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.
curl -X POST 'https://api.onesignal.com/notifications' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Key YOUR_APP_API_KEY' \
  -d '{
    "app_id": "YOUR_APP_ID",
    "target_channel": "push",
    "name": "Testing basic setup",
    "headings": { "en": "👋" },
    "contents": {"en": "Hello world!"},
    "included_segments": ["Test Users"],
    "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  }'
Les images dans les notifications push apparaissent en petit dans la vue réduite. Développez la notification pour voir l'image complète.
Statistiques de livraison montrant la livraison confirmée (indisponible sur les forfaits gratuits).
Vérifiez que l’appareil de test a reçu une notification avec :
  • Votre icône personnalisée (si configurée)
  • Une grande image une fois développée
  • Le tableau de bord > Delivery > Sent Messages affiche le statut “Confirmed” (indisponible sur les forfaits gratuits).
  • 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 onesignal_small_icon_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.
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.
Vérifiez que l’appareil de test a reçu un message in-app. Consultez le guide Configuration des messages in-app pour plus de détails.
Vous ne voyez pas le message ?
  • Démarrez une nouvelle session
    • Vous devez fermer ou mettre en arrière-plan l’application pendant au moins 30 secondes avant de la rouvrir. Cela garantit qu’une nouvelle session est démarrée.
    • 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 abonnements 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 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

Erreur / SymptômeCauseSolution
Cannot resolve symbol 'OneSignal'Dépendance du SDK non ajoutée ou Gradle non synchroniséAjoutez la dépendance au build.gradle et synchronisez le projet
Application class not foundClasse Application non enregistrée dans le manifesteAjoutez android:name=".ApplicationClass" à la balise <application>
Google Play Services not availableÉmulateur/appareil sans Play ServicesUtilisez un appareil avec le Play Store ou un émulateur avec les API Google
Push reçu mais icône Android par défautIcône personnalisée non configurée ou mauvais nomCréez un asset d’icône de notification nommé onesignal_small_icon_default
Aucune notification push reçueFCM non configuré dans OneSignalComplétez l’Étape 0 : Configurez les identifiants FCM dans le tableau de bord OneSignal
Messages in-app non affichésSession non démarrée ou problèmes réseauFermez l’application pendant plus de 30 secondes, rouvrez-la, vérifiez la connexion internet
Manifest merger failedAttributs de manifeste en conflitVérifiez les noms d’application ou conflits de permissions en double
Optimisation de la batterie bloquant les notificationsGestion de l’énergie de l’appareilGuidez les utilisateurs pour désactiver l’optimisation de la batterie pour votre application
Impossible de diagnostiquer le problèmePas assez d’informations dans les journauxAjoutez la journalisation verbose et vérifiez la sortie logcat pour les erreurs

​
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. Consultez notre référence du SDK mobile pour plus de détails et des exemples de code Java.
Kotlin
// Call when user logs in or is identified, safe to call multiple times
// Typically used in a login completion handler, or on app launch if already authenticated
fun onUserAuthenticated(userId: String) {
    OneSignal.login(userId)
}

// If you want to remove the External ID from the Subscription, setting it to an anonymous user
fun onUserLoggedOut() {
    OneSignal.logout()
}
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 le guide de référence du SDK.

​
Ajouter des tags et des événements personnalisés

Les tags et les événements personnalisés sont deux moyens d’ajouter des données à vos utilisateurs. Les tags sont des chaînes clé-valeur et sont généralement associés aux propriétés de l’utilisateur (comme username, role ou status), tandis que les événements personnalisés ont un format JSON et sont habituellement associés à des actions (comme new_purchase, abandoned_cart et les propriétés associées). Les deux peuvent être utilisés pour alimenter la personnalisation avancée des messages et les Journeys. Consultez notre référence du SDK mobile pour plus de détails et des exemples de code Java.
Kotlin
// Add a tag when the user's name is set
OneSignal.User.addTag("username", "john_doe")

// Create a custom event when user abandoned a cart
val properties = mapOf(
    "product_id" to "123456",
    "product_name" to "Product Name",
    "product_price" to 100,
    "product_quantity" to 1
)
OneSignal.User.trackEvent("abandoned_cart", properties)
Plus de détails sur l’utilisation des tags et des événements personnalisés dans les guides Tags et Événements personnalisés.

​
Ajouter des abonnements e-mail et/ou SMS

Vous pouvez contacter les utilisateurs via les canaux e-mail et SMS en plus des notifications push. Si l’adresse e-mail et/ou le numéro de téléphone existent déjà dans l’application OneSignal, le SDK les ajoutera à l’utilisateur existant — il ne créera pas de doublons. Consultez notre référence du SDK mobile pour plus de détails et des exemples de code Java.
Kotlin
// Add email subscription
// Call when user provides their email (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addEmail("user@example.com")

// Add SMS subscription
// Use E.164 format: + country code + number
// Call when user provides their phone number (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addSms("+15551234567")
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. Consultez notre référence du SDK mobile pour plus de détails et des exemples de code Java.
Kotlin
// In ApplicationClass onCreate(), BEFORE OneSignal.initWithContext()
// Use this if your app requires GDPR or other privacy consent before data collection
OneSignal.consentRequired = true

// Later, after user grants consent (e.g., taps "I Agree" on your consent screen)
OneSignal.consentGiven = true
Consultez notre documentation Confidentialité et sécurité pour en savoir plus sur :

​
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

Kotlin
// Add click listener to handle when users tap notifications
val clickListener = object : INotificationClickListener {
  override fun onClick(event: INotificationClickEvent) {
    Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
  }
}
OneSignal.Notifications.addClickListener(clickListener)

​
Changements d’état utilisateur

L’exemple montre comment utiliser l’observateur d’abonnement push. D’autres événements d’état utilisateur comme l’observateur d’état utilisateur et l’observateur de permission de notification sont disponibles dans la référence du SDK mobile.
Kotlin
// Add subscription observer to track push subscription changes
class MyObserver : IPushSubscriptionObserver {
  init {
    OneSignal.User.pushSubscription.addObserver(this)
  }

  override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) {
    if (state.current.optedIn) {
      println("User is now opted-in with push token: ${state.current.token}")
    }
  }
}

​
É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.
Kotlin
// Add click listener for in-app message interactions
val clickListener = object : IInAppMessageClickListener {
  override fun onClick(event: IInAppMessageClickEvent) {
    print(event.result.actionId)
  }
}
OneSignal.InAppMessages.addClickListener(clickListener)

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