API del SDK de Android

Descripción de la interfaz del SDK

• MTMAApi, que contiene todas las interfaces relacionadas con la funcionalidad MA del SDK.

Habilitar la funcionalidad MA

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• start(UserIdentity userIdentity, CallBack callBack)
  • Descripción de la interfaz:
    • Iniciar el uso de la funcionalidad MA. Al habilitarla, se puede establecer simultáneamente la información de identificación del usuario.
  • Descripción de parámetros:
    • userIdentity: La identificación de la llamada; se puede establecer en null si no existe.
      • setUserId(String userId): userId, establecer aquí el identificador único del usuario que ha iniciado sesión.
      • setAnonymousId(String anonymousId): anonymousId. Cuando el usuario no ha iniciado sesión pero proporciona otra información identificable, se puede establecer como ID anónimo, por ejemplo, una dirección de correo electrónico o un ID generado por un tercero.
    • callBack: La devolución de llamada (callback) de los datos del resultado.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del parámetro message para obtener más detalles.
    • message: La descripción del motivo.

Ejemplo de llamada

              
                              MTMAApi.getInstance(this).start(new CallBack() {
                    @Override
                    public void onCallBack(int code, String message) {
                        Log.e(TAG, "start code:" + code);
                        Log.e(TAG, "startmessage:" + message);

                    }
                });

            

Establecer la identificación del usuario

Se recomienda establecer esta interfaz cuando el usuario inicie sesión o proporcione información relevante, con el fin de obtener el EUID que coincida con el usuario.

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• _setUserIdentity(UserIdentity userIdentity, CallBack callBack) _
  • Descripción de la interfaz:
    • Establecer la identificación del usuario, como el número de tarjeta de socio del usuario.
  • Descripción de parámetros:
    • userIdentity: La identificación de la llamada.
      • setUserId(String userId): userId, establecer aquí el identificador único del usuario que ha iniciado sesión.
      • setAnonymousId(String anonymousId): anonymousId. Cuando el usuario no ha iniciado sesión pero proporciona otra información identificable, se puede establecer como ID anónimo, por ejemplo, una dirección de correo electrónico o un ID generado por un tercero.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del parámetro message para obtener más detalles.

Ejemplo de llamada

              
                              UserIdentity userIdentity = new UserIdentity();
                userIdentity.setUserId("Your userId");
                userIdentity.setAnonymousId("Your AnonymousId");
                MTMAApi.getInstance(this).setUserIdentity(userIdentity, new CallBack() {
                    @Override
                    public void onCallBack(int code, String message) {
                        MTCommonLog.e(TAG, "setUserIdentity code:" + code);
                        MTCommonLog.e(TAG, "setUserIdentity message:" + message);
                    }
                });

            

Establecer la información de contacto del usuario

Cuando cambie la información de contacto del usuario, esta interfaz se puede utilizar para actualizar los «datos de contacto» del usuario.

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• setUserContact(JSONObject contacts, CallBack callBack)
  • Descripción de la interfaz:
    • Establecer la «información de contacto» del usuario.
  • Descripción de parámetros:
    • contacts: Establecer múltiples datos de contacto. La clave es el nombre del dato de contacto y el valor es el valor del dato de contacto. Actualmente se admiten 4 tipos de datos de contacto: email, mobile_phone, landline_phone y whatsapp_phone.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del parámetro message para obtener más detalles.
    • message: La descripción del motivo.

Ejemplo de llamada

              
                              JSONObject contacts = new JSONObject();
                try {
                    contacts.put("key1", "cc");
                    contacts.put("key2", "dd");
                } catch (JSONException e) {
                    e.printStackTrace();
                }
                MTMAApi.getInstance(this).setUserContact(contacts, new CallBack() {
                    @Override
                    public void onCallBack(int code, String message) {
                        Log.e(TAG, "setUserContact code:" + code);
                        Log.e(TAG, "setUserContact message:" + message);
                    }
                });

            

Obtener EUID

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• getEuid()
  • Descripción de la interfaz:
    • Obtener el EUID, que representa el ID único del usuario.

