Android SDK API

SDK interface description

• MTMAApi, contains all interfaces of MA functions.

Instructions before calling

• start can only be called in the main process of the host application.
• Except for the configuration interface that is allowed to be set before initialization, other MA business APIs can only be called after successful initialization.
• It is recommended that all MA external APIs be called in the main process. Non-main processes do not share the initialization state of the main process, and calls are not forwarded to the main process.
• When a non-main process calls the business API, the interface with callback returns CODE_START_FAIL (-2), getEuid() and getMaRid() return null value, and the business interface without callback will not be executed.
• configDebugMode, setCollectControl, setReportInterval, setMaxEventCacheCount and setNoActiveSessionEndDurationTime are in-process configurations; calling them in a non-main process will not modify the configuration of the main process MA.

Get SDK version

Supported versions

Starting version supported: 5.5.0

Field definition

• MTMAApi.SDK_VERSION_CODE: MA SDK digital version number.
• MTMAApi.SDK_VERSION_NAME: MA SDK string version number.

              
              int versionCode = MTMAApi.SDK_VERSION_CODE;
String versionName = MTMAApi.SDK_VERSION_NAME;

            

Set debugging mode

Supported versions

Starting version supported: 5.5.0

Interface definition

• configDebugMode(boolean enable)
  • Enable or disable MA SDK debug logs.
  • It is recommended to set it before calling start, and it is recommended to turn it off in the release version.

              
              MTMAApi.configDebugMode(true);

            

Enable MA function

Supported versions

Starting version supported: 5.5.0

Interface definition

• start(MTMAConfig config, MTMAInitResultCallback callback)
  • Interface description: Use MA AppKey to initialize the independent version of MA SDK.
  • config: Initial configuration.
    • MTMAConfig(String appKey): Set MA AppKey.
    • MTMAConfig(String appKey, UserIdentity userIdentity): Set MA AppKey and user ID at the same time.
  • callback: Initialization result callback.
  • MTMAInitResult:
    • isSuccess(): Whether the initialization is successful.
    • getCode(): Result code, 0 indicates success.
    • getMessage(): Result description.
    • getEuid(): EUID obtained after successful initialization.
    • getMaRid(): MA RID obtained after successful initialization.

Call example

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

            

Switch AppKey at runtime

After the last initialization callback is completed, start can be called again with the new MTMAConfig. Other MA business APIs are temporarily unavailable during the switch. There is no automatic fallback to the old AppKey when initialization of the new AppKey fails.

Deprecated interface

Starting with 5.5.0, the following interfaces are deprecated:

• start(CallBack callBack)
• start(UserIdentity userIdentity, CallBack callBack)

Please use start(MTMAConfig config, MTMAInitResultCallback callback) instead.

Set user ID

It is recommended to set this interface when the user logs in and provides relevant information to obtain the EUID matching the user

Supported versions

Starting version supported: 5.0.0

Interface definition

• _setUserIdentity(UserIdentity userIdentity, CallBack callBack) _
  • Interface description: -Set user identification, such as user membership card number.
  • Parameter description:
    • userIdentity: calling identification
      • setUserId(String userId): cannot be empty after removing leading and trailing spaces, up to 255 Unicode characters; cannot be 0, null, undefined, nan (ignoring case)
      • setAnonymousId(String anonymousId): Cannot be empty after removing leading and trailing spaces, up to 256 Unicode characters
      • setEmail(String email): cannot be empty, up to 256 Unicode characters; must contain and can only contain one @, @ cannot be empty before and after, and cannot contain spaces, newlines or Tabs; supported starting from 5.5.0
      • setPhone(String phone): must comply with the E.164 format, starting with +, the first digit of the country code is 1–9, and then contains 1–14 digits; supported starting from 5.5.0
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see message parameter description for details

Call example

              
                              UserIdentity userIdentity = new UserIdentity();
                userIdentity.setUserId("your_user_id");
                userIdentity.setAnonymousId("your_anonymous_id");
                userIdentity.setEmail("user@example.com");
                userIdentity.setPhone("+8613800138000");
                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);
                    }
                });

            

When the user ID field verification fails, no network request is sent, and code = -3 is returned through the callback.

Set user contact information

When the user's contact information changes, you can use this interface to update the user's "contact information".

Supported versions

Starting version supported: 5.0.0

Interface definition

• setUserContact(JSONObject contacts, CallBack callBack)
  • Interface description: -Set the user's "contact information".
  • Parameter description:
    • contacts: Set multiple contact methods. Key is the name of the contact method, and value is the value of the contact method. Currently, four contact methods are supported: email, mobile_phone, landline_phone, and whatsapp_phone.
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see message parameter description for details
    • message: reason description

Call example

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

            

Get EUID

Supported versions

Starting version supported: 5.0.0

Interface definition

• getEuid()
  • Interface description:
    • Get the EUID, which represents the user's unique ID. Only the current value is returned when initialization is successful, and null value is returned in other states.

