Android SDK API

SDK Interface Description

• MTMAApi, which contains all the interfaces of the SDK.

Enable the MA Function

Supported Versions

The version when it starts to be supported: 5.0.0

Interface Definition

• start(UserIdentity userIdentity, CallBack callBack)
  • Interface Description:
    • Start using the MA function. User identification information can be set simultaneously when enabling it.
  • Parameter Description:
    • userIdentity: The call identification, which can be set to null if there is none.
      • setUserId(String userId): userId, set the unique logged-in user identification here.
      • setAnonymousId(String anonymousId): anonymousId, when the user is not logged in but other identifiable information is provided, it can be set as the anonymous ID, such as an email address or an identification ID generated by a third party.
    • callBack: The result data callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the message parameter for details.
    • message: The reason description.

Call Example

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

                    }
                });

        

Set User Identification

It is recommended to set this interface when the user logs in or provides relevant information to obtain the EUID that matches the user.

Supported Versions

The version when it starts to be supported: 5.0.0

Interface Definition

• _setUserIdentity(UserIdentity userIdentity, CallBack callBack) _
  • Interface Description:
    • Set the user identification, such as the user's membership card number.
  • Parameter Description:
    • userIdentity: The call identification.
      • setUserId(String userId): userId, set the unique logged-in user identification here.
      • setAnonymousId(String anonymousId): anonymousId, when the user is not logged in but other identifiable information is provided, it can be set as the anonymous ID, such as an email address or an identification ID generated by a third party.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the message parameter for details.

Call Example

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

        

Set User Contact Information

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

Supported Versions

The version when it starts to be 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 information. The key is the name of the contact information, and the value is the value of the contact information. Currently, 4 types of contact information are supported: email, mobile_phone, landline_phone, and whatsapp_phone.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the message parameter for details.
    • message: The 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

The version when it starts to be supported: 5.0.0

Interface Definition

• getEuid()
  • Interface Description:
    • Get the euid, which represents the unique user ID.

Call Example

          MTMAApi.getInstance(this).getEuid();

        

Set the Report Interval of Uploaded Data

It takes effect together with the setMaxEventCacheCount interface. Reporting will occur as long as one of the conditions is met.

Supported Versions

The version when it starts to be supported: 5.0.0

Interface Definition

• setReportInterval(int interval)
  • Interface Description:
    • Set the report interval of uploaded data. When this interface is not called, the event data is reported once every 10 seconds by default.
    • The report interval is cached in memory and needs to be called in each lifecycle of the application to take effect.
  • Parameter Description
    • interval: The report interval, in s (seconds).

Call Example

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

        

Set the Upper Limit of Event Cache Entries

It takes effect together with the setReportInterval interface. Reporting will occur as long as one of the conditions is met.

Supported Versions

The version when it starts to be supported: 5.0.0

Interface Definition

• setMaxEventCacheCount(int count)
  • Interface Description:
    • Set the upper limit of the number of event cache entries, which is 50 by default and cannot exceed 500 at most.
    • When the cache quantity is exceeded, all data will be reported.
  • Parameter Description
    • count: The upper limit of the number of event cache entries.

Call Example

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

        

Set the Session Timeout

Supported Versions

The version when it starts to be supported: 5.0.0

Interface Definition

• setNoActiveSessionEndDurationTime(int duration)
  • Interface Description:
    • When the App is placed in the background, the session timeout time starts to be calculated. After exceeding the set time (30 minutes by default), this session will end.
  • Parameter Description
    • duration: The timeout duration, in s (seconds).

Call Example

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

        

Set UTM Properties

Supported Versions

The version when it starts to be supported: 5.0.0

Interface Definition

• setUtmProperties(UtmProperties utmProperties)
  • Interface Description:
    • Set the UTM properties. If developers can identify which advertisement the user jumped from to access the App, it is recommended to set the UTM information, and we will pass this parameter when reporting events.
  • Parameter Description:
    • utmProperties: The UTM property object.
    • • utm_source: The source of the advertising campaign.
    • • utm_medium: The medium of the advertising campaign.
    • • utm_term: The term of the advertising campaign.
    • • utm_content: The content of the advertising campaign.
    • • utm_campaign: The name of the advertising campaign.

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

        

Set the Collection Permission

Supported Versions

The version when it starts to be supported: 5.0.0

Interface Definition

