Android SDK API

SDK interface description

• MTMAApi: the MA runtime interface.
• MTMAConfig: the initialization configuration passed to start.

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: Initialization configuration, of type MTMAConfig.
    • MTMAConfig(String appKey): Set MA AppKey.
    • MTMAConfig(String appKey, UserIdentity userIdentity): Set MA AppKey and user ID at the same time.
    • config.dataCollectionEnabled(boolean enabled): Optional. Called on the MTMAConfig object to set the data collection switch of the current MA AppKey for this start call. Supported since 5.5.2.
      • true enables collection and false disables it. Once called, the value passed in takes effect on every start and is saved on the device. Pass the user's current consent result instead of hard-coding a fixed value.
      • See Data Collection Switch.
  • 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");
// Optional (supported since 5.5.2): set the data collection switch based on the user's current consent; enabled by default if it has never been set
// 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();
        }
    }
});

            

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
    • utm_id campaign ID

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 Collection Switch

Supported versions

Starting version supported: 5.5.2

If your app needs to control collection based on user consent, use the data collection switch. If not, no change is required: collection is enabled by default and the SDK behaves the same as before the upgrade.

The switch is saved separately for each MA AppKey. At initialization, pass dataCollectionEnabled dynamically based on the user's consent status. Do not hard-code it, otherwise every initialization resets the state to the hard-coded value. When the user changes their choice at runtime, call setDataCollectionEnabled after initialization succeeds. Both must be called in the main process.

Set the Data Collection Switch

Interface definition

• setDataCollectionEnabled(boolean enabled)
  • Interface description:
    • Sets the data collection switch of the current MA AppKey. Call it in the main process after initialization succeeds.
    • Takes effect immediately and is saved on the device, without waiting for any network request to complete.
    • If the value is the same as the current state, the disable or recovery handling is not run again, and launch and session statistics are not affected.
    • After collection is re-enabled, the SDK resumes collection automatically. Events, user properties, and UTM set before recovery completes are not kept, and APIs with a callback return -2.
    • For how each API behaves after collection is disabled, see Behavior While Disabled.
  • Parameter description:
    • enabled: true to enable, false to disable.

Call example

              
              // enabled is the switch state your app decides based on the user's consent
MTMAApi.getInstance(this).setDataCollectionEnabled(enabled);

            

Query the Data Collection Switch

Interface definition

• isDataCollectionEnabled()
  • Interface description:
    • Queries the data collection switch of the current MA AppKey. It sends no network request and does not trigger switching or recovery.
  • Return description:
    • true means enabled and false means disabled.
    • Before start, when no AppKey has been determined: returns the default value true, which does not represent the state of any AppKey. Query it after start.
    • In a non-main process it returns false, which only means that the process does not collect data and does not represent the switch state of the main process.

Call example

              
              boolean enabled = MTMAApi.getInstance(this).isDataCollectionEnabled();

            

Behavior While Disabled

Stopped while disabled

Still available while disabled

When collection is disabled

• Data generated before the switch is sent once immediately, without retry on failure, and the local cache is then cleared.
• Data that has already been reported is not deleted.

Requests still sent while disabled

• Initialization, identity registration (without device characteristics), configuration fetch, push channel binding, and switch state synchronization.

Push and messages

• Push notifications are delivered as usual and can open the app.
• MA events such as push click are not generated, so journey conditions that depend on MA behavior events are not met.
• Clicks on push notifications or in-app messages are not counted as MA message conversions. Click records from before collection was disabled are cleared and are not attributed after it is re-enabled.

Not controlled by this switch

• Delivery and click receipts of the push channel itself.
• Reporting by a separately integrated AppPush SDK.
• MA REST APIs called by your app's backend.
• This switch does not replace push unsubscription.

Console and segments

• User details show the “Data Collection” status, which is the value most recently synchronized to the server and may be delayed. It is empty under an AppKey for which the switch has never been set.
• In segments, you can select users by “Data Collection = Disabled”: a user matches if any device is disabled; devices that have not reported a state do not match.

Data acquisition control

setCollectControl sets collection permission for specific device fields. To stop event, user property, UTM, and device collection as a whole, use the Data Collection Switch. After overall collection is re-enabled, the previous field permissions remain in effect.

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