Integrationsleitfaden für das iOS MA SDK

Anwendbare Versionen

Dieser Leitfaden gilt für das eigenständige MTMA SDK ab v5.5.0. Das SDK unterstützt derzeit iOS 10 und höher.

Für Versionen vor 5.5.0 siehe den Integrationsleitfaden für Versionen vor 5.5.0.

Ab v5.5.0 kann das MTMA SDK unabhängig von AppPush integriert und initialisiert werden. MTMA und AppPush haben getrennte Codebasen. Das offizielle SDK wird weiterhin als kombiniertes Push-Paket ausgeliefert. Entwickler können daraus nur MTMA oder sowohl MTMA als auch MTPush integrieren.

Projekt konfigurieren

SDK importieren

Import über CocoaPods

              
                  pod 'MTMA'

    Hinweis: Falls die neueste Version nicht importiert werden kann, aktualisieren Sie das lokale Pod-Repository mit pod repo update und führen Sie anschließend erneut pod 'MTMA' aus.

            

• Verwenden Sie folgende Syntax, um eine bestimmte Version zu installieren (hier MTMA 5.5.0):

              
                  pod 'MTMA', '5.5.0'

            

Manueller Import

• Entpacken Sie das SDK-Paket. Wählen Sie in Xcode „Add files to 'Your project name'...“ und fügen Sie MTMA-ios-x.x.x.xcframework Ihrem Projektverzeichnis hinzu.

Datenschutzmanifest

Das SDK-Paket enthält PrivacyInfo.xcprivacy. Wird diese Datei nicht automatisch in die gepackte App übernommen, ergänzen Sie das Datenschutzmanifest Ihrer App anhand dieser Datei.

SDK initialisieren

Das eigenständige MTMA SDK wird mit einem MA AppKey initialisiert und muss weder auf die Initialisierung noch auf die erfolgreiche Registrierung von AppPush warten.

Konfigurieren Sie vor der Initialisierung in der MA-Konsole die zum MA AppKey gehörende Datenquelle des aktuellen Projekts mit derselben iOS Bundle ID wie die App und aktivieren Sie die Datenquelle. Das SDK liest den Bundle Identifier der App automatisch; eine separate Einstellung ist nicht erforderlich. Eine fehlende Bindung oder eine Abweichung führt zum Fehlschlagen der Initialisierung.

Wenn die Initialisierung 55004 zurückgibt und message packageName is not bound enthält, prüfen Sie die oben beschriebene Bindung.

              
              - (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    MTMAConfig *config = [[MTMAConfig alloc] init];
    config.appKey = @"Ihr MA AppKey";
    config.resultCompletion = ^(MTMAInitResult *result) {
        NSLog(@"result：%ld - %@", result.code, result.message);
    };
    [MTMAService start:config];

    return YES;
}

            

Erläuterung ausgewählter Parameter

• appKey
  • MA AppKey. Erforderlich; muss aus genau 24 Buchstaben oder Ziffern bestehen.
  • MA AppKey und Push AppKey sind unabhängig voneinander und können gleich oder unterschiedlich sein.
• resultCompletion
  • Callback für das Initialisierungsergebnis. Prüfen Sie den Erfolg über result.isSuccess. Bei einem Fehler dienen result.code und result.message der Diagnose.
  • Das zurückgegebene Objekt und seine Felder sind unter Klasse MTMAInitResult beschrieben.

Die Initialisierung benötigt eine Netzwerkverbindung. Ist das Gerät offline, wartet das SDK und setzt den Vorgang automatisch fort, sobald die Verbindung wieder verfügbar ist. Es erfolgt kein sofortiger Fehler-Callback.

Das SDK unterstützt wiederholte Initialisierungen und den Wechsel des MA AppKey. Jeder gültige Aufruf wird der Reihe nach ausgeführt und erhält einen eigenen Callback. Details siehe MA-Funktionen starten.

Benutzerkennungen bei der Initialisierung festlegen