• setCollectControl(MTMACollectControl control)
  • Interface Description:
    • Set the collection permission. If you need to enable/disable the collection of certain data, please call this interface.
  • Parameter Description:
    • control: The permission setting, which is enabled by default.

Call Example

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

        

Set User Properties

Set the value of the user properties. If the user properties do not exist, they will be automatically created in the background.

Overwrite and Update User Properties

• propertySet(final JSONObject properties, final CallBack callBack)
  • Interface Description:
    • Update the values of user properties in batches by overwriting.
    • Only the latest reported data is saved, overwriting the historical data, such as the user's membership level.
  • Parameter Description:
    • properties: User properties.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the error code for details.
    • message: The reason description.
  • Call Example:

          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)
  • Interface Description:
    • Update the value of a single user property by overwriting.
    • Only the latest reported data is saved, overwriting the historical data, such as the user's membership level.
  • Parameter Description:
    • property: The user property name.
    • value: The user property value.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the error code for details.
    • message: The reason description.
  • Call Example:

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

        

Increment and Update User Properties

• propertyIncrease(final Map<String, ? extends Number> properties, CallBack callBack)
  • Interface Description:
    • Set an increment for the values of user properties, for batch requests.
    • Accumulate all the reported data, such as the cumulative consumption amount.
    • This interface can only be called for user properties of the numeric type, otherwise it will be ignored. If this user property did not exist before, the initial value is treated as 0.
  • Parameter Description:
    • properties: User properties.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the error code for details.
    • message: The reason description.
  • Call Example:

          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)
  • Interface Description:
    • Set an increment for the value of a user property, for a single request.
    • Accumulate all the reported data, such as the cumulative consumption amount.
    • This interface can only be called for user properties of the numeric type, otherwise it will be ignored. If this user property did not exist before, the initial value is treated as 0.
  • Parameter Description:
    • property: The user property name.
    • value: The user property value.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the error code for details.
    • message: The reason description.
  • Call Example:

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

        

Append User Properties

• propertyAdd(final String property, final String value, CallBack callBack)
  • Interface Description:
    • Append a value to the value of a user property, for a single request.
    • The elements of this set can be continuously added, and duplicate elements are removed when stored in the database. If ABC already exists and CD is appended, the final result will be ABCD.
  • Parameter Description:
    • property: The user property name.
    • value: The user property value.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the error code for details.
    • message: The reason description.
  • Call Example:

          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)
  • Interface Description:
    • Append values to the value of a user property, adding multiple values at once.
    • The elements of this set can be continuously added, and duplicate elements are removed when stored in the database. If ABC already exists and CD is appended, the final result will be ABCD.
  • Parameter Description:
    • property: The user property name.
    • value: The user property value.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the error code for details.
    • message: The reason description.
  • Call Example:

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

        

Remove User Properties

• propertyRemove(final String property, String values, final CallBack callBack)
  • Interface Description:
    • Remove the value of a user property.
    • This value is an element of the set, and duplicate elements are removed when stored in the database. If ABCD already exists and D is removed, the final result will be ABC.
  • Parameter Description:
    • property: The user property name.
    • value: The user property value.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the error code for details.
    • message: The reason description.
  • Call Example:

          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)
  • Interface Description:
    • Remove multiple values of a user property at once.
    • These values are elements of the set, and duplicate elements are removed when stored in the database. If ABCD already exists and CD is removed, the final result will be AB.
  • Parameter Description:
    • property: The user property name.
    • value: The user property value.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the error code for details.
    • message: The reason description.
  • Call Example:

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

        

Delete User Properties

Supported Versions

The version when it starts to be supported: 5.0.0

Interface Definition

• propertyDelete(final String property, final CallBack callBack)
  • Interface Description:
    • Delete all the value(s) of a certain user property.
  • Parameter Description:
    • property: The user property name.
    • callBack: The interface callback.
  • Return Description:
    onCallBack(int code, String message)
    • code: The return code. 0 represents a successful acquisition, and -1 represents a failure. See the description of the error code for details.
    • message: The reason description.

Call Example

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

        

Custom Event Reporting

Supported Versions

The version when it starts to be supported: 5.0.0

Interface Definition

• onEvent(String eventKey, JSONObject property)
  • Interface Description:
    • Report a custom event.
  • Parameter Description:
    • eventKey: The event name.
    • property: The event properties. The key is the property name, and the value is the property value.

Call Example

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

        

Error Codes: