Guide d'intégration des fonctions Android MA

Version applicable

Cet article s'applique à la version indépendante du SDK MA de 5.5.0 et aux versions ultérieures.

À partir de la version 5.5.0, MA ne s'appuie plus sur AppPush et peut être intégré et initialisé indépendamment. MA AppKey et Push AppKey sont indépendants l'un de l'autre et peuvent être identiques ou différents.

Pour la méthode d'intégration de la version Fusion antérieure à 5.5.0, veuillez consulter le Guide d'intégration avant 5.5.0.

1. Importer le SDK

Importation manuelle

Ajoutez mt-sdk-ma-5.5.0.aar dans le package de version au répertoire libs du projet d'application :

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

            

Importation Maven

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

            

Si vous utilisez AppPush en même temps, suivez le document AppPush pour présenter le package principal engagelab ; lorsque vous utilisez MA uniquement, vous n'avez pas besoin d'introduire le package principal AppPush.

2. Configuration des autorisations

Déclarez les autorisations réseau dans AndroidManifest.xml :

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

            

La version autonome de MA ne nécessite pas de configuration de ENGAGELAB_PRIVATES_APPKEY, ENGAGELAB_PRIVATES_CHANNEL, Push Service ou Push Receiver. Si vous utilisez AppPush en même temps, vous devez toujours effectuer la configuration correspondante conformément au document d'intégration AppPush.

3. Initialiser le SDK

Il est recommandé d'initialiser dans Application.onCreate() du processus principal. MA AppKey est utilisé pour l'initialisation et il n'est pas nécessaire d'attendre l'initialisation d'AppPush ou l'enregistrement réussi.

              
              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");
        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();
                }
            }
        });
    }
}

            

Instructions d'initialisation

• MA AppKey requise.
• Le SDK Android MA prend uniquement en charge l'initialisation dans le processus principal de l'application hôte. L’appel de start dans un processus non principal renverra un échec via le rappel et aucune demande réseau ne sera lancée.
• Avant que l'initialisation ne réussisse, les autres API métier MA ne sont pas disponibles, à l'exception de l'interface de configuration de pré-initialisation.
• Il est recommandé que toutes les API externes MA soient appelées dans le processus principal. Les processus non principaux ne partageront pas le statut d'initialisation du processus principal et les appels professionnels ne seront pas transmis au processus principal.
• Après une initialisation réussie, la valeur actuelle peut également être obtenue via getEuid() et getMaRid().

Changer MA AppKey au moment de l'exécution

Le même processus prend en charge le changement de MA AppKey au moment de l'exécution. Veuillez appeler à nouveau start avec la nouvelle AppKey une fois le dernier rappel d'initialisation terminé.

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

            

Pendant le changement, les autres API métier MA sont temporairement indisponibles ; une fois la nouvelle AppKey initialisée avec succès, les événements ultérieurs et les données utilisateur appartiennent à la nouvelle AppKey. Si la nouvelle AppKey ne parvient pas à s'initialiser, le SDK ne reviendra pas automatiquement à l'ancienne AppKey et start doit être appelé à nouveau avec une AppKey valide.

Définir l'ID utilisateur lors de l'initialisation

              
              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);

            

Parmi eux, setEmail et setPhone sont pris en charge à partir de la version 5.5.0.

Règles des champs d’identité utilisateur : après suppression des espaces de début et de fin, user_id ne doit pas être vide, ne doit pas dépasser 255 caractères Unicode et ne doit pas être égal à 0, null, undefined ou nan (sans tenir compte de la casse). Après suppression des espaces, anonymous_id ne doit pas être vide et ne doit pas dépasser 256 caractères Unicode. email ne doit pas être vide, ne doit pas dépasser 256 caractères Unicode, doit contenir exactement un @ avec du contenu non vide de chaque côté et ne doit contenir ni espace, ni saut de ligne, ni tabulation. phone doit respecter le format E.164 : il commence par +, le code pays commence par un chiffre de 1 à 9, suivi de 1 à 14 chiffres. Si la validation échoue, le SDK n’envoie aucune requête d’identité et renvoie code = -3 via le callback.

4. Utilisez AppPush en même temps

Lors de la configuration de la source de données mobiles dans la console MA, veuillez choisir d'utiliser AppPush en même temps et sélectionnez l'application AppPush qui est réellement connectée. Lors de l'initialisation d'AppPush, utilisez l'AppKey de l'application sélectionnée.

MA et AppPush sont initialisés séparément et ne nécessitent pas d'ordre fixe. Une fois AppPush enregistré avec succès et le Push RID obtenu, MA SDK liera automatiquement le canal AppPush.

AppPush n'est pas intégré, n'a pas été enregistré ou la liaison de canal échoue, ce qui n'affecte pas l'initialisation de MA, la collecte d'événements et la création de rapports.

Remarque : MA RID et AppPush RID sont deux identifiants de périphérique indépendants. Veuillez les obtenir et les utiliser via le SDK correspondant respectivement, ne pas utiliser l'un comme l'autre.

5. Définir l'ID du contact de la chaîne

Si vous devez définir l'ID de contact du canal pour un canal Push tiers, veuillez appeler une fois le MA initialisé avec succès :

              
              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 : l'ID du canal Push tiers configuré sur la console MA doit être supérieur à 0.
• values : la liste de valeurs de l'ID de contact du canal (tel que RID ou Token) ne peut pas être vide, et les éléments de la liste ne peuvent pas être vides.
• Une fois l'ID de contact du canal modifié, la mise à jour de l'interface doit être rappelée.
• Cette interface est utilisée pour définir l'ID de contact du canal Push tiers ; le canal AppPush est automatiquement lié par le SDK.

6. Instructions de mise à niveau de l'ancienne version

• Après la mise à niveau vers 5.5.0, la MA AppKey doit être transmise explicitement à l'aide de MTMAConfig.
• Plus besoin d'attendre une longue connexion AppPush ou une inscription réussie pour appeler MA start.
• start(CallBack) et start(UserIdentity, CallBack) sont obsolètes, veuillez utiliser start(MTMAConfig, MTMAInitResultCallback) pour la version autonome.
• Les applications qui utilisaient initialement AppPush et MA en même temps peuvent continuer à intégrer AppPush, mais elles doivent être initialisées séparément.
• MA RID et AppPush RID sont deux identifiants d'appareil indépendants. Veuillez les obtenir et les utiliser via le SDK correspondant respectivement, ne pas utiliser l'un comme l'autre.

Pour les autres interfaces métier, veuillez consulter le Guide API.