Ejemplo de llamada

              
              MTMAApi.getInstance(this).getEuid();

            

Establecer el intervalo de envío de los datos cargados

Funciona junto con la interfaz setMaxEventCacheCount. Se realizará el envío en cuanto se cumpla cualquiera de las condiciones.

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• setReportInterval(int interval)
  • Descripción de la interfaz:
    • Establecer el intervalo de envío de los datos cargados. Si no se llama a esta interfaz, los datos de eventos se envían de forma predeterminada una vez cada 10 segundos.
    • El intervalo de envío se almacena en caché en memoria y es necesario llamarlo en cada ciclo de vida de la aplicación para que surta efecto.
  • Descripción de parámetros
    • interval: El intervalo de envío, en s (segundos).

Ejemplo de llamada

              
                  MTMAApi.getInstance(this).setReportInterval(10);

            

Establecer el límite superior de entradas de caché de eventos

Surte efecto junto con la interfaz setReportInterval. Se realizará el envío en cuanto se cumpla cualquiera de las condiciones.

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• setMaxEventCacheCount(int count)
  • Descripción de la interfaz:
    • Establecer el límite superior del número de entradas de caché de eventos, que es 50 de forma predeterminada y no puede superar 500 como máximo.
    • Cuando se supera la cantidad en caché, se enviarán todos los datos.
  • Descripción de parámetros
    • count: El límite superior del número de entradas de caché de eventos.

Ejemplo de llamada

              
                  MTMAApi.getInstance(this).setMaxEventCacheCount(50);

            

Establecer el tiempo de espera de la sesión

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• setNoActiveSessionEndDurationTime(int duration)
  • Descripción de la interfaz:
    • Cuando la App pasa a segundo plano, se empieza a calcular el tiempo de espera de la sesión. Al superar el tiempo establecido (30 minutos de forma predeterminada), esta sesión finalizará.
  • Descripción de parámetros
    • duration: La duración del tiempo de espera, en s (segundos).

Ejemplo de llamada

              
                  MTMAApi.getInstance(this).setNoActiveSessionEndDurationTime(5*60);

            

Establecer propiedades UTM

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• setUtmProperties(UtmProperties utmProperties)
  • Descripción de la interfaz:
    • Establecer las propiedades UTM. Si los desarrolladores pueden identificar desde qué anuncio accedió el usuario a la App, se recomienda configurar la información UTM, y este parámetro se enviará al envío de eventos.
  • Descripción de parámetros:
    • utmProperties: El objeto de propiedades UTM.
    • • utm_source: El origen de la campaña publicitaria.
    • • utm_medium: El medio de la campaña publicitaria.
    • • utm_term: El término de la campaña publicitaria.
    • • utm_content: El contenido de la campaña publicitaria.
    • • utm_campaign: El nombre de la campaña publicitaria.

Ejemplo de llamada

              
                              UtmProperties utmProperties = new UtmProperties();
                utmProperties.setUtmSource("Your utm_source");
                utmProperties.setUtmCampaign("Your utm_campaign");
                utmProperties.setUtmContent("Your utm_content");
                utmProperties.setUtmId("Your utm_id" );
                utmProperties.setUtmMedium("Your utm_medium");
                utmProperties.setUtmTerm("Your utm_term");
                MTMAApi.getInstance(this).setUtmProperties(utmProperties);

            

Establecer el permiso de recopilación

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• setCollectControl(MTMACollectControl control)
  • Descripción de la interfaz:
    • Establecer el permiso de recopilación. Si es necesario habilitar o deshabilitar la recopilación de determinados datos, se debe llamar a esta interfaz.
  • Descripción de parámetros:
    • control: La configuración de permisos, habilitada de forma predeterminada.

Ejemplo de llamada

              
              try {
MTMACollectControl mtmaCollectControl = new MTMACollectControl();
        mtmaCollectControl.setIMEI(true);
        mtmaCollectControl.setAAID(true);
    MTMAApi.getInstance(this).setCollectControl(mtmaCollectControl);
} catch (Throwable e) {
    e.printStackTrace();
}

            

Establecer propiedades de usuario

Establecer el valor de las propiedades de usuario. Si las propiedades de usuario no existen, se crearán automáticamente en segundo plano.

Sobrescribir y actualizar propiedades de usuario

• propertySet(final JSONObject properties, final CallBack callBack)
  • Descripción de la interfaz:
    • Actualizar por lotes los valores de las propiedades de usuario mediante sobrescritura.
    • Solo se guarda la última información enviada, sobrescribiendo los datos históricos, como el nivel de membresía del usuario.
  • Descripción de parámetros:
    • properties: Propiedades de usuario.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del código de error para obtener más detalles.
    • message: La descripción del motivo.
  • Ejemplo de llamada:

              
              try {
    JSONObject properties = new JSONObject();
    properties.put("Your user property name", "Your property value");
    properties.put("Your user property name 2", "Your property value 2");
    properties.put("Your user property name 3", "Your property value 3");
    MTMAApi.getInstance(this).propertySet(properties, new CallBack() {
        @Override
        public void onCallBack(int code, String message) {
        }
    });
} catch (Throwable e) {
    e.printStackTrace();
}

            

• propertySet(String property, Object value, CallBack callBack)
  • Descripción de la interfaz:
    • Actualizar el valor de una única propiedad de usuario mediante sobrescritura.
    • Solo se guarda la última información enviada, sobrescribiendo los datos históricos, como el nivel de membresía del usuario.
  • Descripción de parámetros:
    • property: El nombre de la propiedad de usuario.
    • value: El valor de la propiedad de usuario.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del código de error para obtener más detalles.
    • message: La descripción del motivo.
  • Ejemplo de llamada:

              
              MTMAApi.getInstance(this).propertySet("Your user property name", "Your property value", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

Incrementar y actualizar propiedades de usuario

• propertyIncrease(final Map<String, ? extends Number> properties, CallBack callBack)
  • Descripción de la interfaz:
    • Establecer un incremento para los valores de propiedades de usuario, para solicitudes por lotes.
    • Acumular todos los datos enviados, como el importe de consumo acumulado.
    • Esta interfaz solo se puede llamar para propiedades de usuario de tipo numérico; de lo contrario, se ignorará. Si esta propiedad de usuario no existía previamente, el valor inicial se trata como 0.
  • Descripción de parámetros:
    • properties: Propiedades de usuario.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del código de error para obtener más detalles.
    • message: La descripción del motivo.
  • Ejemplo de llamada:

              
              Map<String, Number> properties = new HashMap<>();
properties.put("Your user property name", 1);
properties.put("Your user property name 2", 2);
properties.put("Your user property name 3", 3);
MTMAApi.getInstance(this).propertyIncrease(properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

• propertyIncrease(final String property, final Number value, CallBack callBack)
  • Descripción de la interfaz:
    • Establecer un incremento para el valor de una propiedad de usuario, para una única solicitud.
    • Acumular todos los datos enviados, como el importe de consumo acumulado.
    • Esta interfaz solo se puede llamar para propiedades de usuario de tipo numérico; de lo contrario, se ignorará. Si esta propiedad de usuario no existía previamente, el valor inicial se trata como 0.
  • Descripción de parámetros:
    • property: El nombre de la propiedad de usuario.
    • value: El valor de la propiedad de usuario.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del código de error para obtener más detalles.
    • message: La descripción del motivo.
  • Ejemplo de llamada:

              
              MTMAApi.getInstance(this).propertyIncrease("Your user property name", 1, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

Anexar propiedades de usuario

• propertyAdd(final String property, final String value, CallBack callBack)
  • Descripción de la interfaz:
    • Anexar un valor al valor de una propiedad de usuario, para una única solicitud.
    • Los elementos de este conjunto se pueden añadir de forma continua, y los elementos duplicados se eliminan al almacenarse en la base de datos. Si ya existe ABC y se anexa CD, el resultado final será ABCD.
  • Descripción de parámetros:
    • property: El nombre de la propiedad de usuario.
    • value: El valor de la propiedad de usuario.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del código de error para obtener más detalles.
    • message: La descripción del motivo.
  • Ejemplo de llamada:

              
              MTMAApi.getInstance(this).propertyAdd("Your user property name", "Your user property value", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

• propertyAdd(final String property, final Set values, CallBack callBack)
  • Descripción de la interfaz:
    • Anexar valores al valor de una propiedad de usuario, añadiendo varios valores a la vez.
    • Los elementos de este conjunto se pueden añadir de forma continua, y los elementos duplicados se eliminan al almacenarse en la base de datos. Si ya existe ABC y se anexa CD, el resultado final será ABCD.
  • Descripción de parámetros:
    • property: El nombre de la propiedad de usuario.
    • value: El valor de la propiedad de usuario.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del código de error para obtener más detalles.
    • message: La descripción del motivo.
  • Ejemplo de llamada:

              
              Set<String> properties = new HashSet<>();
properties.add("Your user property value");
properties.add("Your user property value 2");
properties.add("Your user property value 3");
MTMAApi.getInstance(this).propertyAdd("Your user property name", properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

Eliminar propiedades de usuario

• propertyRemove(final String property, String values, final CallBack callBack)
  • Descripción de la interfaz:
    • Eliminar el valor de una propiedad de usuario.
    • Este valor es un elemento del conjunto, y los elementos duplicados se eliminan al almacenarse en la base de datos. Si ya existe ABCD y se elimina D, el resultado final será ABC.
  • Descripción de parámetros:
    • property: El nombre de la propiedad de usuario.
    • value: El valor de la propiedad de usuario.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del código de error para obtener más detalles.
    • message: La descripción del motivo.
  • Ejemplo de llamada:

              
              MTMAApi.getInstance(this).propertyRemove("Your user property name", "Your user property value", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

• propertyRemove(final String property, Set values, final CallBack callBack)
  • Descripción de la interfaz:
    • Eliminar varios valores de una propiedad de usuario a la vez.
    • Estos valores son elementos del conjunto, y los elementos duplicados se eliminan al almacenarse en la base de datos. Si ya existe ABCD y se eliminan CD, el resultado final será AB.
  • Descripción de parámetros:
    • property: El nombre de la propiedad de usuario.
    • value: El valor de la propiedad de usuario.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del código de error para obtener más detalles.
    • message: La descripción del motivo.
  • Ejemplo de llamada:

              
              Set<String> properties = new HashSet<>();
properties.add("Your user property value");
properties.add("Your user property value 2");
properties.add("Your user property value 3");
MTMAApi.getInstance(this).propertyRemove("Your user property name", properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

Borrar propiedades de usuario

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• propertyDelete(final String property, final CallBack callBack)
  • Descripción de la interfaz:
    • Eliminar todos los valores de una determinada propiedad de usuario.
  • Descripción de parámetros:
    • property: El nombre de la propiedad de usuario.
    • callBack: La devolución de llamada (callback) de la interfaz.
  • Descripción de retorno:
    onCallBack(int code, String message)
    • code: El código de retorno. 0 representa una adquisición correcta y -1 representa un fallo. Consultar la descripción del código de error para obtener más detalles.
    • message: La descripción del motivo.

Ejemplo de llamada

              
              MTMAApi.getInstance(this).propertyDelete("Your user property name", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

Envío de eventos personalizados

Versiones compatibles

Compatible a partir de la versión 5.0.0

Definición de la interfaz

• onEvent(String eventKey, JSONObject properties)
  • Descripción de la interfaz:
    • Enviar un evento personalizado.
  • Descripción de parámetros:
    • eventKey: El nombre del evento.
    • properties: Las propiedades del evento. La clave es el nombre de la propiedad y el valor es el valor de la propiedad.

Ejemplo de llamada

              
              JSONObject properties = new JSONObject();
properties.put("key1", "v1");
properties.put("key2", "v2");
MTMAApi.getInstance(this).onEvent("Your event name", properties);

            

Códigos de error: