Table des matières
- Le SDK Mobile Engage, c'est quoi ?
- Intégrer avec iOS
- Intégrer avec Android
- Vérifier le SDK
- Foire Aux Questions
- Effectuer la migration de l'API Mobile Engage API au SDK Mobile Engage
Lecture complémentaire
Le SDK Mobile Engage, c'est quoi ?
Le SDK Mobile Engage vous permet d'utiliser très simplement Mobile Engage. En incorporant le SDK dans votre appli, nous vous aidons, entre autres, à gérer les identifiants, les appels API, le traçage des ouvertures et des événements ainsi que les connexions et les déconnexions dans l'appli.
Le SFK Mobile Engage est en open source afin d'augmenter la transparence et d'éviter les soucis de confidentialité. Ceci implique également que vous pouvez toujours être à jour sur ce sur quoi nous travaillons.
Utiliser le SDK est également avantageux pour l'aspect du produit : l'envoi de messages push via votre appli est de ce fait beaucoup plus facile. Vous n'avez pas besoin de suivre et de mettre en place des changements dans nos appels, points d'entrée et paramètres API : Nous le faisons pour vous dans le kit de développement (SDK). Votre seule tâche est d'utiliser la dernière version du SDK dans votre appli, et nous nous occupons de tout le reste.
Intégrer avec iOS
Installation avec CocoaPods
CocoaPods est un gestionnaire de dépendance pour iOS, qui automatise et simplifie le processus d'utilisation de bibliothèques tierces.
Vous pouvez l'installer avec la commande suivante :
$ gem install cocoapods
1. Podfile
Pour intégrer le SDK Mobile ENfage sur cotre projet Xcode avec CocoaPods, spécifiez-le dans votre Podfile:
Lorsque vous voyez <NomCible> ou quelque chose de semblable entre <> crochets, vous devez les changer en fonction de votre convention de nommage personnalisée.
2. Installer Pods
Après avoir créé le Podfile, il vous faut exécuter la commande ci-dessous pour en télécharger les dépendances :
pod install
3. Obligations
La cible iOS doit être iOS 9 ou plus récent.
4. Utilisation
4.1. Initialisation
Pour configurer le SDK, voici ce qui doit être fait dans l'AppDelegate de l'application:
LepushToken doit être configuré lorsqu'il arrive:
Si vous souhaitez recevoir le journal des erreurs, vous devez paramétrer MobileEngage.statusDelegate:
Chaque appel renvoie un eventId, qui peut être utilisé avec le statusDelegate pour tracer nos appels. LestatusDelegate définit deux méthodes:
4.2. Connexion
Lorsque l'installation de l'application est terminée, l'appLogin doit être appelée. Si l'utilisateur n'est plus connecté, il peut être utilisé sans paramtres:
Si les données d'authentification sont déjà connues, l'appLogin doit être utilisé avec les paramètres :
Assurez-vous d'appeler appLogin avec ou sans paramètres après chaque départ d'application (en fonction de si l'utilisateur actuel est connu ou inconnu).
4.3. Tracer les ouvertures de message
Si vous souhaitez vérifier si les messages push ont été ouverts, c'est la fonction trackMessageOpen qu'il faut utiliser. Dans le plus simple des cas, il se trouvera dans la méthode didReceiveRemoteNotification:fetchCompletionHandler: de l'AppDelegate :
4.4. Tracer les événements client
Si vous souhaitez vérifier les événements personnalisés, c'est la fonction trackCustomEvent qu'il faut utliser, où le paramètre nomévénement est obligatoire, mais tous les autres attributs sont facultatifs:
4.5. Déconnexion
Lorsque l'utilisateur se déconnecte, la fonction appLogout doit être utilisée :
Après cette étape, l'installation est terminée.
Intégrer avec Android
1. Installation avec Gradle
Gradle est un système de construction pour Android, qui automatise et simplifie le processus d'utilisation de bibliothèques tierces.
2. Spécifier le SDK Mobile Engage
Pour intégrer le SDK Mobile Engage dans votre projet Android sur Gradle, vous devez le spécifier dans le fichier build.gradle de votre application :
Lorsque vous voyez <Chaîne> ou quelque chose de semblable entre <> crochets, vous devez les changer en fonction de votre convention de nommage personnalisée.
3. Obligations
La version minimum d'Android doit être au moins API level 14.
Le SDK Mobile Engage va de pair avec les dépendances Firebase, mais il ne vous fournit pas tous les paramètres nécessaires pour que votre appli fonctionne.
Pour intégrer Firebase dans votre appli, suivez les instructions dans la documentaiton Firebase. En revanche, vous n'avez pas besoin d'ajouter les dépendances de Firebase pourfirebase-core et firebase-messaging, car ils sont déjà inclus dans le SDK Mobile Engage.
Pour permettre au SDK Mobile Engage de gérer automatiquement les appels setPushToken et trackMessageOpen pour vous, merci de d'inscrire ces services dans votre manifeste :
De plus, vous pouvez installer une icône de notification personnalisée, en précisant qu'il s'agit de méta-données entre le tag de votre application :
4. Utilisation
4.1. Initialisation
Pour configurer le Kit de Développement (SDK), vous devez exécuter ce qui suit dans la méthodeonCreate dans la classe Application, Et nous pouvons configurer le statusListener également :
LestatusListenerpeut également être réglé plus tard; il n'est pas obligatoire pour l'initialisation de Mobile Engage:
Chaque appel renvoie un eventId, qui peut être utilisé avec le statusListener pour tracer nos appels. Le statusListener définit deux méthodes:
4.2. Connexion
Lorsque l'installation de l'application est terminée, vos pouvez utiliser les méthodes d'appLogin pour identifier l'utilisateur. Si vous souhaitez vérifier les uilisateurs aninymes, vous pouvez utiliser appLogin sans paramètres:
Si l'utilisateur est déjà connu, vous pouvez utiliser les paramètres : appLogin avec contactFieldID et contactFieldValue :
Assurez-vous d'appeler appLogin avec ou sans paramètres après chaque départ d'application (en fonction de si l'utilisateur actuel est connu ou inconnu).
4.3. Tracer les événements client
Si vous souhaitez vérifier les événements personnalisés, c'est la fonction trackCustomEvent qu'il faut utliser, où le paramètre nom est obligatoire, mais tous les autres attributs sont facultatifs:
4.4. Déconnexion
Lorsque l'utilisateur se déconnecte, la fonction appLogout doit être utilisée :
Après cette étape, l'installation est terminée.
Vérifier le SDK
Il y a deux méthodes pour vérifier l'intégration du SDK.
1. Vérifier les résultats des appels SDK
Chaque appel MobileEngage (appLogin, appLogout, trackCustomEvent) renvoie un unique eventId, ce qui vous permet de tracer le résultat de chaque appel.
Aussitôt que le SDK Mobile Engage reçoit une réaction de nos serveurs, le statusDelegate fourni sur iOS ou bien le MobileEngageStatusListener sur Android est notifié du succès de cet eventId:
- Si la requête a fonctionné, les méthodes
mobileEngageLogReceived(iOS), ouonStatusLog(Android) sont appelées avec l'eventIdet un message de log. - Si la demande a échoué, les méthodes
mobileEngageErrorHappened(iOS), ouonError(Android) sont sollicitées avec l'eventIdet l'Erreur/Exception. L'erreur/exception peut être une erreur de réseau (IOException) ou une exception personnalisée accompagnant la réponse du serveyr. Par exemple : 400 - Mauvaise demande.
2. Vérifier que les appels SDK sont reçus par nos serveurs
Vous pouvez vérifier si les appels SDK ont été reçus par nos serveurs en cliquant sur l'icône SDK events sur les onglets e Apps De l'interface utilisateur Mobile Engage.
La colonne Nom montre l'événement qui a été reçu alors que la colonne Statut montre le code de réponse. Si sa valeur est 201 ou 202,l'intégration du SDK est réussie.
Foire aux questions
Mises à jour du SDK
Chaque nouvelle sortie du SDK apporte soit de nouvelles fonctionnalités, soit des corrections de problèmes connus, donc il est toujours avantageux de mettre à jour vers la nouvelle version.
Nous faisons en sorte d'assurer que le SDK sot de qualité maximale, et cela implique de prendre en compte la compatibilité rétroactive.
De manière générale, il est conseillé de mettra à jour votre version aussi souvent que possible. Même si vous ne prévoyez pas d'incorporer des nouvelles fonctionnalités à votre appli, nous vous encourageons quand même à faire au moins une mise à jour lorsqu'une nouvelle version patch sort, afin de ne pas manquer les corrections de bogues et d'autres améliorations du SDK.
Le Versioning du SDK suit la logique x,y,z pour laquelle xest une version majeure, y est une version mineure, etz une version de correction (patch)
- Version majeure - C'est une nouvelle version importante, qui implique par exemple une fonctionnalité attendue impatiemment. Bien que cela arrive contre notre plein gré, il se peut qu'une nouvelle version majeure affecte la compatibilité rétroactive avec la précédente version. Nous nous efforçons d'en sortir un minimum et ce pour une raison importante. Ceci sera toujours communiqué avant.
- version mineure - Elle apporte de nouvelles petites fonctionnalités. Les versions mineures ne régressent jamais sur la compatibilité.
- Version de correction - Elle vous apporte des corrections de bugs, de la stabilité et des améliorations de performance. Les versions de correction ne régressent pas non plus sur la compatibilité.
Questions Android
Nous faisons notre possible pour maintenir à jour les dépendances en lançant périodiquement de nouvelles versions du SDK avec des versions de dépendance à jour. Toutefois, si c'est urgent et que vous ne pouvez pas attendre la nouvelle release, vous pouvez exclure manuellement les dépendances transitives dans votre fichier gradle de niveau module et ajouter les dépendances Firebase manuellement.
Vous devez remplacer les signes + par les versions les plus récentes.
Le but principal des services FCM par défaut dans le SDK est de fournir une implémentation qui fonctionne pour vous clés-en-mains quand vous intégrez le SDK. Nous essayons de conserver à ces services un caractère générique, de sorte qu'ils soient adaptés aux cas d'utilisation par défaut de nos clients. Si vous avez des besoins particuliers, nous vous conseillons d'implémenter vos propres services Firebase, sur la base de votre implémentation par défaut.
Quand vous implémentez votre propre service FCM, assurez-vous de manipuler messageOpens correctement.
Le problème n'est pas de notre côté, mais provient du service Firebase. Pour plus d'informations, consultez la documentation Firebase.
Si votre organisation a un firewall qui limite le trafic vers ou à partir d'Internet, vous devez le configurer pour autoriser la connectivité avec FCM , afin que vos apps de service Firebase Clouse Messaging reçoivent des messages. Les ports à ouvrir sont : 5228, 5229, et 5230. FCM n'utilise typiquement que 5228, mais parfois aussi 5229 et 5230. FCM ne fournit pas d'IPs spécifiques, donc vous devez autoriser votre firewall à accepter les connexions sortantes vers toutes les adresses IP contenues dans les blocs d'IP listés dans l'ASN Google de 15169. Pour plus d'informations, consultez la documentation du service Google Cloud Messaging.
Pour résoudre cela, veuillez faire les vérifications suivantes :
- Avez-vous téléchargé le json google-services. ? Si vous ne l'avez pas fait, veuillez consulter la documentation Firebase pour configurer d'abord votre appli avec firebase.
- Assurez-vous que votre connexion à Firebase n'est pas limitée par les règles de firewall de l'entreprise.
- Assurez-vous que vous voyez les jetons push dans vos logs SDK dans l' interface utilisateur Mobile Engage.
Assurez-vous d'avoir enregistrés nos srevices (MobileEngageMessagingService, MobileEngageInstanceIdService) dans votre AndroidManifest.xml.
Assurez-vous d'avoir enregistrés nos srevices (MobileEngageMessagingService, MobileEngageInstanceIdService) dans votre AndroidManifest.xml.
questions iOS
Si vous avez une application native, vous pouvez normalement obtenir le jeton push dans sa forme originelle (NSData) dans le Appdelegate de votre application :
didRegisterForRemoteNotificationsWithDeviceToken: method
Si vous n'avez aucun moyen de l'obtenir dans son format originel, vous pouvez utiliser la solution d'Apple pour créer NSData à partir de hexString:
Effectuer la migration de l'API Mobile Engage API au SDK Mobile Engage
iOS
Afin de passer au nouveau SDK Mobile Engage sur iOS, procédez comme suit :
1. Activer les services push
Les instructions pour activer les notifications push se trouvent dans la documentation officielle Apple iOS.
2. Initialiser le SDK Mobile Engage
Initialisez le SDKdans l'AppDelegate de votre appli. Pour en savoir plus, consultez le Guide d'intégration du SDK iOS Mobile Engage.
3. Passer des appels API aux invocations de la méthode SDK
Au lieu d'appels API, utilisez ces méthodes correspondantes :
MobileEngage.appLoginMobileEngage.appLogoutMobileEngage.trackCustomEvent4. Installer jeton push
Utilisez la méthode MobileEngage.setPushToken. Pour en savoir plus, consultez le Guide d'intégration du SDK iOS Mobile Engage.
Android
Afin de passer au nouveau SDK Mobile Engage sur Android, procédez comme suit :
1. Activer les services push
Vous devez ajouter Firebase à votre projet, soit via l'Assistant Firebase, soit manuellement. Pour en savoir plus, consultez la rubrique Intégrer avec Android ci-dessus.
2. Initialiser le SDK Mobile Engage
Initialisez le SDK dans la méthodeonCreate dans la classe de l'application. Pour en savoir plus, consultez le Guide d'intégration du SDK Android Mobile Engage.
3. Passer des appels API aux invocations de la méthode SDK
Au lieu d'appels API, utilisez ces méthodes correspondantes :
MobileEngage.appLoginMobileEngage.appLogoutMobileEngage.trackCustomEvent