Configuration du SDK Flutter

​

Aperçu

​

Exigences

• Flutter 3.29.0+
• Application et plateforme OneSignal configurées

• macOS avec Xcode 14+ (les instructions de configuration utilisent Xcode 16.2)
• Appareil avec iOS 12+, iPadOS 12+ ou simulateur Xcode exécutant iOS 16.2+
• CocoaPods 1.16.2+

• Appareil ou émulateur Android 7.0+ avec Google Play Store (Services) installé

​

Configurer votre application OneSignal et votre plateforme

Instructions étape par étape pour configurer votre application OneSignal.

Vous pouvez gérer plusieurs plateformes (iOS, Android, Huawei, Amazon, Web) sous une seule application OneSignal.

1

Créer ou sélectionner votre application

• Pour ajouter des plateformes à une application existante, allez dans Settings > Push & In-App dans le tableau de bord OneSignal.
• Pour repartir de zéro, cliquez sur New App/Website et suivez les instructions.

L'exemple montre la création d'une nouvelle application.

2

Configurer et activer une plateforme

• Choisissez un nom clair et reconnaissable pour votre application et votre organisation.
• Sélectionnez la ou les plateformes que vous souhaitez configurer (iOS, Android, etc.).
• Cliquez sur Next: Configure Your Platform.

Exemple de configuration de votre première application, organisation et canal OneSignal.

3

Configurer les identifiants de plateforme

Suivez les instructions en fonction de vos plateformes :

• Android : Configurer les identifiants Firebase
• iOS : Jeton p8 (Recommandé) ou Certificat p12
• Amazon : Générer une clé API
• Huawei : Autoriser OneSignal

Cliquez sur Save & Continue après avoir saisi vos identifiants.

4

Choisir le SDK cible

Sélectionnez le SDK qui correspond à votre plateforme de développement (par exemple, iOS, Android, React Native, Unity), puis cliquez sur Save & Continue.

Sélectionnez le SDK que vous utilisez pour accéder à la documentation.

5

Installer le SDK et enregistrer votre App ID

Une fois votre plateforme configurée, votre OneSignal App ID sera affiché. Copiez et enregistrez cet ID—vous en aurez besoin lors de l’installation et de l’initialisation du SDK.Si vous collaborez avec d’autres personnes, utilisez le bouton Invite pour ajouter des développeurs ou des membres de l’équipe, puis cliquez sur Done pour terminer la configuration.

Enregistrez votre App ID et invitez des membres d'équipe supplémentaires.

Une fois terminé, suivez le guide d’installation du SDK pour votre plateforme sélectionnée afin de terminer l’intégration de OneSignal.

​

Configuration du SDK

​

1. Ajouter le SDK

  dependencies:
  	onesignal_flutter: ^5.1.2

​

2. Initialiser le SDK

// Inclure le package OneSignal
import 'package:onesignal_flutter/onesignal_flutter.dart';

void main() {
  runApp(const MyApp());

  // Activer la journalisation détaillée pour le débogage (à retirer en production)
  OneSignal.Debug.setLogLevel(OSLogLevel.verbose);
  // Initialiser avec votre ID d'application OneSignal
  OneSignal.initialize("YOUR_APP_ID");
  // Utilisez cette méthode pour demander les notifications push.
  // Nous recommandons de retirer cette méthode après les tests et d'utiliser plutôt les messages in-app pour demander la permission de notification.
  OneSignal.Notifications.requestPermission(false);

}

​

Configuration Android

​

Configuration iOS

​

1. Ajouter la capacité Push Notifications à la cible de l’application

1. Ouvrez le fichier .xcworkspace de votre application dans Xcode.
2. Sélectionnez votre cible d’application > Signing & Capabilities
3. Cliquez sur + Capability et ajoutez la capacité Push Notifications

La cible de l'application reçoit la capacité Push Notifications.

​

2. Ajouter la capacité Background Modes à la cible de l’application

1. Ajoutez la capacité Background Modes
2. Activez Remote notifications

La cible de l'application reçoit le mode d'exécution en arrière-plan Remote Notifications.

​

3. Ajouter la cible de l’application à un App Group

• Si vous n'avez PAS d'App Group configuré
• Si vous avez déjà un App Group

1. Ajoutez la capacité App Groups
2. Dans la capacité App Groups, cliquez sur +
3. Ajoutez un nouvel ID de conteneur au format : group.your_bundle_id.onesignal

• Conservez le préfixe group. et le suffixe .onesignal. Remplacez your_bundle_id par l’identifiant de bundle de votre application.
• Par exemple, l’identifiant de bundle com.onesignal.MyApp aura le nom de conteneur group.com.onesignal.MyApp.onesignal.

La cible de l'application fait partie de l'App Group.

Le nom de votre App Group doit correspondre exactement à l’orthographe et à la casse de votre ID de bundle sur toutes les cibles.

​

4. Ajouter le Notification Service Extension

1. Dans Xcode : File > New > Target…
2. Sélectionnez Notification Service Extension, puis Next.
3. Définissez le nom du produit sur OneSignalNotificationServiceExtension et appuyez sur Finish.
4. Appuyez sur Don’t Activate sur l’invite Activate scheme.

Sélectionnez la cible Notification Service Extension.

Nommez le Notification Service Extension.

Annulez l'activation pour continuer le débogage de la cible de votre application.

Définissez la même cible de déploiement que l'application principale.

​

5. Ajouter la cible NSE à l’app group

1. Allez dans OneSignalNotificationServiceExtension > Signing & Capabilities
2. Ajoutez App Groups
3. Ajoutez exactement le même ID de groupe

Le NSE appartient maintenant au même app group que votre cible d'application.

​

6. Mettre à jour le code NSE

1. Naviguez vers le dossier OneSignalNotificationServiceExtension
2. Remplacez le contenu du fichier NotificationService.swift ou NotificationService.m par ce qui suit :

Naviguez vers votre fichier NotificationService.

import UserNotifications
import OneSignalExtension

class NotificationService: UNNotificationServiceExtension {
    var contentHandler: ((UNNotificationContent) -> Void)?
    var receivedRequest: UNNotificationRequest!
    var bestAttemptContent: UNMutableNotificationContent?

    // Note this extension only runs when `mutable_content` is set
    // Setting an attachment or action buttons automatically sets the property to true
    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.receivedRequest = request
        self.contentHandler = contentHandler
        self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

        if let bestAttemptContent = bestAttemptContent {
            // DEBUGGING: Uncomment the 2 lines below to check this extension is executing
//            print("Running NotificationServiceExtension")
//            bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

            OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
            contentHandler(bestAttemptContent)
        }
    }
}

Ce fichier affiche une erreur jusqu'à ce que vous installiez le package à l'étape suivante.

​

7. Ajouter OneSignal à la cible NSE

target 'OneSignalNotificationServiceExtension' do
  pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
end

cd ios pod install cd ..

​

Erreurs courantes de pod install

​

Compiler pour iOS

​

Erreurs courantes de compilation iOS

Cycle Inside... building could produce unreliable results.

Vous pourriez voir cette erreur lors de la compilation avec Xcode 15+, en raison d’un changement de configuration par défaut affectant les systèmes multiplateformes.

1. Ouvrez votre dossier .xcworkspace dans Xcode et naviguez vers votre cible d’application > Build Phases.
2. Vous devriez avoir une phase appelée “Embed Foundation Extensions” ou “Embed App Extensions”.
3. Faites glisser et déplacez cette phase de compilation au-dessus de “Run Script”.
4. Compilez et exécutez votre application. L’erreur devrait être résolue.

Ordre correct des Build Phases dans Xcode.

Décochez Copy only when installing.

Erreur PBXGroup

RuntimeError - PBXGroup a tenté d’initialiser un objet avec un ISA inconnu PBXFileSystemSynchronizedRootGroup à partir des attributs : {"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}

Correction :

1. Trouvez le dossier listé sous “path” dans l’erreur
2. Dans la barre latérale du projet Xcode, faites un clic droit sur le dossier
3. Sélectionnez Convert to Group

Erreur de chemin pour PBXGroup.

Convertir le dossier en groupe.

​

Tester l’intégration du SDK OneSignal

​

Vérifier les abonnements mobiles

1

Lancez votre application sur un appareil de test.

L’invite d’autorisation push native devrait apparaître automatiquement si vous avez ajouté la méthode requestPermission lors de l’initialisation.

Invites d'autorisation push iOS et Android

2

Vérifiez votre tableau de bord OneSignal

Avant d’accepter l’invite, vérifiez le tableau de bord OneSignal :

• Allez dans Audience > Subscriptions.
• Vous devriez voir une nouvelle entrée avec le statut “Never Subscribed”.

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

3

Retournez à l'application et appuyez sur Autoriser dans l'invite.

4

Actualisez la page Subscription du tableau de bord OneSignal.

Le statut de l’abonnement devrait maintenant afficher Subscribed.

Tableau de bord affichant un abonnement avec le statut '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.

​

Configurer les abonnements de test

1

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

Ajout d'un appareil aux abonnements de test

2

Nommez votre abonnement.

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

Tableau de bord affichant le champ 'Name your subscription'

3

Créer un segment d'utilisateurs de test.

Allez dans Audience > Segments > New Segment.

4

Nommez le segment.

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

5

Ajoutez le filtre Test Users et cliquez sur Create Segment.

Création d'un segment 'Test Users' avec le filtre 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

1

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

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

2

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.

Copy

Ask AI

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"
  ],
  "ios_attachments": {
    "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  },
  "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'

3

Exécutez le code.

Exécutez le code dans votre terminal.

4

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 avec une image incluse :

Notification push avec image sur iOS et Android

Les images apparaîtront petites dans la vue de notification réduite. Développez la notification pour voir l’image complète.

5

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.

Statistiques de livraison affichant la livraison confirmée

Si vous avez un forfait Professional ou supérieur, faites défiler jusqu’à Audience Activity pour voir la confirmation au niveau de l’abonnement :

Livraison confirmée au niveau de l'appareil dans Audience Activity

Vous avez envoyé avec succès une notification via notre API à un segment.

• Aucune image reçue ? Votre Notification Service Extension est peut-être manquant.
• Aucune livraison confirmée ? Consultez le guide de dépannage ici.
• Vous rencontrez 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.

​

Envoyer un message in-app

1

Fermez ou mettez votre application en arrière-plan sur l'appareil.

C’est parce que les utilisateurs doivent répondre aux critères d’audience in-app avant qu’une nouvelle session ne commence. Dans OneSignal, une nouvelle session commence lorsque l’utilisateur ouvre votre application après qu’elle ait été en arrière-plan ou fermée pendant au moins 30 secondes. Pour plus de détails, consultez notre guide sur comment les messages in-app sont affichés.

2

Créer un message in-app.

• Dans votre tableau de bord OneSignal, naviguez vers Messages > In-App > New In-App.
• Trouvez et sélectionnez le message Welcome.
• Définissez votre Audience comme le segment Test Users que nous avons utilisé précédemment.

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

3

Personnalisez le contenu du message si désiré.

Exemple de personnalisation du message de bienvenue in-app

4

Définir le déclencheur sur 'On app open'.

5

Planifier la fréquence.

Sous Schedule > How often do you want to show this message? sélectionnez Every time trigger conditions are satisfied.

Options de planification du message in-app

6

Rendre le message actif.

Cliquez sur Make Message Live pour qu’il soit disponible pour vos utilisateurs de test chaque fois qu’ils ouvrent l’application.

7

Ouvrez l'application et voyez le message.

Après que le message in-app soit actif, ouvrez votre application. Vous devriez le voir s’afficher :

Message de bienvenue in-app affiché sur les appareils

Vous ne voyez pas le message ?

• Démarrez une nouvelle session
  • Vous devez fermer ou mettre l’application en arrière-plan pendant au moins 30 secondes avant de la rouvrir. Cela garantit qu’une nouvelle session est démarrée.
  • Pour plus d’informations, voir comment les messages in-app sont affichés.
• Toujours dans le segment Test Users ?
  • Si vous avez réinstallé ou changé d’appareil, réajoutez l’appareil aux abonnements de test et confirmez qu’il fait partie du segment Test Users.
• Vous rencontrez des problèmes ?
  • Suivez Obtenir un journal de débogage tout 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 à enquêter sur ce qui se passe.

​

Identification des utilisateurs

​

Attribuer un External ID

​

Ajouter des tags de données

Un profil utilisateur dans OneSignal avec un tag appelé "current_level" défini sur "6"

Éditeur de segment montrant un segment ciblant les utilisateurs avec une valeur current_level supérieure à 4 et inférieure à 10

Capture d'écran montrant une notification push ciblant le segment Niveau 5-10 avec un message personnalisé

La notification push est reçue sur un appareil iOS et Android avec le contenu personnalisé

​

Ajouter des abonnements email et/ou SMS

• Utilisez la méthode addEmail pour créer des abonnements email.
• Utilisez la méthode addSms pour créer des abonnements SMS.

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

​

Confidentialité et consentement de l’utilisateur

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

• Données collectées par le SDK
• Gestion des données personnelles

​

Demander les autorisations push

​

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

​

Événements de notification push

• addClickListener() : Détecter quand une notification est tapée. Utile pour les Deep Linking.
• addForegroundLifecycleListener() : Contrôler comment les notifications se comportent au premier plan.

​

Changements d’état de l’utilisateur

• addObserver() pour l’état utilisateur : Détecter quand l’External ID est défini.
• addPermissionObserver() : Suivre l’interaction spécifique de l’utilisateur avec l’invite d’autorisation push native.
• addObserver() pour l’abonnement push : Suivre quand le statut de l’abonnement push change.

​

Événements de message in-app

• addClickListener() : Gérer les actions de clic in-app. Idéal pour le deep linking ou le suivi des événements.
• addLifecycleListener() : Suivre le cycle de vie complet des messages in-app (affiché, cliqué, rejeté, etc.).

​

Configuration avancée et capacités

• 🔁 Migrer vers OneSignal depuis un autre service
• 🌍 Suivi de localisation
• 🔗 Deep Linking
• 🔌 Intégrations
• 🧩 Extensions de service mobile
• 🛎️ Boutons d’action
• 🌐 Messagerie multilingue
• 🛡️ Vérification d’identité
• 📊 Résultats personnalisés
• 📲 Live Activities

​

Configuration et référence du SDK mobile