iOS SDK Integration Guide

Version applicable

Cet article concerne la version du SDK MTPush iOS : v3.0.0 et ultérieures.

Fichier de ressources

Nom du package : engagelab-ios-{numéro de version}

À partir de la version 4.3.3, le package .a ne sera plus fourni. Seuls les packages .xcframework seront proposés.

• Dossier lib : contient mtpush-ios-x.x.x.xcframework, mtpush-extension-ios-x.x.x.xcframework. (Remarque : APNs n'est pas pris en charge sur les simulateurs).
• Fichier README : instructions relatives au SDK
• Dossier demo : exemples

Obtention des informations de l'application

Après la création d'une application sur la console, un AppKey est automatiquement généré pour identifier l'application.

Configuration du projet

Importer le SDK

Importation via Cocoapods

              
                  pod 'MTPush'

    Remarque : Si vous ne pouvez pas importer la dernière version, exécutez la commande pod repo update master pour mettre à jour la bibliothèque pod locale puis relancez pod 'MTPush'.

            

• Si vous devez installer une version spécifique, utilisez la méthode suivante (exemple avec MTPush 3.5.0) :

              
                  pod 'MTPush', '3.5.0'

            

Importation manuelle

• Décompressez le package SDK, dans Xcode, sélectionnez "Add files to 'Nom de votre projet'...", et ajoutez mtpush-ios-x.x.x.xcframework à votre répertoire de projet.
• Ajouter les Frameworks
  • CFNetwork.framework
  • CoreFoundation.framework
  • CoreTelephony.framework
  • SystemConfiguration.framework
  • CoreGraphics.framework
  • Foundation.framework
  • UIKit.framework
  • Security.framework
  • libz.tbd
  • UserNotifications.framework
  • libresolv.tbd
  • libsqlite3.tbd

Paramètres de compilation (Build Settings)

Si votre projet doit prendre en charge des systèmes d'exploitation iOS inférieurs à 7.0, veuillez aller dans Build Settings et désactiver l'option bitCode. Sinon, la compilation échouera.

• Définissez les User Header Search Paths et Library Search Paths dans Search Paths. Par exemple, si le dossier SDK (par défaut lib) est au même niveau que le fichier projet, définissez ce paramètre sur $(SRCROOT)/{Nom du dossier contenant la bibliothèque statique}.

Capacités

Si vous développez avec Xcode 8 ou supérieur, activez l'option Capabilities->Push Notifications dans l'Application Target, comme illustré ici :
Si vous développez dans un environnement Xcode 10 ou supérieur, activez l'option Capabilities->Access WIFI Infomation sur votre Application Target.

Ajout d'un fichier d'en-tête

Ajoutez le code suivant à l'emplacement du fichier d'en-tête de référence AppDelegate.m.

              
              // importer le fichier d'en-tête nécessaire pour la fonction MTPush
#import "MTPushService.h"
// iOS10 Enregistrer le fichier d'en-tête requis pour APNs
#ifdef NSFoundationVersionNumber_iOS_9_x_Max
#import <UserNotifications/UserNotifications.h>
#endif
// Fichiers d'en-tête à importer si vous souhaitez utiliser la fonctionnalité idfa (optionnel)
#import <AdSupport/AdSupport.h>

            

Ajouter le Delegate

Ajoutez un Delegate à l'AppDelegate. Référez-vous au code suivant :

              
              @interface AppDelegate ()<MTPushRegisterDelegate>

@end

            

Ajouter le code d'initialisation

Ajouter le code d'initialisation APNs

Veuillez ajouter le code suivant à -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

              
                //Obligatoire
 
    MTPushRegisterEntity * entity = [[MTPushRegisterEntity alloc] init];
  entity.types = MTPushAuthorizationOptionAlert|MTPushAuthorizationOptionSound|MTPushAuthorizationOptionProvidesAppNotificationSettings;
  if ([[UIDevice currentDevice].systemVersion floatValue] >= 8.0) {
    // Des personnalisations peuvent être ajoutées aux catégories
    // NSSet<UNNotificationCategory *> *categories pour iOS10 ou ultérieur
    // NSSet<UIUserNotificationCategory *> *categories pour iOS8 et iOS9
  }
  [MTPushService registerForRemoteNotificationConfig:entity delegate:self];

            

Ajouter le code d'initialisation MTPush

Veuillez ajouter le code suivant à -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

              
              // Optionnel
// Obtenir l'IDFA
// Pour utiliser la fonction IDFA, ajoutez ce code et renseignez le paramètre advertisingIdentifier pour la méthode d'initialisation
NSString *advertisingId = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];

// Obligatoire
// Initialiser Push
[MTPushService setupWithOption:launchOptions appKey:appKey
                      channel:channel
             apsForProduction:isProduction
        advertisingIdentifier:advertisingId];

            

Description des paramètres

• appKey
  • Assurez-vous que l'appkey configuré dans l'application est identique à celui généré après la création de l'application sur la Console.
• channel
  • Spécifiez le canal de téléchargement du package applicatif. Pour faciliter les statistiques par canal, vous pouvez définir la valeur spécifique vous-même, par exemple App Store.
• apsForProduction
  • Ce paramètre identifie l'environnement du certificat APNs utilisé par l'application actuelle.
  • 0 (valeur par défaut) indique qu'un certificat de développement est utilisé, et 1 indique qu'un certificat de production est utilisé pour publier les applications.
  • Remarque : La valeur de ce champ doit être identique à l'environnement du certificat configuré dans Code Signing pour Build Settings.

APNs est enregistré avec succès et le DeviceToken est signalé.

Astuce : Vous pouvez vous connecter à EngageLab sans appeler cette méthode. Cependant, les notifications APNs ne seront pas disponibles, seules les messages personnalisés pourront être utilisés.

Implémentez la méthode de rappel dans AppDelegate.m et ajoutez le code dans la méthode de rappel :

              
              - (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {

  /// Obligatoire - DeviceToken enregistré
  [MTPushService registerDeviceToken:deviceToken];
}

            

Implémenter l'interface d'échec d'enregistrement APNs (Optionnel)

              
              - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
  //Optionnel
  NSLog(@"did Fail To Register For Remote Notifications With Error: %@", error);
   [MTPushService registerDeviceToken:deviceToken];
}

            

Ajouter une méthode de rappel pour gérer les notifications APNs

Implémentez la méthode de rappel dans AppDelegate.m et ajoutez le code dans la méthode de rappel :

              
              #pragma mark- MTPushRegisterDelegate

// Support iOS 12
- (void)mtpNotificationCenter:(UNUserNotificationCenter *)center openSettingsForNotification:(UNNotification *)notification{if (notification && [notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {// Entrée directe dans l'application depuis l'interface de notification.}else{// Entrée dans l'application depuis l'interface des paramètres de notification.}
}

// Support iOS 10
- (void)mtpNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(NSInteger))completionHandler {
  // Obligatoire
  NSDictionary * userInfo = notification.request.content.userInfo;
  if([notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {[MTPushService handleRemoteNotification:userInfo];
  }
  completionHandler(UNNotificationPresentationOptionAlert); // Pour exécuter cette méthode, choisissez d'alerter ou non l'utilisateur. Trois types sont disponibles : Badge, Son et alerte.
}

// Support iOS 10
- (void)mtpNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)())completionHandler {
  // Obligatoire
  NSDictionary * userInfo = response.notification.request.content.userInfo;
  if([response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {[MTPushService handleRemoteNotification:userInfo];
  }
  completionHandler();	// Le système exige l'exécution de cette méthode}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {

  // Obligatoire, support iOS 7
  [MTPushService handleRemoteNotification:userInfo];
  completionHandler(UIBackgroundFetchResultNewData);
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {

  // Obligatoire, pour les systèmes iOS 6 ou antérieurs
  [MTPushService handleRemoteNotification:userInfo];
}

            

Ajout d'une méthode de rappel pour gérer les messages personnalisés MTPush

Pour utiliser la fonctionnalité de message personnalisé de MTPush, consultez le 【Guide API iOS】 pour implémenter les callbacks de traitement des messages personnalisés.

Exécution réussie

Déboguez le projet. Si la console affiche le log suivant, l'intégration a réussi.

              
              2016-08-19 17:12:12.745823 219b28[1443:286814] | MTP | I - [MTCORETcpEventController] 
----- login result -----
uid:123456 
registrationID:171976fa8a8620a14a4 
idc:0

            

Si vous rencontrez des problèmes lors du débogage, veuillez vous référer au 【Guide de débogage SDK iOS】.

Fonctionnalités avancées

Écoute des événements liés au SDK MTPush

Il est recommandé que les développeurs incluent les types de notifications suivants fournis dans l'API :

extern NSString *const kMTCNetworkIsConnectingNotification; // Connexion en cours
extern NSString * const kMTCNetworkDidSetupNotification; // Connexion établie
extern NSString * const kMTCNetworkDidCloseNotification; // Connexion fermée
extern NSString * const kMTCNetworkDidRegisterNotification; // Enregistrement réussi
extern NSString *const kMTCNetworkFailedRegisterNotification; // Échec de l'enregistrement
extern NSString * const kMTCNetworkDidLoginNotification; // Connexion réussie

extern NSString * const kMTCNetworkDidReceiveMessageNotification; // Message personnalisé reçu (non-APNS)
Le transfert de données kMTCNetworkDidReceiveMessageNotification peut être obtenu via userInfo dans NSNotification, incluant le titre, le contenu et les informations supplémentaires, etc. Veuillez consulter le document : API SDK iOS

Service de statistiques des notifications

Les développeurs peuvent utiliser le SDK Notification Service Extension pour signaler le statut de livraison de chaque message APNs. Remarque : Les données d'Impressions affichées sur la console EngageLab proviennent des données de livraison signalées ici.

Utilisation :

• Créez un Service Extension. Pour plus de détails, voir iOS 10 Service Extension.
• Importez le fichier mtpush-extension-ios-xxx.xcframework dans votre projet Service Extension.
• Ajoutez les Frameworks : libz.tbd et libresolv.tbd.
• Appelez [mtpushSetAppkey:] pour définir votre appkey. Veuillez noter que cet appkey doit être identique à celui de votre application EngageLab.
• Appelez la méthode [mtpushReceiveNotificationRequest:] pour signaler votre apns, les statistiques sont alors prises en compte ; affichez l'apns dans le callback block de la méthode.

Pour des exemples d'utilisation plus précis, référez-vous au code Demo inclus dans le package zip de la version. Document de référence : API SDK iOS

Voip Push

• Introduit dans iOS 8, le push Voip basé sur le framework PushKit permet à l'application de l'utilisateur de se réveiller et d'exécuter du code même lorsqu'elle est tuée.
• Voip ne distingue pas les certificats de développement et de production. Les certificats Apple Push Notification service SSL (Sandbox & Production) et VoIP Services Certificate prennent en charge le push Voip.

Ajouter la bibliothèque PushKit.Framework

• Ajoutez la bibliothèque PushKit.framework dans Xcode Build Phases - Link Binary With Libraries.
• Importez le fichier d'en-tête #import <PushKit/PushKit.h>.
• Implémentez le protocole PKPushRegistryDelegate dans AppDelegate.

Ajouter l'autorisation Voip

Dans Project->Capabilities->Background Modes, activez l'option Voice over IP.

Implémentation du code

• Implémentez l'enregistrement Voip dans la méthode didFinishLaunchingWithOptions.

              
              - (void)voipRegistration{
  dispatch_queue_t mainQueue = dispatch_get_main_queue();
  PKPushRegistry *voipRegistry = [[PKPushRegistry alloc] initWithQueue:mainQueue];
  voipRegistry.delegate = self;
  // Définir le type de push sur VoIP
  voipRegistry.desiredPushTypes = [NSSet setWithObject:PKPushTypeVoIP];
}

            

• Soumettre le Token

              
              /// Le système retourne le VoipToken, à signaler au serveur EngageLab
- (void)pushRegistry:(PKPushRegistry *)registry didUpdatePushCredentials:(PKPushCredentials *)pushCredentials forType:(PKPushType)type{
   if (type == PKPushTypeVoIP) {
    [MTPushService registerVoipToken:pushCredentials.token];
   }
}

            

• Lors de la réception d'un push Voip, appelez l'interface de réception pour compter les livraisons Voip.

              
              - (void)pushRegistry:(PKPushRegistry *)registry didReceiveIncomingPushWithPayload:(PKPushPayload *)payload forType:(PKPushType)type{
  if (type == PKPushTypeVoIP) {
    // Soumettre le reçu au serveur EngageLab
    [MTPushService handleVoipNotification:payload.dictionaryPayload];
  }
}

- (void)pushRegistry:(PKPushRegistry *)registry didReceiveIncomingPushWithPayload:(PKPushPayload *)payload forType:(PKPushType)type withCompletionHandler:(void(^)(void))completion{
   if (type == PKPushTypeVoIP) {
    // Soumettre le reçu au serveur EngageLab
    [MTPushService handleVoipNotification:payload.dictionaryPayload];
   }
}

            

Support technique

En cas de problème lors de l'intégration

• Veuillez lire attentivement la documentation pour vérifier s'il n'y a pas d'omissions.
• Vous pouvez aller sur EngageLab pour rechercher une question similaire. Pour résoudre le problème plus rapidement, veuillez fournir les informations suivantes lors de votre demande d'aide :
  • Le produit pour lequel vous souhaitez consulter est MTPush, et si vous utilisez d'autres produits EngageLab.
  • Quelle API vous appelez, les paramètres transmis, le message d'erreur complet et le moment où l'exception s'est produite.
  • Si aucun message n'est reçu, fournissez l'Appkey de l'application, l'ID du message et l'ID d'enregistrement de l'appareil.
  • Si le problème est causé par le SDK, veuillez fournir la version du SDK concernée ainsi que les logs complets. Téléchargez les informations de logs au format TXT.
  • Si l'appareil défectueux est sous iOS, veuillez fournir le modèle et le système précis.