Comment prendre en charge l'envoi direct via des tokens FCM/APNs

Scénarios concernés

Cet article vous concerne si votre application répond aux critères suivants :

• L'application est déjà connectée directement à Google FCM et à iOS APNs, détient ses propres tokens FCM et APNs et envoie des notifications de manière autonome via les protocoles natifs ;
• Les versions historiques de l'application n'ont pas intégré le SDK EngageLab AppPush : un grand nombre d'utilisateurs existants ne disposent d'aucun registration_id EngageLab et ne peuvent pas être atteints via l'API de création d'envoi ;
• Vous souhaitez d'abord intégrer ces utilisateurs existants au système d'envoi EngageLab sans imposer de mise à jour de l'application, puis migrer progressivement vers le SDK.

Vue d'ensemble de la solution

Pour ce scénario, EngageLab propose l'API d'enregistrement des appareils : votre serveur soumet directement les tokens FCM ou les device tokens APNs qu'il détient déjà, et EngageLab génère pour chacun un registration_id associé de manière unique. Vous pouvez ensuite envoyer des messages par registration_id via l'API de création d'envoi, exactement comme pour les utilisateurs enregistrés par le SDK, et utiliser les fonctionnalités basées sur le registration_id telles que les tags, les alias et les statistiques.

flowchart LR
    token["Tokens FCM / APNs<br/>que vous détenez déjà"]
    register["API d'enregistrement des appareils<br/>/v4/devices/token/registration_id"]
    regId["registration_id"]
    push["API de création d'envoi<br/>/v4/push"]
    device["L'appareil de l'utilisateur<br/>reçoit la notification"]

    token --> register --> regId --> push --> device

Étapes d'intégration :

1. Votre serveur appelle l'API d'enregistrement des appareils pour soumettre les tokens par lots et par plateforme (1 à 500 par requête), puis conserve la correspondance entre le registration_id renvoyé et chaque token ;
2. Lors de l'envoi, renseignez le registration_id des utilisateurs cibles dans to.registration_id de l'API de création d'envoi ;
3. Lorsqu'un token change (onNewToken de FCM, réenregistrement APNs), appelez de nouveau l'API d'enregistrement des appareils pour obtenir le nouveau registration_id.

Une question fréquente après l'intégration : lorsque l'utilisateur appuie sur la notification sur son téléphone, l'application ouvre-t-elle la page d'accueil ou peut-elle accéder directement à une page cible telle que le détail d'une commande ? La suite prend FCM sur Android comme exemple.

Navigation au clic sur la notification : conclusion

L'ouverture d'une page cible est possible, mais elle n'est pas disponible automatiquement du seul fait de l'enregistrement d'un registration_id.

• Par défaut, appuyer sur la notification ne fait qu'ouvrir l'application ;
• La page précise affichée dépend de la logique de gestion des clics propre à votre application ;
• Pour ouvrir une page cible, le serveur doit préciser intent.url dans la requête d'envoi et votre application doit fournir une Activity capable de répondre à cette action.

L'API d'enregistrement des appareils se limite à établir la correspondance entre le token FCM et le registration_id ; elle n'ajoute aucune capacité de navigation à votre application, et ces utilisateurs ne passent pas par la logique de redirection des clics sur notification qui dépend du SDK EngageLab. Il s'agit donc d'une solution transitoire ; à long terme, nous recommandons toujours de migrer vers le SDK EngageLab AppPush, comme détaillé dans la section « Recommandation à long terme » en fin d'article.

Comportement par défaut : aucune action de clic configurée

Lorsque la requête d'envoi ne configure pas notification.android.intent, la notification transmise par EngageLab à FCM ne contient pas de click_action. Le comportement au clic suit alors entièrement le comportement par défaut de FCM :

• Si l'application est en arrière-plan ou a été fermée, FCM affiche automatiquement la notification et un appui ouvre l'Activity de lancement de l'application (celle déclarée comme MAIN/LAUNCHER dans AndroidManifest.xml) ;
• Que l'utilisateur final voie la page d'accueil, la page de connexion ou la page sur laquelle il se trouvait auparavant dépend de la logique de démarrage de votre application et de l'état actuel de la pile de tâches.

Ainsi, « ouvrir l'application par défaut » ne signifie pas « revenir systématiquement à la page d'accueil ». Consultez la documentation officielle Firebase : Recevoir des messages dans une application Android.

Ouvrir une page cible : intent.url → click_action

Chaîne de correspondance

Le serveur EngageLab associe la valeur de notification.android.intent.url de l'API de création d'envoi au champ android.notification.click_action de la notification FCM ; le système Android recherche ensuite dans votre application une Activity correspondant à cette action.

flowchart LR
    pushApi["API de création d'envoi<br/>notification.android.intent.url"]
    fcm["Message FCM<br/>android.notification.click_action"]
    activity["Votre application<br/>Activity correspondant à l'action"]
    target["Page métier cible<br/>(ex. : détail de commande)"]

    pushApi --> fcm --> activity --> target

La définition officielle de click_action se trouve dans FCM AndroidNotification.

Étape 1 : le serveur précise intent.url dans la requête d'envoi

Lors d'un envoi par registration_id, ajoutez intent.url dans notification.android et transmettez les paramètres métier via extras :

              
              curl -X POST https://pushapi-sgp.engagelab.com/v4/push \
  -u "appKey:masterSecret" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "push",
    "to": {
      "registration_id": ["13065ffa4e1a6cc91c3"]
    },
    "body": {
      "platform": "android",
      "notification": {
        "android": {
          "title": "Commande expédiée",
          "alert": "Votre commande 20260911001 a été expédiée. Appuyez pour suivre la livraison",
          "intent": {
            "url": "intent:#Intent;action=com.example.app.ORDER_DETAIL;component=com.example.app/com.example.app.OrderDetailActivity;end"
          },
          "extras": {
            "order_id": "20260911001",
            "page": "order_detail"
          }
        }
      }
    },
    "request_id": "order-shipped-20260911001"
  }'

            

