iOS SDK Integration Guide
Anwendbare Version
Dieser Artikel gilt für die MTPush iOS SDK-Version: v3.0.0 und höher.
Ressourcenpaket
Paketname: engagelab-ios-{Versionsnummer} (Ressourcenpaket für das MTPush iOS SDK)
Ab Version 4.3.3 wird das .a-Paket nicht mehr bereitgestellt. Es werden ausschließlich .xcframework-Pakete angeboten.
- lib-Ordner: Enthält mtpush-ios-x.x.x.xcframework und mtpush-extension-ios-x.x.x.xcframework. (Hinweis: APNs-Benachrichtigungen werden auf Simulatoren nicht unterstützt.)
- README-Datei: SDK-Anleitung
- demo-Ordner: Beispielprojekte
Abrufen von Anwendungsinformationen
Nach dem Erstellen einer Anwendung in der EngageLab-Konsole wird automatisch ein AppKey generiert, der die Anwendung eindeutig identifiziert (AppKey zur eindeutigen Identifizierung der Anwendung).
Projekteinstellungen
SDK importieren
Cocoapods-Import
pod 'MTPush'
Hinweis: Falls Sie die neueste Version nicht importieren können, führen Sie den Befehl pod repo update master aus, um das lokale Pod-Repository zu aktualisieren, und wiederholen Sie anschließend pod 'MTPush'.
- Wenn Sie eine bestimmte Version installieren möchten, verwenden Sie folgende Methode (hier am Beispiel von MTPush 3.5.0):
pod 'MTPush', '3.5.0'
Manueller Import
- Entpacken Sie das SDK-Paket und fügen Sie in Xcode über „Dateien zu ‚Ihr Projektname‘ hinzufügen...“ die mtpush-ios-x.x.x.xcframework in Ihr Projektverzeichnis ein.
- Fügen Sie folgende Frameworks hinzu:
- CFNetwork.framework
- CoreFoundation.framework
- CoreTelephony.framework
- SystemConfiguration.framework
- CoreGraphics.framework
- Foundation.framework
- UIKit.framework
- Security.framework
- libz.tbd
- UserNotifications.framework
- libresolv.tbd
- libsqlite3.tbd
Build-Einstellungen für iOS-Projekte
Falls Ihr Projekt Unterstützung für iOS-Versionen unter 7.0 benötigt, deaktivieren Sie in den Build Settings die Option bitCode. Andernfalls wird das Projekt nicht korrekt kompiliert.
Legen Sie die User Header Search Paths und Library Search Paths in den Sucheinstellungen fest. Liegt der SDK-Ordner (Standard: lib) auf derselben Ebene wie die Projektdatei, setzen Sie diesen Parameter auf $(SRCROOT)/{Name des Ordners, in dem sich die statische Bibliothek befindet}.
Capabilities
Wenn Sie mit Xcode 8 oder höher entwickeln, aktivieren Sie im Application Target die Option Capabilities → Push Notifications, wie hier gezeigt:
Wenn Sie in einer Xcode 10- oder höheren Umgebung entwickeln, aktivieren Sie zusätzlich im Application Target die Option Capabilities → Access WIFI Information.
Hinzufügen einer Header-Datei
Fügen Sie folgenden Code an der Stelle ein, an der die Header-Datei in AppDelegate.m referenziert wird:
// Erforderliche Header-Datei für MTPush-Funktionen importieren
#import "MTPushService.h"
// Für iOS10 erforderliche Header-Datei zur APNs-Registrierung
#ifdef NSFoundationVersionNumber_iOS_9_x_Max
#import <UserNotifications/UserNotifications.h>
#endif
// Header-Datei für IDFA-Funktionalität importieren (optional)
#import <AdSupport/AdSupport.h>
Delegate im AppDelegate hinzufügen
Fügen Sie einen Delegate zum AppDelegate hinzu. Beispiel:
@interface AppDelegate ()<MTPushRegisterDelegate>
@end
Initialisierungscode hinzufügen
Initialisierungscode für APNs hinzufügen
Fügen Sie den folgenden Code in
-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
ein:
// Erforderlich
MTPushRegisterEntity * entity = [[MTPushRegisterEntity alloc] init];
entity.types = MTPushAuthorizationOptionAlert|MTPushAuthorizationOptionSound|MTPushAuthorizationOptionProvidesAppNotificationSettings;
if ([[UIDevice currentDevice].systemVersion floatValue] >= 8.0) {
// Eigene Kategorien können hinzugefügt werden
// NSSet<UNNotificationCategory *> *categories für iOS10 oder höher
// NSSet<UIUserNotificationCategory *> *categories für iOS8 und iOS9
}
[MTPushService registerForRemoteNotificationConfig:entity delegate:self];
Initialisierungscode für MTPush hinzufügen
Fügen Sie den folgenden Code in
-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
ein:
// Optional
// IDFA abrufen
// Um die IDFA-Funktion zu nutzen, fügen Sie diesen Code hinzu und übergeben Sie den advertisingIdentifier-Parameter an die Initialisierungsmethode
NSString *advertisingId = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
// Erforderlich
// Push initialisieren
[MTPushService setupWithOption:launchOptions appKey:appKey
channel:channel
apsForProduction:isProduction
advertisingIdentifier:advertisingId];
Parameterbeschreibung
- appKey
- AppKey-Konfiguration überprüfen: Stellen Sie sicher, dass der in der Anwendung konfigurierte AppKey mit dem nach der Erstellung in der Konsole generierten AppKey übereinstimmt.
- channel
- Gibt den Download-Kanal des Anwendungspakets an. Zur besseren Statistik können Sie den Wert selbst festlegen, z. B. App Store.
- apsForProduction
- Gibt an, welche APNs-Zertifikatsumgebung verwendet wird.
- 0 (Standardwert) bedeutet Entwicklungszertifikat, 1 steht für Produktionszertifikat.
- Hinweis: Der Wert muss mit der in den Build Settings unter Code Signing konfigurierten Zertifikatsumgebung übereinstimmen.
APNs-Registrierung und DeviceToken erfolgreich übermitteln
Tipp: Sie können sich bei EngageLab anmelden, ohne diese Methode aufzurufen. Allerdings stehen dann keine APNs-Benachrichtigungen zur Verfügung, sondern nur eigene Nachrichten.
Implementieren Sie die Callback-Methode in AppDelegate.m und fügen Sie dort folgenden Code ein:
- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
/// Erforderlich – DeviceToken registrieren
[MTPushService registerDeviceToken:deviceToken];
}
Fehlerhafte APNs-Registrierung behandeln (optional)
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
// Optional
NSLog(@"did Fail To Register For Remote Notifications With Error: %@", error);
[MTPushService registerDeviceToken:deviceToken];
}
Callback-Methode zur Verarbeitung von APNs-Benachrichtigungen hinzufügen
Implementieren Sie die Callback-Methoden in AppDelegate.m und fügen Sie dort folgenden Code ein:
#pragma mark- MTPushRegisterDelegate
// iOS 12 Support
- (void)mtpNotificationCenter:(UNUserNotificationCenter *)center openSettingsForNotification:(UNNotification *)notification{
if (notification && [notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {
// Direkter Einstieg in die App über die Benachrichtigungsoberfläche.
} else {
// Einstieg über die Benachrichtigungseinstellungen.
}
}
// iOS 10 Support
- (void)mtpNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(NSInteger))completionHandler {
// Erforderlich
NSDictionary * userInfo = notification.request.content.userInfo;
if([notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {
[MTPushService handleRemoteNotification:userInfo];
}
completionHandler(UNNotificationPresentationOptionAlert); // Hier kann festgelegt werden, ob ein Alert angezeigt wird. Es gibt Badge, Sound und Alert.
}
// iOS 10 Support
- (void)mtpNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)())completionHandler {
// Erforderlich
NSDictionary * userInfo = response.notification.request.content.userInfo;
if([response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {
[MTPushService handleRemoteNotification:userInfo];
}
completionHandler(); // Muss vom System ausgeführt werden
}
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
// Erforderlich, iOS 7 Support
[MTPushService handleRemoteNotification:userInfo];
completionHandler(UIBackgroundFetchResultNewData);
}
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
// Erforderlich, für Systeme bis einschließlich iOS 6
[MTPushService handleRemoteNotification:userInfo];
}
Callback-Methode zur Verarbeitung von MTPush-eigenen Nachrichten hinzufügen
Um die Funktion für eigene Nachrichten von MTPush zu nutzen, lesen Sie bitte den 【iOS API Guide】 und implementieren Sie die entsprechenden Callback-Methoden.
Erfolgreiche Integration und Debugging
Starten Sie das Projekt im Debug-Modus. Wenn die Konsole folgendes Log ausgibt, war die Integration erfolgreich:
2016-08-19 17:12:12.745823 219b28[1443:286814] | MTP | I - [MTCORETcpEventController]
----- login result -----
uid:123456
registrationID:171976fa8a8620a14a4
idc:0
Sollten während des Debuggens Probleme auftreten, lesen Sie bitte den 【iOS SDK Debugging Guide】.
Erweiterte Funktionen
Ereignisüberwachung für das MTPush SDK
Es wird empfohlen, dass Entwickler:innen folgende Benachrichtigungen aus der API einbinden:
extern NSString *const kMTCNetworkIsConnectingNotification; // Verbindungsaufbau
extern NSString * const kMTCNetworkDidSetupNotification; // Verbindung hergestellt
extern NSString * const kMTCNetworkDidCloseNotification; // Verbindung geschlossen
extern NSString * const kMTCNetworkDidRegisterNotification; // Registrierung erfolgreich
extern NSString *const kMTCNetworkFailedRegisterNotification; // Registrierung fehlgeschlagen
extern NSString * const kMTCNetworkDidLoginNotification; // Login erfolgreich
Tipp:
Fügen Sie die Methode zum Registrieren der Benachrichtigung kMTCNetworkDidLoginNotification hinzu und holen Sie sich die Registration ID in dieser Methode. Alternativ können Sie auch die Methode registrationIDCompletionHandler: verwenden, um die Registration ID per CompletionHandler zu erhalten.
extern NSString * const kMTCNetworkDidReceiveMessageNotification; // Eigene Nachricht (nicht APNS) empfangen
Die Daten der Benachrichtigung kMTCNetworkDidReceiveMessageNotification können über userInfo in NSNotification abgerufen werden, inklusive Titel, Inhalt und Extras. Weitere Informationen finden Sie im Dokument: iOS SDK API
Benachrichtigungsstatistiken mit Notification Service Extension
Tipp:
Die Notification Service Extension ist eine neue Funktion ab iOS 10, die über das mutable-content-Feld gesteuert wird.
Wenn Sie über die Web-Konsole pushen, aktivieren Sie in den optionalen Einstellungen die Option mutable-content. Beim Versand per RESTful API setzen Sie das Feld mutable-content auf true.
Entwickler:innen können mit dem Notification Service Extension SDK den Zustellstatus jeder APNs-Nachricht melden.
Hinweis: Die Impressions-Daten, die in der EngageLab-Konsole angezeigt werden, stammen aus den hier gemeldeten Zustelldaten.
Vorgehensweise:
- Erstellen Sie einen Service Extension Service. Details finden Sie unter iOS 10 Service Extension.
- Importieren Sie die Datei mtpush-extension-ios-xxx.xcframework in Ihr Service Extension-Projekt.
- Frameworks hinzufügen: libz.tbd und libresolv.tbd.
- Rufen Sie [mtpushSetAppkey:] auf, um Ihren AppKey zu setzen. Dieser muss mit dem AppKey Ihrer EngageLab-Anwendung übereinstimmen.
- Rufen Sie [mtpushReceiveNotificationRequest:] auf, um Ihre APNs zu melden; die Statistik wird entsprechend erfasst. Die Anzeige der APNs erfolgt im Block-Callback der Methode.
Weitere Anwendungsbeispiele finden Sie im Demo-Code des Version-Zip-Pakets.
Referenzdokument: iOS SDK API
VoIP Push-Benachrichtigungen mit PushKit
- VoIP Push wurde in iOS 8 eingeführt und basiert auf dem PushKit-Framework. Damit kann die App auch dann aufgeweckt und Code ausgeführt werden, wenn sie beendet wurde.
- VoIP unterscheidet nicht zwischen Entwicklungs- und Produktionszertifikaten. Sowohl Apple Push Notification service SSL (Sandbox & Production) als auch VoIP Services Certificate unterstützen VoIP Push.
PushKit.Framework-Bibliothek hinzufügen
- Fügen Sie in Xcode unter Build Phases → Link Binary With Libraries die PushKit.framework-Bibliothek hinzu.
- Importieren Sie die Header-Datei mit
#import <PushKit/PushKit.h>. - Implementieren Sie das PKPushRegistryDelegate-Protokoll im AppDelegate.
VoIP-Berechtigung hinzufügen
Aktivieren Sie unter Projekt → Capabilities → Background Modes die Option Voice over IP.
Code-Implementierung
- Implementieren Sie die VoIP-Registrierung in der Methode didFinishLaunchingWithOptions.
- (void)voipRegistration{
dispatch_queue_t mainQueue = dispatch_get_main_queue();
PKPushRegistry *voipRegistry = [[PKPushRegistry alloc] initWithQueue:mainQueue];
voipRegistry.delegate = self;
// Push-Typ auf VoIP setzen
voipRegistry.desiredPushTypes = [NSSet setWithObject:PKPushTypeVoIP];
}
- Token übermitteln
/// System gibt VoipToken zurück, an Engagelab-Server melden
- (void)pushRegistry:(PKPushRegistry *)registry didUpdatePushCredentials:(PKPushCredentials *)pushCredentials forType:(PKPushType)type{
if (type == PKPushTypeVoIP) {
[MTPushService registerVoipToken:pushCredentials.token];
}
}
- Bei Empfang eines VoIP Push den Empfang melden, um VoIP-Zustellungen zu zählen.
- (void)pushRegistry:(PKPushRegistry *)registry didReceiveIncomingPushWithPayload:(PKPushPayload *)payload forType:(PKPushType)type{
if (type == PKPushTypeVoIP) {
// Empfang an Engagelab-Server melden
[MTPushService handleVoipNotification:payload.dictionaryPayload];
}
}
- (void)pushRegistry:(PKPushRegistry *)registry didReceiveIncomingPushWithPayload:(PKPushPayload *)payload forType:(PKPushType)type withCompletionHandler:(void(^)(void))completion{
if (type == PKPushTypeVoIP) {
// Empfang an Engagelab-Server melden
[MTPushService handleVoipNotification:payload.dictionaryPayload];
}
}
Technischer Support für MTPush iOS SDK
Bei Problemen während der Integration:
- Lesen Sie die Dokumentation sorgfältig, um mögliche Auslassungen zu vermeiden.
- Sie können auf EngageLab nach ähnlichen Fragen suchen.
Um Ihr Problem schneller zu lösen, geben Sie bitte folgende Informationen an:
- Das Produkt, zu dem Sie eine Anfrage haben (MTPush), und ob Sie weitere EngageLab-Produkte nutzen.
- Welche API Sie aufrufen, welche Parameter Sie übergeben, die vollständige Fehlermeldung und den Zeitpunkt des Auftretens.
- Falls keine Nachricht empfangen wird, geben Sie den AppKey der Anwendung, die Message ID der Nachricht und die Registrierungs-ID des Geräts an.
- Bei SDK-bedingten Fehlern geben Sie bitte die entsprechende SDK-Version und vollständige Log-Aufzeichnungen an. Laden Sie die Log-Informationen als TXT-Datei hoch.
- Bei einem Fehler auf einem iOS-Gerät geben Sie bitte das genaue Modell und das verwendete System an.
