Android MA-Funktionsintegrationshandbuch

Anwendbare Version

Dieser Artikel gilt für die unabhängige Version des MA SDK von 5.5.0 und spätere Versionen.

Ab 5.5.0 ist MA nicht mehr auf AppPush angewiesen und kann unabhängig integriert und initialisiert werden. MA AppKey und Push AppKey sind unabhängig voneinander und können gleich oder unterschiedlich sein.

Informationen zur Integrationsmethode der Fusion-Version vor 5.5.0 finden Sie im Integrationshandbuch vor 5.5.0.

1. SDK importieren

Manueller Import

Fügen Sie mt-sdk-ma-5.5.0.aar im Release-Paket zum Verzeichnis libs des Anwendungsprojekts hinzu:

              
              dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
}

            

Maven-Import

              
              dependencies {
    implementation 'com.engagelab.plugin:oth_ma:5.5.0'
}

            

Wenn Sie gleichzeitig AppPush verwenden, befolgen Sie das AppPush-Dokument, um das Hauptpaket engagelab vorzustellen. Wenn Sie nur MA verwenden, müssen Sie das AppPush-Hauptpaket nicht einführen.

2. Berechtigungskonfiguration

Deklarieren Sie Netzwerkberechtigungen in AndroidManifest.xml:

              
              <uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

            

Die Standalone-Version von MA erfordert keine Konfiguration von ENGAGELAB_PRIVATES_APPKEY, ENGAGELAB_PRIVATES_CHANNEL, Push Service oder Push Receiver. Wenn Sie gleichzeitig AppPush nutzen, müssen Sie noch die entsprechende Konfiguration gemäß dem AppPush-Integrationsdokument durchführen.

3. SDK initialisieren

Es wird empfohlen, den Hauptprozess in Application.onCreate() zu initialisieren. MA AppKey wird für die Initialisierung verwendet und es besteht keine Notwendigkeit, auf die AppPush-Initialisierung oder die erfolgreiche Registrierung zu warten.

              
              import android.app.Application;

import com.engagelab.privates.push.oth.ma.api.MTMAApi;
import com.engagelab.privates.push.oth.ma.api.MTMAConfig;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResult;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResultCallback;

public class MainApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        MTMAApi.configDebugMode(true);
        MTMAConfig config = new MTMAConfig("your MA AppKey");
        // Optional (ab 5.5.2): Soll die Erfassung von der Einwilligung des Nutzers abhängen, übergeben Sie das aktuell in der App gespeicherte Einwilligungsergebnis; true aktiviert, false deaktiviert; standardmäßig aktiviert, wenn noch nie gesetzt
        // config.dataCollectionEnabled(enabled);
        MTMAApi.getInstance(this).start(config, new MTMAInitResultCallback() {
            @Override
            public void onResult(MTMAInitResult result) {
                if (result.isSuccess()) {
                    String euid = result.getEuid();
                    String maRid = result.getMaRid();
                } else {
                    int code = result.getCode();
                    String message = result.getMessage();
                }
            }
        });
    }
}

            

Initialisierungsanweisungen

• MA AppKey erforderlich. – Android MA SDK unterstützt nur die Initialisierung im Hauptprozess der Hostanwendung. Der Aufruf von start in einem Nicht-Hauptprozess führt über den Rückruf zu einem Fehler und es wird keine Netzwerkanforderung initiiert. – Bevor die Initialisierung erfolgreich ist, sind andere MA-Geschäfts-APIs mit Ausnahme der Konfigurationsschnittstelle vor der Initialisierung nicht verfügbar. – Es wird empfohlen, alle externen MA-APIs im Hauptprozess aufzurufen. Nicht-Hauptprozesse teilen nicht den Initialisierungsstatus des Hauptprozesses und Geschäftsanrufe werden nicht an den Hauptprozess weitergeleitet.
• Nach erfolgreicher Initialisierung kann der aktuelle Wert auch über getEuid() und getMaRid() abgerufen werden.

MA AppKey zur Laufzeit wechseln

Der gleiche Prozess unterstützt das Umschalten von MA AppKey zur Laufzeit. Bitte rufen Sie start erneut mit dem neuen AppKey auf, nachdem der letzte Initialisierungsrückruf abgeschlossen ist.

              
              MTMAConfig newConfig = new MTMAConfig("new MA AppKey");
MTMAApi.getInstance(this).start(newConfig, callback);

            

Während der Umstellung sind andere MA-Business-APIs vorübergehend nicht verfügbar; Nachdem der neue AppKey erfolgreich initialisiert wurde, gehören nachfolgende Ereignisse und Benutzerdaten zum neuen AppKey. Wenn die Initialisierung des neuen AppKey fehlschlägt, greift das SDK nicht automatisch auf den alten AppKey zurück und start muss erneut mit einem gültigen AppKey aufgerufen werden.

Benutzer-ID während der Initialisierung festlegen

              
              UserIdentity identity = new UserIdentity();
identity.setUserId("your user id");
identity.setAnonymousId("your anonymous id");
identity.setEmail("user@example.com");
identity.setPhone("+8613800138000");

MTMAConfig config = new MTMAConfig("your MA AppKey", identity);
MTMAApi.getInstance(this).start(config, callback);

            

Darunter werden setEmail und setPhone ab Version 5.5.0 unterstützt.

Regeln für Benutzeridentitätsfelder: Nach dem Entfernen führender und nachfolgender Leerzeichen darf user_id nicht leer sein, höchstens 255 Unicode-Zeichen enthalten und nicht 0, null, undefined oder nan entsprechen (Groß-/Kleinschreibung wird ignoriert). Nach dem Entfernen der Leerzeichen darf anonymous_id nicht leer sein und höchstens 256 Unicode-Zeichen enthalten. email darf nicht leer sein, höchstens 256 Unicode-Zeichen enthalten, muss genau ein @ mit nicht leerem Inhalt auf beiden Seiten enthalten und darf keine Leerzeichen, Zeilenumbrüche oder Tabulatoren enthalten. phone muss dem E.164-Format entsprechen: Es beginnt mit +, der Ländercode beginnt mit einer Ziffer von 1 bis 9, gefolgt von 1–14 Ziffern. Bei fehlgeschlagener Validierung sendet das SDK keine Identitätsanfrage und gibt im Callback code = -3 zurück.

Optional: Erfassung anhand der Einwilligung des Nutzers steuern

Wenn Ihre App die Erfassung abhängig von der Einwilligung des Nutzers steuern muss, verwenden Sie den Datenerfassungsschalter. Andernfalls ist keine Änderung nötig: Die Erfassung ist standardmäßig aktiviert und das Verhalten entspricht dem vor dem Upgrade. Diese Funktion ist ab MA SDK 5.5.2 verfügbar.

Der Schalter wird für jeden MA AppKey getrennt gespeichert. Übergeben Sie dataCollectionEnabled bei der Initialisierung dynamisch anhand des Einwilligungsstatus des Nutzers. Codieren Sie den Wert nicht fest, da sonst jede Initialisierung den Status auf diesen festen Wert zurücksetzt. Ändert der Nutzer seine Auswahl zur Laufzeit, rufen Sie nach erfolgreicher Initialisierung setDataCollectionEnabled auf. Beides erfolgt im Hauptprozess:

              
              // enabled ist der Schalterstatus, den Ihre App anhand der Einwilligung des Nutzers festlegt
MTMAConfig config = new MTMAConfig(maAppKey);
config.dataCollectionEnabled(enabled);
MTMAApi.getInstance(this).start(config, initCallback);

// Wenn der Nutzer seine Auswahl zur Laufzeit ändert
MTMAApi.getInstance(this).setDataCollectionEnabled(enabled);

            

Bei der Integration zu beachten:

• Bei deaktivierter Erfassung werden Ereignisse, Benutzerattribute, UTM und Geräteinformationen nicht mehr erfasst und gemeldet. Initialisierung, Benutzerkennung, Kontaktdaten und Push-Kanäle bleiben verfügbar; das SDK sendet diese notwendigen Anfragen weiterhin.
• Beim Wechsel von aktiviert zu deaktiviert sendet das SDK die vor dem Umschalten erzeugten Daten sofort einmal, bei einem Fehler nicht erneut, und löscht anschließend den lokalen Cache.
• Beim Aufruf von config.dataCollectionEnabled muss true oder false übergeben werden; der Wert gilt bei jedem start: Weicht er vom letzten Status ab, wird dieser Start direkt im neuen Status initialisiert. Wird start bei bereits laufendem SDK erneut aufgerufen und ändert sich der Status, wird einmal die Deaktivierungs- bzw. Aktivierungsverarbeitung ausgeführt.
• Nach dem erneuten Aktivieren nimmt das SDK die Erfassung automatisch wieder auf. Ereignisse, Benutzerattribute und UTM, die vor Abschluss der Wiederherstellung aufgerufen werden, bleiben nicht erhalten.

Schnittstellenparameter, das Verhalten der einzelnen Schnittstellen bei deaktivierter Erfassung und Fehlercodes finden Sie unter Datenerfassungsschalter im API-Leitfaden.

4. Verwenden Sie gleichzeitig AppPush

Wenn Sie die mobile Datenquelle in der MA-Konsole konfigurieren, wählen Sie bitte gleichzeitig die Verwendung von AppPush und wählen Sie die tatsächlich verbundene AppPush-Anwendung aus. Verwenden Sie beim Initialisieren von AppPush den AppKey der ausgewählten App.

MA und AppPush werden separat initialisiert und erfordern keine feste Reihenfolge. Nachdem AppPush erfolgreich registriert und die Push-RID erhalten wurde, bindet MA SDK automatisch den AppPush-Kanal.

AppPush ist nicht integriert, wurde nicht registriert oder die Kanalbindung schlägt fehl, was sich nicht auf die MA-Initialisierung, Ereigniserfassung und Berichterstellung auswirkt.

Hinweis: MA RID und AppPush RID sind zwei unabhängige Gerätekennungen. Bitte besorgen und verwenden Sie sie jeweils über das entsprechende SDK, verwenden Sie nicht das eine wie das andere.

5. Kanalkontakt-ID festlegen

Wenn Sie die Kanalkontakt-ID für einen Push-Kanal eines Drittanbieters festlegen müssen, rufen Sie bitte an, nachdem der MA erfolgreich initialisiert wurde:

              
              List<String> values = Collections.singletonList("push rid or token");
MTMAApi.getInstance(this).setChannelValue(136L, values, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
        // code == 0 means success
    }
});

            

• channelId: Die auf der MA-Konsole konfigurierte Drittanbieter-Push-Kanal-ID muss größer als 0 sein.
• values: Die Werteliste der Kanalkontakt-ID (z. B. RID oder Token) darf nicht leer sein und die Listenelemente dürfen nicht leer sein.
• Nachdem sich die Kanalkontakt-ID geändert hat, muss das Schnittstellenupdate erneut aufgerufen werden.
• Über diese Schnittstelle wird die Kontakt-ID des Drittanbieter-Push-Kanals festgelegt. Der AppPush-Kanal wird automatisch durch das SDK gebunden.

6. Anweisungen zum Upgrade der alten Version

– Nach dem Upgrade auf 5.5.0 muss der MA AppKey explizit mit MTMAConfig übergeben werden.

• Sie müssen nicht mehr auf eine lange AppPush-Verbindung oder eine erfolgreiche Registrierung warten, um MA start anzurufen.
• start(CallBack) und start(UserIdentity, CallBack) sind veraltet. Bitte verwenden Sie start(MTMAConfig, MTMAInitResultCallback) für die Standalone-Version.
• Anwendungen, die ursprünglich AppPush und MA gleichzeitig verwendet haben, können AppPush weiterhin integrieren, müssen jedoch separat initialisiert werden.
• MA RID und AppPush RID sind zwei unabhängige Gerätekennungen. Bitte besorgen und verwenden Sie sie jeweils über das entsprechende SDK, verwenden Sie nicht das eine wie das andere.

Informationen zu anderen Geschäftsschnittstellen finden Sie im API-Leitfaden.