Android MA 功能整合指南
適用版本
本文適用於 5.5.0 及以後版本的獨立版 MA SDK。
從 5.5.0 開始，MA 不再依賴 AppPush，可以單獨整合和初始化。 MA AppKey 與 Push AppKey 相互獨立，可以相同，也可以不同。
5.5.0 先前的融合版整合方式請查看5.5.0 先前整合指南。
1. 導入 SDK
手動導入
將發布包中的 mt-sdk-ma-5.5.0.aar 加入應用工程的 libs 目錄：
dependencies {
implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
}
Maven 導入
dependencies {
implementation 'com.engagelab.plugin:oth_ma:5.5.0'
}
如果同時使用 AppPush，再按 AppPush 文件引入 engagelab 主包；僅使用 MA 時不需要引入 AppPush 主包。
2. 權限配置
在 AndroidManifest.xml 中聲明網路權限：
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
獨立版 MA 不需要設定 ENGAGELAB_PRIVATES_APPKEY、ENGAGELAB_PRIVATES_CHANNEL、Push Service 或 Push Receiver。若同時使用 AppPush，仍需依照 AppPush 整合文件完成對應設定。
3. 初始化 SDK
建議在主進程的 Application.onCreate() 中初始化。初始化使用 MA AppKey，不需要等待 AppPush 初始化或註冊成功。
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();
}
}
});
}
}
初始化說明
- MA AppKey 必填。
- Android MA SDK 只支援在宿主應用主進程初始化。在非主進程呼叫
start會透過回呼回傳失敗，不會發起網路請求。 - 初始化成功前，除初始化前配置介面外，其他 MA 業務 API 不可用。
- 建議所有 MA 對外 API 均在主程序呼叫。非主進程不會共享主進程的初始化狀態，業務呼叫不會轉送給主進程。
- 初始化成功後也可透過
getEuid()和getMaRid()取得目前值。
運行時切換 MA AppKey
同一進程支援在運行時切換 MA AppKey。請在上一次初始化回呼完成後，使用新 AppKey 再次呼叫 start。
MTMAConfig newConfig = new MTMAConfig("new MA AppKey");
MTMAApi.getInstance(this).start(newConfig, callback);
切換期間其他 MA 業務 API 暫不可用；新 AppKey 初始化成功後，後續事件和使用者資料歸屬新 AppKey。如果新 AppKey 初始化失敗，SDK 不會自動回退到舊 AppKey，需要使用有效 AppKey 重新呼叫 start。
初始化時設定使用者標識
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);
其中 setEmail、setPhone 從 5.5.0 版本開始支援。
使用者標識欄位規則：user_id 去除首尾空格後不能為空，最長 255 個 Unicode 字元，且不能為 0、null、undefined、nan（忽略大小寫）；anonymous_id 去除首尾空格後不能為空，最長 256 個 Unicode 字元；email 不能為空、最長 256 個 Unicode 字元，必須且只能包含一個 @，@ 前後皆不能為空，且不能包含空格、換行或 Tab；phone 必須符合 E.164 格式，以 + 開頭，國家碼首位為 1–9，之後包含 1–14 位數字。校驗失敗時 SDK 不發送身分請求，並透過回呼傳回 code = -3。
4. 同時使用 AppPush
在 MA 控制台設定行動裝置資料來源時，請選擇同時使用 AppPush，並選擇實際存取的 AppPush 應用程式。初始化 AppPush 時，請使用所選應用程式的 AppKey。
MA 與 AppPush 分別初始化，不要求固定順序。 AppPush 註冊成功並取得 Push RID 後，MA SDK 會自動綁定 AppPush 頻道。
AppPush 未整合、尚未註冊或通道綁定失敗，不影響 MA 初始化、事件擷取和上報。
注意：MA RID 與 AppPush RID 是兩個獨立的裝置識別碼。請分別透過對應 SDK 獲取和使用，不要將其中一個作為另一個使用。
5. 設定通道聯繫ID
如需為第三方 Push 通道設定通道聯繫ID，請在 MA 初始化成功後呼叫：
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：MA 控制台配置的第三方 Push 通道 ID，必須大於 0。values：通道聯繫ID的值清單（例如 RID 或 Token），不能為空，清單元素也不能為空。- 通道聯繫ID變更後，需要再次呼叫介面更新。
- 此介面用於設定第三方 Push 通道聯繫ID；AppPush 通道由 SDK 自動綁定。
6. 舊版升級說明
- 升級到 5.5.0 後，必須使用
MTMAConfig明確傳入 MA AppKey。 - 不再需要等待 AppPush 長連線或註冊成功後呼叫 MA
start。 start(CallBack)和start(UserIdentity, CallBack)已廢棄，獨立版請使用start(MTMAConfig, MTMAInitResultCallback)。- 原來同時使用 AppPush 和 MA 的應用，可繼續整合 AppPush，但兩者需要分別初始化。
- MA RID 與 AppPush RID 是兩個獨立的裝置識別碼。請分別透過對應 SDK 獲取和使用，不要將其中一個作為另一個使用。
其他業務介面請查看 API 指南。
