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");
        // Opcional (a partir de 5.5.2): si necesita controlar la recopilación según el consentimiento del usuario, pase el resultado de consentimiento que su aplicación tiene registrado; true activa, false desactiva; si nunca se ha establecido, está activado de forma predeterminada
        // 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();
                }
            }
        });
    }
}

            

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.

Opcional: controlar la recopilación según el consentimiento del usuario

Si su aplicación necesita controlar la recopilación según el consentimiento del usuario, utilice el interruptor de recopilación de datos. Si no lo necesita, no tiene que cambiar nada: la recopilación está activada de forma predeterminada y el comportamiento es el mismo que antes de la actualización. Esta capacidad está disponible a partir de MA SDK 5.5.2.

El interruptor se guarda por separado para cada MA AppKey. En la inicialización, pase dataCollectionEnabled de forma dinámica según el estado de consentimiento del usuario. No lo fije en el código, ya que cada inicialización restablecería el estado a ese valor fijo. Cuando el usuario cambie su elección durante la ejecución, llame a setDataCollectionEnabled después de que la inicialización se complete correctamente. Ambas llamadas deben hacerse en el proceso principal:

              
              // enabled es el estado del interruptor que su aplicación decide según el consentimiento del usuario
MTMAConfig config = new MTMAConfig(maAppKey);
config.dataCollectionEnabled(enabled);
MTMAApi.getInstance(this).start(config, initCallback);

// Cuando el usuario cambia su elección durante la ejecución
MTMAApi.getInstance(this).setDataCollectionEnabled(enabled);

            

Aspectos a tener en cuenta en la integración:

• Mientras está desactivado, dejan de recopilarse e informarse los eventos, atributos de usuario, UTM e información del dispositivo. La inicialización, la identificación del usuario, los datos de contacto y los canales push siguen disponibles, y el SDK continúa enviando estas solicitudes necesarias.
• Al pasar de activado a desactivado, el SDK envía una vez de inmediato los datos generados antes del cambio, sin reintentos si falla, y después borra la caché local.
• Al llamar a config.dataCollectionEnabled debe pasar true o false, y el valor se aplica en cada start: si difiere del estado anterior, este inicio se inicializa directamente con el nuevo estado; si se vuelve a llamar a start con el SDK ya iniciado y el estado cambia, se ejecuta una vez el procesamiento de desactivación o de activación.
• Tras volver a activarla, el SDK reanuda la recopilación automáticamente. Los eventos, atributos de usuario y UTM llamados antes de que termine la recuperación no se conservan.

Para los parámetros de las interfaces, su comportamiento mientras está desactivado y los códigos de error, consulte Interruptor de recopilación de datos en la Guía API.

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.