Guía de integración de funciones de Android MA

Versión aplicable

Este artículo se aplica a la versión independiente de MA SDK de 5.5.0 y versiones posteriores.

A partir de 5.5.0, MA ya no depende de AppPush y puede integrarse e inicializarse de forma independiente. MA AppKey y Push AppKey son independientes entre sí y pueden ser iguales o diferentes.

Para conocer el método de integración de la versión Fusion anterior a 5.5.0, consulte la Guía de integración anterior a 5.5.0.

1. Importar SDK

Importación manual

Agregue mt-sdk-ma-5.5.0.aar en el paquete de lanzamiento al directorio libs del proyecto de aplicación:

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

            

Importación de Maven

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

            

Si usa AppPush al mismo tiempo, siga el documento de AppPush para presentar el paquete principal engagelab; cuando usa MA únicamente, no necesita introducir el paquete principal de AppPush.

2. Configuración de permisos

Declare permisos de red en AndroidManifest.xml:

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

            

La versión independiente de MA no requiere configuración de ENGAGELAB_PRIVATES_APPKEY, ENGAGELAB_PRIVATES_CHANNEL, Push Service o Push Receiver. Si usa AppPush al mismo tiempo, aún debe completar la configuración correspondiente de acuerdo con el documento de integración de AppPush.

3. Inicializar SDK

Se recomienda inicializar en Application.onCreate() del proceso principal. MA AppKey se utiliza para la inicialización y no es necesario esperar a que AppPush se inicialice o se registre correctamente.

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

            

Instrucciones de inicialización

• Se requiere MA AppKey.
• Android MA SDK solo admite la inicialización en el proceso principal de la aplicación host. Llamar a start en un proceso no principal devolverá un error a través de la devolución de llamada y no se iniciará ninguna solicitud de red.
• Antes de que la inicialización sea exitosa, otras API comerciales de MA no están disponibles excepto la interfaz de configuración previa a la inicialización.
• Se recomienda llamar a todas las API externas de MA en el proceso principal. Los procesos no principales no compartirán el estado de inicialización del proceso principal y las llamadas comerciales no se reenviarán al proceso principal.
• Después de una inicialización exitosa, el valor actual también se puede obtener a través de getEuid() y getMaRid().

Cambiar MA AppKey en tiempo de ejecución

El mismo proceso admite el cambio de MA AppKey en tiempo de ejecución. Llame nuevamente a start con la nueva AppKey después de que se complete la última devolución de llamada de inicialización.

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

            

Durante el cambio, otras API empresariales de MA no estarán disponibles temporalmente; Una vez que la nueva AppKey se inicializa correctamente, los eventos posteriores y los datos del usuario pertenecen a la nueva AppKey. Si la nueva AppKey no se inicializa, el SDK no recurrirá automáticamente a la AppKey anterior y será necesario volver a llamar a start con una AppKey válida.

Establecer ID de usuario durante la inicialización

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

            

Entre ellos, setEmail y setPhone son compatibles a partir de la versión 5.5.0.

Reglas de los campos de identidad del usuario: después de eliminar los espacios iniciales y finales, user_id no puede estar vacío, debe tener como máximo 255 caracteres Unicode y no puede ser 0, null, undefined ni nan (sin distinguir mayúsculas y minúsculas). Después de eliminar los espacios, anonymous_id no puede estar vacío y debe tener como máximo 256 caracteres Unicode. email no puede estar vacío, debe tener como máximo 256 caracteres Unicode, debe contener exactamente un @ con contenido no vacío a ambos lados y no puede contener espacios, saltos de línea ni tabulaciones. phone debe usar el formato E.164: comienza con +, el código de país comienza con un dígito del 1 al 9, seguido de 1–14 dígitos. Si la validación falla, el SDK no envía una solicitud de identidad y devuelve code = -3 mediante el callback.

4. Utilice AppPush al mismo tiempo

Al configurar la fuente de datos móviles en la consola MA, elija usar AppPush al mismo tiempo y seleccione la aplicación AppPush que realmente está conectada. Al inicializar AppPush, use la AppKey de la aplicación seleccionada.

MA y AppPush se inicializan por separado y no requieren un orden fijo. Después de que AppPush se registre exitosamente y se obtenga Push RID, MA SDK vinculará automáticamente el canal AppPush.

AppPush no está integrado, no se ha registrado o falla el enlace del canal, lo que no afecta la inicialización de MA, la recopilación de eventos ni los informes.

Nota: MA RID y AppPush RID son dos identificadores de dispositivos independientes. Consígalos y utilícelos a través del SDK correspondiente respectivamente, no utilice uno como el otro.

5. Establecer ID de contacto del canal

Si necesita configurar el ID de contacto del canal para un canal Push de terceros, llame después de que el MA se haya inicializado correctamente:

              
              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: el ID del canal Push de terceros configurado en la consola MA debe ser mayor que 0.
• values: La lista de valores del ID de contacto del canal (como RID o Token) no puede estar vacía y los elementos de la lista no pueden estar vacíos.
• Después de que cambia el ID de contacto del canal, es necesario volver a llamar a la actualización de la interfaz.
• Esta interfaz se utiliza para configurar el ID de contacto del canal Push de terceros; el canal AppPush está vinculado automáticamente al SDK.

6. Instrucciones de actualización de la versión anterior

• Después de actualizar a 5.5.0, la MA AppKey se debe pasar explícitamente usando MTMAConfig.
• Ya no es necesario esperar una conexión larga de AppPush o un registro exitoso para llamar a MA start.
• start(CallBack) y start(UserIdentity, CallBack) están obsoletos; utilice start(MTMAConfig, MTMAInitResultCallback) para la versión independiente.
• Las aplicaciones que originalmente usaban AppPush y MA al mismo tiempo pueden continuar integrando AppPush, pero deben inicializarse por separado.
• MA RID y AppPush RID son dos identificadores de dispositivos independientes. Consígalos y utilícelos a través del SDK correspondiente respectivamente, no utilice uno como el otro.

Para otras interfaces comerciales, consulte la Guía API.