Call example

              
              MTMAApi.getInstance(this).getEuid();

            

Get MA RID

Supported versions

Starting version supported: 5.5.0

Interface definition

• getMaRid()
  • Get the current MA RID. Only the current value is returned when initialization is successful, and null value is returned in other states.

              
              String maRid = MTMAApi.getInstance(this).getMaRid();

            

Set channel contact ID

Supported versions

Starting version supported: 5.5.0

Interface definition

• setChannelValue(long channelId, List values, CallBack callBack)
  • Interface description: Set channel contact ID. The AppPush channel is automatically bound by the SDK, and there is no need to call this interface setting.
  • Parameter description:
    • channelId: The third-party Push channel ID configured on the MA console must be greater than 0.
    • values: The value list of the channel contact ID (such as RID or Token) cannot be empty, and the list elements cannot be empty.
    • callBack: Result callback, code == 0 indicates success.

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

            

Set reporting data interval

It takes effect together with the setMaxEventCacheCount interface, and it will be reported as long as one of the conditions is met.

Supported versions

Starting version supported: 5.0.0

Interface definition

• setReportInterval(int interval)
  • Interface description:
    • Set the reporting data interval. When this interface is not called, the default is 10 seconds to report event data.
    • Report interval memory cache, which needs to be called in each life cycle of the application to take effect
  • Parameter description
    • interval reporting interval, unit s (seconds)

Call example

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

            

Set the upper limit of event cache

It takes effect together with the setReportInterval interface, and it will be reported as long as one of the conditions is met.

Supported versions

Starting version supported: 5.0.0

Interface definition

• setMaxEventCacheCount(int count)
  • Interface description:
    • Set the upper limit of event cache, the default is 50, the maximum cannot exceed 500
    • When the cache quantity is exceeded, all data will be reported
  • Parameter description
    • count The upper limit of the number of event cache items

Call example

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

            

Set session timeout

Supported versions

Starting version supported: 5.0.0

Interface definition

• setNoActiveSessionEndDurationTime(int duration)
  • Interface description:
    • When the App is placed in the background, the session timeout begins to be calculated. If the set time is exceeded (default 30 minutes), the session will end.
  • Parameter description
    • duration timeout duration, unit s (seconds)

Call example

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

            

Set UTM attributes

Supported versions

Starting version supported: 5.0.0

Interface definition

• setUtmProperties(UtmProperties utmProperties)
  • Interface description:
    • Set the UTM attribute. If the developer can identify which advertisement the user jumps from to access the App, it is recommended to set the UTM information. We will pass this parameter when reporting the event.
  • Parameter description:
    • utmProperties UTM properties object
    • • utm_source campaign source
    • • utm_medium campaign medium
    • • utm_term campaign term
    • • utm_content campaign content
    • • utm_campaign campaign name

Call example

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

            

Data acquisition control

Supported versions

Starting version supported: 5.0.0

Interface definition

• setCollectControl(MTMACollectControl control)
  • Interface description: -Set collection permissions. If you need to turn on/off certain data collection, please call this interface
  • Parameter description:
    • control: Collection permission settings; properties that are not explicitly set use the following default values
      • setCarrier(boolean enable): Whether to collect operator information, enabled by default
      • setMacAddress(boolean enable): Whether to collect MAC address, disabled by default
      • setGAID(boolean enable): Whether to collect GAID, closed by default
      • setOAID(boolean enable): Whether to collect OAID, closed by default
      • setAAID(boolean enable): Whether to collect AAID, closed by default
      • setIMEI(boolean enable): Whether to collect IMEI, turned off by default; only supported by Android 9 and below, the host application needs to declare and obtain READ_PHONE_STATE permission.

Call example

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

            

Set user attributes

Set the value of the user attribute. If the user attribute does not exist, it will be automatically created in the background.

Overwrite and update user attributes