Um Benutzerkennungen bei der Initialisierung festzulegen, übergeben Sie diese über MTMAConfig.userID. userID, anonymousID, email und phone sind optional. Das folgende Beispiel verwendet userID:

              
              MTMAUserID *userID = [[MTMAUserID alloc] init];
userID.userID = @"member_10001";

MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = @"Ihr MA AppKey";
config.userID = userID;
config.resultCompletion = ^(MTMAInitResult *result) {
    if (result.isSuccess) {
        NSLog(@"MTMA-Initialisierung erfolgreich");
    } else {
        NSLog(@"MTMA-Initialisierung fehlgeschlagen, code=%ld, message=%@", (long)result.code, result.message);
    }
};
[MTMAService start:config];

            

Die Initialisierung ist auch ohne Benutzerkennungen möglich. Eine erfolgreiche Initialisierung bedeutet nicht, dass jede Kennung erfolgreich gesetzt wurde. Feldvalidierung und Callbacks sind unter Klasse MTMAUserID beschrieben.

Initialisierungsszenarien

AppPush zusammen mit MTMA verwenden

Wählen Sie beim Konfigurieren einer mobilen Datenquelle in der MA-Konsole die zusätzliche Nutzung von AppPush sowie die tatsächlich integrierte AppPush-Anwendung aus. Initialisieren Sie AppPush mit dem AppKey dieser Anwendung.

Initialisieren Sie MTMA und AppPush separat. Eine feste Reihenfolge ist nicht erforderlich.

              
              // Push SDK initialisieren
[MTPushService setupWithOption:launchOptions
                        appKey:pushAppKey
                       channel:channel
              apsForProduction:isProduction
         advertisingIdentifier:nil];

// MTMA SDK initialisieren
MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = maAppKey;
config.resultCompletion = ^(MTMAInitResult *result) {
    NSLog(@"result：%ld - %@", result.code, result.message);
};
[MTMAService start:config];

            

Nach erfolgreicher AppPush-Registrierung und Erhalt einer Push RegistrationID richtet das MTMA SDK den AppPush-Kanal automatisch ein. Eine fehlende AppPush-Registrierung oder ein Fehler bei der Kanaleinrichtung beeinträchtigt weder die MTMA-Initialisierung noch die Ereigniserfassung und -übermittlung.

Kanal-Kontakt-IDs festlegen

Um einen Push-Drittanbieter zu verwenden, legen Sie dessen RID oder Token nach erfolgreicher MTMA-Initialisierung fest.

              
              [MTMAService setChannelValueWithChannelId:136
                                   values:@[@"Push-RID oder Token"]
                               completion:^(NSInteger code, NSString *message) {
    NSLog(@"result：%ld - %@", code, message);
}];

            

Erläuterung ausgewählter Parameter

• channelId
  • ID des in der MA-Konsole konfigurierten Push-Drittanbieterkanals; muss größer als 0 sein.
• values
  • Array mit RIDs oder Tokens des Push-Drittanbieters. Weder das Array noch seine Elemente dürfen leer sein.
  • Rufen Sie die API bei einer Änderung der RID oder des Tokens erneut auf, um den Wert zu aktualisieren.

Diese API ist nur für Push-Drittanbieter vorgesehen. Die genauen Einschränkungen finden Sie unter Kanal-Kontakt-IDs festlegen.

Upgrade von früheren Versionen

• Das offizielle SDK wird weiterhin als kombiniertes Push-Paket ausgeliefert. Projekte, die bereits AppPush und MTMA integrieren, müssen ihr manuelles Importverfahren nicht ändern.
• Nach dem Upgrade auf v5.5.0 muss appKey in MTMAConfig gesetzt werden.
• MTMAConfig.userID und alle vier Benutzerkennungsfelder sind optional. Behandeln Sie diese bei der Swift-Integration als optionale Eigenschaften.
• Der bisherige completion-Callback bleibt verfügbar; empfohlen wird resultCompletion. Sind beide gesetzt, wird nur resultCompletion aufgerufen.
• Push RegistrationID und MA RID sind unterschiedliche Geräteidentitäten und dürfen nicht verwechselt werden.