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");
// 可選（5.5.2 起支援）：需要按使用者同意結果控制採集時，傳入應用目前記錄的同意結果，true 開啟、false 關閉，從未設定過則預設開啟
// 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();
}
}
});
}
}
初始化說明
- 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。
可選：按使用者同意控制採集
如應用需要根據使用者同意結果控制採集，可使用資料採集開關；不需要時無需任何改動，預設開啟，行為與升級前一致。該能力從 MA SDK 5.5.2 開始提供。
開關按 MA AppKey 分別儲存。在初始化時，請根據使用者的同意狀態對 dataCollectionEnabled 動態傳值，不要寫死配置，避免每次初始化都導致狀態被重設為寫死的值。運行中使用者改變選擇時，在初始化成功後呼叫 setDataCollectionEnabled 介面。均在主進程執行：
// enabled 為應用根據使用者同意結果決定的開關狀態
MTMAConfig config = new MTMAConfig(maAppKey);
config.dataCollectionEnabled(enabled);
MTMAApi.getInstance(this).start(config, initCallback);
// 運行中使用者改變選擇時
MTMAApi.getInstance(this).setDataCollectionEnabled(enabled);
接入時需注意：
- 關閉期間，事件、使用者屬性、UTM 和裝置資訊停止採集與上報；初始化、使用者標識、聯絡方式和推播通道照常可用，SDK 仍會發送這些必要請求。
- 從開啟切換為關閉時，SDK 會立即發送一次切換前已產生的資料，失敗不重試，隨後清除本機快取。
- 呼叫
config.dataCollectionEnabled時須傳入true或false，每次start都會生效：與上次狀態不同時，本次啟動直接按新狀態初始化；在已啟動的情況下再次呼叫start改變狀態時，會執行一次關閉或開啟處理。 - 重新開啟後 SDK 自動恢復採集，恢復完成前呼叫的事件、使用者屬性和 UTM 不會保留。
介面參數、各介面在關閉期間的行為和錯誤碼，見 API 指南的資料採集開關。
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 指南。
