Android MA Function Integration Guide

Applicable version

This article applies to the independent version of MA SDK of 5.5.0 and later versions.

Starting from 5.5.0, MA no longer relies on AppPush and can be integrated and initialized independently. MA AppKey and Push AppKey are independent of each other and can be the same or different.

For the integration method of the Fusion version before 5.5.0, please see Integration Guide before 5.5.0.

1. Import SDK

Manual import

Add mt-sdk-ma-5.5.0.aar in the release package to the libs directory of the application project:

              
              dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
}

            

Maven import

              
              dependencies {
    implementation 'com.engagelab.plugin:oth_ma:5.5.0'
}

            

If you use AppPush at the same time, follow the AppPush document to introduce the engagelab main package; when using MA only, you do not need to introduce the AppPush main package.

2. Permission configuration

Declare network permissions in AndroidManifest.xml:

              
              <uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

            

The standalone version of MA does not require configuration of ENGAGELAB_PRIVATES_APPKEY, ENGAGELAB_PRIVATES_CHANNEL, Push Service or Push Receiver. If you use AppPush at the same time, you still need to complete the corresponding configuration according to the AppPush integration document.

3. Initialize SDK

It is recommended to initialize in Application.onCreate() of the main process. MA AppKey is used for initialization, and there is no need to wait for AppPush initialization or successful registration.

              
              import android.app.Application;

import com.engagelab.privates.push.oth.ma.api.MTMAApi;
import com.engagelab.privates.push.oth.ma.api.MTMAConfig;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResult;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResultCallback;

public class MainApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        MTMAApi.configDebugMode(true);
        MTMAConfig config = new MTMAConfig("your MA AppKey");
        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();
                }
            }
        });
    }
}

            

Initialization instructions

• MA AppKey required.
• Android MA SDK only supports initialization in the main process of the host application. Calling start in a non-main process will return failure through the callback and no network request will be initiated.
• Before initialization is successful, other MA business APIs are unavailable except for the pre-initialization configuration interface.
• It is recommended that all MA external APIs be called in the main process. Non-main processes will not share the initialization status of the main process, and business calls will not be forwarded to the main process.
• After successful initialization, the current value can also be obtained through getEuid() and getMaRid().

Switch MA AppKey at runtime

The same process supports switching MA AppKey at runtime. Please call start again with the new AppKey after the last initialization callback is completed.

              
              MTMAConfig newConfig = new MTMAConfig("new MA AppKey");
MTMAApi.getInstance(this).start(newConfig, callback);

            

During the switch, other MA business APIs are temporarily unavailable; after the new AppKey is successfully initialized, subsequent events and user data belong to the new AppKey. If the new AppKey fails to initialize, the SDK will not automatically fall back to the old AppKey, and start needs to be called again with a valid AppKey.

Set user ID during initialization

              
              UserIdentity identity = new UserIdentity();
identity.setUserId("your user id");
identity.setAnonymousId("your anonymous id");
identity.setEmail("user@example.com");
identity.setPhone("+8613800138000");

MTMAConfig config = new MTMAConfig("your MA AppKey", identity);
MTMAApi.getInstance(this).start(config, callback);

            

Among them, setEmail and setPhone are supported starting from version 5.5.0.

User identity field rules: after trimming leading and trailing spaces, user_id must not be empty, must be no longer than 255 Unicode characters, and must not equal 0, null, undefined, or nan (case-insensitive). After trimming, anonymous_id must not be empty and must be no longer than 256 Unicode characters. email must not be empty, must be no longer than 256 Unicode characters, must contain exactly one @, must have non-empty content on both sides of @, and must not contain spaces, line breaks, or tabs. phone must use E.164 format: it starts with +, the country code starts with a digit from 1 to 9, followed by 1–14 digits. If validation fails, the SDK does not send an identity request and returns code = -3 through the callback.

4. Use AppPush at the same time

When configuring the mobile data source in the MA console, please choose to use AppPush at the same time, and select the AppPush application that is actually connected. When initializing AppPush, use the AppKey of the selected app.

MA and AppPush are initialized separately and do not require a fixed order. After AppPush is successfully registered and the Push RID is obtained, MA SDK will automatically bind the AppPush channel.

AppPush is not integrated, has not been registered, or channel binding fails, which does not affect MA initialization, event collection, and reporting.

Note: MA RID and AppPush RID are two independent device identifiers. Please obtain and use them through the corresponding SDK respectively, do not use one as the other.

5. Set channel contact ID

If you need to set the channel contact ID for a third-party Push channel, please call after the MA is successfully initialized:

              
              List<String> values = Collections.singletonList("push rid or token");
MTMAApi.getInstance(this).setChannelValue(136L, values, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
        // code == 0 means success
    }
});

            

• channelId: 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.
• After the channel contact ID changes, the interface update needs to be called again.
• This interface is used to set the third-party Push channel contact ID; the AppPush channel is automatically bound by the SDK.

6. Old version upgrade instructions

• After upgrading to 5.5.0, the MA AppKey must be passed in explicitly using MTMAConfig.
• No longer need to wait for AppPush long connection or successful registration to call MA start.
• start(CallBack) and start(UserIdentity, CallBack) are obsolete, please use start(MTMAConfig, MTMAInitResultCallback) for standalone version.
• Applications that originally used AppPush and MA at the same time can continue to integrate AppPush, but they need to be initialized separately.
• MA RID and AppPush RID are two independent device identifiers. Please obtain and use them through the corresponding SDK respectively, do not use one as the other.

For other business interfaces, please view API Guide.