• propertySet(final JSONObject properties, final CallBack callBack)
  • Interface description:
    • Batch overwrite and update user attribute values
    • Only the latest reported data is saved, covering historical data, such as user membership level.
    • Value supports strings, numbers, Boolean values, string arrays, JSONObject, and JSONArray whose elements are all JSONObject.
  • Parameter description:
    • properties: user properties
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see error code description for details
    • message: reason description
  • Call example:

              
              try {JSONObject properties = new JSONObject();
    properties.put("your_property_name","your_property_value");
    properties.put("your_property_name 2","your_property_value 2");
    properties.put("your_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)
  • Interface description:
    • A single override updates the value of a user attribute
    • Only the latest reported data is saved, covering historical data, such as user membership level.
    • Value type rules are consistent with batch propertySet.
  • Parameter description:
    • property: user property name
    • value: user attribute value
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see error code description for details
    • message: reason description
  • Call example:

              
              MTMAApi.getInstance(this).propertySet("your_property_name","your_property_value", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

Update user attributes cumulatively

• propertyIncrease(final Map<String, ? extends Number> properties, CallBack callBack)
  • Interface description:
    • Accumulate the value settings of user attributes and make batch requests
    • Accumulate all reported data, such as accumulated consumption amount.
    • This interface can only be called for user attributes of numeric type, otherwise it will be ignored. If the user attribute does not exist before, the initial value will be treated as 0.
  • Parameter description:
    • properties: user properties
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see error code description for details
    • message: reason description
  • Call example:

              
              Map<String,Number> properties = new HashMap();
properties.put("your_property_name",1);
properties.put("your_property_name 2",2);
properties.put("your_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)
  • Interface description:
    • Accumulate user attribute value settings, single request
    • Accumulate all reported data, such as accumulated consumption amount.
    • This interface can only be called for user attributes of numeric type, otherwise it will be ignored. If the user attribute does not exist before, the initial value will be treated as 0.
  • Parameter description:
    • property: user property name
    • value: user attribute value
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see error code description for details
    • message: reason description
  • Call example:

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

            

###Append user attributes

• propertyAdd(final String property, final String value, CallBack callBack)
  • Interface description:
    • Append the value of user attribute, single request
    • Continuously add elements to the collection, and store the elements in the database for deduplication. If ABC already exists, add CD, and finally it will be ABCD.
  • Parameter description:
    • property: user property name
    • value: user attribute value
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see error code description for details
    • message: reason description
  • Call example:

              
              MTMAApi.getInstance(this).propertyAdd("your_property_name","your_property_value", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

• propertyAdd(final String property, final Set values, CallBack callBack)
  • Interface description:
    • Append the value of the user attribute, adding multiple values at one time
    • Continuously add elements to the collection, and store the elements in the database for deduplication. If ABC already exists, add CD, and finally it will be ABCD.
  • Parameter description:
    • property: user property name
    • value: user attribute value
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see error code description for details
    • message: reason description
  • Call example:

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

            

Manipulate object_array elements

The following interfaces are supported starting from 5.5.0 and are only used for the object_array user attribute. The original propertyAdd, propertyRemove are still used for string arrays and the behavior remains unchanged.

• updateObjectArrayProperty(String property, String identifierKey, Object identifierValue, JSONObject values, CallBack callBack)
  • Update a subfield of an object element based on a unique identifier.
  • identifierValue supports strings or limited numbers; values cannot modify the identification field.
  • Use JSONObject.NULL in values to delete the corresponding subfield.

              
              JSONObject values = new JSONObject().put("enabled", false);
MTMAApi.getInstance(this).updateObjectArrayProperty(
        "devices", "device_id", "device_1", values, callBack);

            

• addObjectArrayProperty(String property, JSONObject object, CallBack callBack)
  • Append a non-null object element to object_array.

              
              JSONObject device = new JSONObject()
        .put("device_id", "device_2")
        .put("year", 2026);
MTMAApi.getInstance(this).addObjectArrayProperty("devices", device, callBack);

            

• removeObjectArrayProperty(String property, String identifierKey, Object identifierValue, CallBack callBack)
  • Remove entire object elements based on unique identifiers.

              
              MTMAApi.getInstance(this).removeObjectArrayProperty(
        "devices", "device_id", "device_2", callBack);

            

Remove user attributes

• propertyRemove(final String property, String values, final CallBack callBack)
  • Interface description:
    • Removed value operations on user attributes.
    • This value is a collection element, and the elements are stored in the database for deduplication processing. If ABCD already exists, delete D, and finally it is ABC.
  • Parameter description:
    • property: user property name
    • value: user attribute value
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see error code description for details
    • message: reason description
  • Call example:

              
              MTMAApi.getInstance(this).propertyRemove("your_property_name","your_property_value", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

• propertyRemove(final String property, Set values, final CallBack callBack)
  • Interface description:
    • Remove the value of user attributes and remove multiple values at one time.
    • This value is a collection element, and the elements are stored in the database for deduplication processing. If ABCD already exists, CD is deleted, and finally it is AB.
  • Parameter description:
    • property: user property name
    • value: user attribute value
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see error code description for details
    • message: reason description
  • Call example:

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

            

Delete user attributes

Supported versions

Starting version supported: 5.0.0

Interface definition

• propertyDelete(final String property, final CallBack callBack)
  • Interface description:
    • Delete all value values for a user attribute
  • Parameter description:
    • property: user property name
    • callBack: interface callback
  • Return description:
    onCallBack(int code, String message)
    • code: return code, 0 represents success, -1 represents failure, see error code description for details
    • message: reason description

Call example

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

            

Incident reporting

Supported versions

Starting version supported: 5.0.0

Interface definition

• onEvent(String eventKey, JSONObject properties)
  • Interface description:
    • Incident reporting
  • Parameter description:
    • eventKey: event name
    • properties: event properties, Key is the property name, value is the property value

Call example

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

            

Error code