Concernant la valeur de intent.url, notez que :

• Il s'agit du format Intent URI d'Android (intent:#Intent;...;end), et non d'une adresse web quelconque ;
• action est le nom d'action personnalisé de votre application et component correspond à nom du package/nom de classe complet de l'Activity ;
• Dans une même url, vous pouvez renseigner uniquement action ou uniquement component, mais il est recommandé de renseigner les deux afin de cibler précisément l'Activity ;
• Pour les autres types de valeurs (ouvrir la page d'accueil, Deeplink, etc.), consultez la description de intent dans les champs de notification android de l'API de création d'envoi.

Étape 2 : votre application fournit une Activity correspondante

Dans AndroidManifest.xml, déclarez sur l'Activity cible un intent-filter dont l'action correspond à celle de intent.url :

              
              <activity
    android:name=".OrderDetailActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="com.example.app.ORDER_DETAIL" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

            

Une fois la notification affichée par FCM puis cliquée, l'Activity correspondante est lancée avec cette action et les paires clé-valeur des extras de la notification sont placées dans les extras de l'Intent. L'Activity cible lit les paramètres et effectue le routage métier :

              
              class OrderDetailActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val orderId = intent.getStringExtra("order_id")
        if (orderId.isNullOrEmpty()) {
            // En l'absence de paramètre, revenir à la liste des commandes ou à la page d'accueil
            startActivity(Intent(this, MainActivity::class.java))
            finish()
            return
        }
        showOrderDetail(orderId)
    }
}

            

Si votre application dispose déjà d'une page de routage unifiée (par exemple, tous les clics sur notification passent d'abord par PushRouterActivity, qui redirige ensuite vers la page concernée selon les paramètres), vous pouvez faire pointer le component de intent.url vers cette page intermédiaire ; celle-ci lit les extras puis navigue vers la page métier telle que le détail de commande, sans qu'il soit nécessaire de déclarer une action pour chaque page.

Points d'attention

• Faut-il intégrer le SDK EngageLab ? Non. La chaîne ci-dessus ne dépend que du mécanisme click_action de FCM et des déclarations d'Activity de votre propre application.
• La gestion existante de click_action est réutilisable : si votre application avait déjà implémenté la logique click_action lorsqu'elle utilisait FCM directement, il suffit de renseigner la valeur d'action d'origine dans intent.url.
• En l'absence de gestion de click_action, il faut la compléter : si votre application ne repose actuellement que sur le comportement d'ouverture par défaut, ajoutez la déclaration d'Activity et la logique d'analyse des paramètres selon l'« Étape 2 » ; sinon, même si le serveur configure intent.url, le système ne trouvera aucune Activity capable de répondre.
• Les paramètres métier passent par extras : intent.url détermine « quelle page ouvrir » ; le contenu affiché dans la page doit être transmis via extras (par exemple order_id) et analysé par l'Activity cible.
• Comportement lorsque l'application est au premier plan : lorsque l'application est au premier plan, FCM n'affiche pas la notification automatiquement mais appelle onMessageReceived de votre application ; l'affichage de la notification et la navigation au clic relèvent alors entièrement de votre application.
• Méthode de vérification : lors des tests d'intégration, utilisez d'abord intent:#Intent;action=android.intent.action.MAIN;end pour confirmer que la chaîne du canal fonctionne, puis remplacez-le par l'action métier pour vérifier la navigation vers la page cible.

Recommandation à long terme : migrez dès que possible vers le SDK EngageLab AppPush

L'API d'enregistrement des appareils est conçue comme une solution de compatibilité transitoire : elle permet d'atteindre les utilisateurs existants des versions historiques de l'application sans intégrer le SDK et génère un registration_id associé, en préparation de l'accès ultérieur aux autres fonctionnalités d'EngageLab AppPush. Elle résout la question « peut-on délivrer le message ? », mais ne remplace pas le SDK.

Nous vous recommandons de la considérer comme une composante de votre stratégie de migration, et non comme une solution à long terme :

• Les nouvelles versions de l'application intègrent le SDK EngageLab AppPush : les nouveaux utilisateurs obtiennent leur registration_id via l'enregistrement standard du SDK et bénéficient directement de toutes les capacités d'affichage des notifications et de gestion des clics.
• Les anciennes versions assurent la transition avec les tokens directs : les utilisateurs existants continuent de recevoir les envois via le registration_id enregistré par l'API d'enregistrement des appareils ; les deux systèmes peuvent coexister sans fusion forcée.
• Convergence progressive au fil des mises à jour : à mesure que les utilisateurs passent aux versions intégrant le SDK, le nombre d'utilisateurs en token direct diminue naturellement et tout finit par converger vers le système du SDK.

Par rapport à la méthode directe décrite dans cet article, une fois le SDK intégré :

• La navigation au clic sur la notification est gérée de manière unifiée par le SDK ; les trois types pris en charge par intent.url (Activity donnée, page d'accueil de l'application, Deeplink) ne nécessitent pas de déclarer les actions et la logique d'analyse une à une côté application ;
• L'affichage des notifications au premier plan, les styles de la barre de notification (builder_id, style, channel_id, etc.), les badges, le regroupement des messages et les autres champs prennent pleinement effet ;
• Le SDK remonte automatiquement les informations sur l'appareil et les comportements tels que les clics, ce qui rend les statistiques de livraison et de clics de la console plus complètes.

Pour l'intégration, consultez le Guide d'intégration du SDK Android et le Guide d'intégration du SDK iOS.