Android SDK API

SDK 介面說明

• MTMAApi，包含 MA 功能的所有介面。

呼叫前說明

• start 只能在宿主應用主程序呼叫。
• 除允許在初始化前設定的配置介面外，其他 MA 業務 API 只能在初始化成功後呼叫。
• 建議所有 MA 對外 API 均在主程序呼叫。非主進程不共享主進程的初始化狀態，呼叫不會轉送給主進程。
• 在非主程序呼叫業務 API 時，有回呼的介面會回傳 CODE_START_FAIL (-2)，getEuid() 和 getMaRid() 傳回空值，無回呼的業務介面不會執行。
• configDebugMode、setCollectControl、setReportInterval、setMaxEventCacheCount 和 setNoActiveSessionEndDurationTime 是進程內設定；在非主進程呼叫不會修改主進程 MA 的配置。

取得 SDK 版本

支援的版本

開始支援的版本：5.5.0

欄位定義

• MTMAApi.SDK_VERSION_CODE：MA SDK 數位版本號。
• MTMAApi.SDK_VERSION_NAME：MA SDK 字串版本號。

              
              int versionCode = MTMAApi.SDK_VERSION_CODE;
String versionName = MTMAApi.SDK_VERSION_NAME;

            

設定調試模式

支援的版本

開始支援的版本：5.5.0

介面定義

• configDebugMode(boolean enable)
  • 開啟或關閉 MA SDK 偵錯日誌。
  • 建議在調用 start 之前設置，發布版本建議關閉。

              
              MTMAApi.configDebugMode(true);

            

啟用MA功能

支援的版本

開始支援的版本：5.5.0

介面定義

• start(MTMAConfig config, MTMAInitResultCallback callback)
  • 介面說明：使用 MA AppKey 初始化獨立版 MA SDK。
  • config：初始化配置。
    • MTMAConfig(String appKey)：設定 MA AppKey。
    • MTMAConfig(String appKey, UserIdentity userIdentity)：設定 MA AppKey，並可同時設定使用者標識。
  • callback：初始化結果回呼。
  • MTMAInitResult：
    • isSuccess()：初始化是否成功。
    • getCode()：結果碼，0 表示成功。
    • getMessage()：結果描述。
    • getEuid()：初始化成功後取得的 EUID。
    • getMaRid()：初始化成功後取得的 MA RID。

呼叫範例

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

            

運行時切換 AppKey

上一次初始化回呼完成後，可使用新的 MTMAConfig 再次呼叫 start。切換期間其他 MA 業務 API 暫不可用。新 AppKey 初始化失敗時不會自動回退到舊 AppKey。

廢棄接口

從 5.5.0 開始，以下介面已廢棄：

• start(CallBack callBack)
• start(UserIdentity userIdentity, CallBack callBack)

請改用 start(MTMAConfig config, MTMAInitResultCallback callback)。

設定使用者標識

建議在使用者登入、提供相關資訊時設定該接口，以獲得與該使用者匹配的 EUID

支援的版本

開始支援的版本： 5.0.0

介面定義

• _setUserIdentity(UserIdentity userIdentity, CallBack callBack) _
  • 介面說明：
    • 設定使用者標識，如：使用者會員卡號。
  • 參數說明：
    • userIdentity：呼叫標識
      • setUserId(String userId)：移除首尾空格後不能為空，最長 255 個 Unicode 字元；不能為 0、null、undefined、nan（忽略大小寫）
      • setAnonymousId(String anonymousId)：移除首尾空格後不能為空，最長 256 個 Unicode 字符
      • setEmail(String email)：不能為空，最長 256 個 Unicode 字元；必須包含且只能包含一個 @，@ 前後都不能為空，且不能包含空格、換行或 Tab；5.5.0 開始支援
      • setPhone(String phone)：必須符合 E.164 格式，以 + 開頭，國家碼首位為 1–9，之後包含 1–14 位數；5.5.0 開始支持
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見 message 參數描述

呼叫範例

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

            

使用者標識欄位校驗失敗時不發送網路請求，並透過回呼傳回 code = -3。

設定使用者聯絡方式

當使用者的聯絡方式發生變更時，可使用本介面更新使用者的「聯絡方式」。

支援的版本

開始支援的版本： 5.0.0

介面定義

• setUserContact(JSONObject contacts, CallBack callBack)
  • 介面說明：
    • 設定使用者的「聯絡方式」。
  • 參數說明：
    • contacts：設定多個聯絡方式，Key 為聯絡人的名稱，value 為聯絡方式的值，目前支援 email、mobile_phone、landline_phone、whatsapp_phone 這 4 種聯絡方式
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見 message 參數描述
    • message：原因描述

呼叫範例

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

            

取得 EUID

支援的版本

開始支援的版本： 5.0.0

介面定義

• getEuid()
  • 介面說明：
    • 取得 EUID，表示使用者唯一 ID。僅初始化成功時傳回目前值，其他狀態傳回空值。

呼叫範例

              
              MTMAApi.getInstance(this).getEuid();

            

取得 MA RID

支援的版本

開始支援的版本：5.5.0

介面定義

• getMaRid()
  • 取得目前 MA RID。僅初始化成功時傳回目前值，其他狀態傳回空值。

              
              String maRid = MTMAApi.getInstance(this).getMaRid();

            

設定通道聯繫ID

支援的版本

開始支援的版本：5.5.0

介面定義

• setChannelValue(long channelId, List values, CallBack callBack)
  • 介面說明：設定通道聯繫ID。 AppPush 通道由 SDK 自動綁定，不需要呼叫該介面設定。
  • 參數說明：
    • channelId：MA 控制台配置的第三方 Push 通道 ID，必須大於 0。
    • values：通道聯繫ID的值清單（例如 RID 或 Token），不能為空，清單元素也不能為空。
    • callBack：結果回調，code == 0 表示成功。

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

            

設定上報資料間隔

和 setMaxEventCacheCount 介面共同生效，只需符合其中一個條件就會回報

支援的版本

開始支援的版本： 5.0.0

介面定義

• setReportInterval(int interval)
  • 介面說明:
    • 設定上報資料間隔，不呼叫該介面時，預設為 10s 上報一次事件數據
    • 上報間隔記憶體緩存，需要在應用程式每次生命週期中呼叫才會生效
  • 參數說明
    • interval 上報間隔，單位 s(秒)

呼叫範例

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

            

設定事件快取上限條數

和 setReportInterval 介面共同生效，只需滿足其中一個條件就會上報

支援的版本

開始支援的版本： 5.0.0

介面定義

• setMaxEventCacheCount(int count)
  • 介面說明:
    • 設定事件快取上限條數，預設50條，最高不能超過500條
    • 當超出快取數量時會上報全部數據
  • 參數說明
    • count 事件快取條數上限

呼叫範例

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

            

設定會話逾時時間

支援的版本

開始支援的版本： 5.0.0

介面定義

• setNoActiveSessionEndDurationTime(int duration)
  • 介面說明:
    • 當 App 置於背景時，開始計算會話逾時時間，超過所設定的時間（預設 30 分鐘）後將會結束本次會話。
  • 參數說明
    • duration 超時時長，單位s(秒)

呼叫範例

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

            

設定 UTM 屬性

支援的版本

開始支援的版本： 5.0.0

介面定義

• setUtmProperties(UtmProperties utmProperties)
  • 介面說明：
    • 設定 UTM 屬性，若開發者能辨識使用者是從哪一個廣告跳轉訪問 App ，建議設定 UTM 訊息，我們將在事件回報時傳遞該參數
  • 參數說明：
    • utmProperties UTM屬性對象
    • • utm_source 廣告活動來源
    • • utm_medium 廣告活動媒介
    • • utm_term 廣告活動字詞
    • • utm_content 廣告活動內容
    • • utm_campaign 廣告活動名稱

呼叫範例

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

            

資料採集控制

支援的版本

開始支援的版本： 5.0.0

介面定義

• setCollectControl(MTMACollectControl control)
  • 介面說明：
    • 設定採集權限，如果需要開啟/關閉某些資料擷取，請呼叫本介面
  • 參數說明：
    • control：擷取權限設定；未明確設定的屬性使用下列預設值
      • setCarrier(boolean enable)：是否擷取操作員訊息，預設為開啟
      • setMacAddress(boolean enable)：是否採集 MAC 位址，預設為關閉
      • setGAID(boolean enable)：是否採集 GAID，預設為關閉
      • setOAID(boolean enable)：是否採集 OAID，預設為關閉
      • setAAID(boolean enable)：是否採集 AAID，預設為關閉
      • setIMEI(boolean enable)：是否採集 IMEI，預設為關閉；僅 Android 9 及以下支持，宿主應用需自行聲明並取得 READ_PHONE_STATE 權限

呼叫範例

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

            

設定使用者屬性

設定使用者屬性的值，若使用者屬性不存在，後台會自動建立。

覆寫更新使用者屬性

• propertySet(final JSONObject properties, final CallBack callBack)
  • 介面說明：
    • 批量覆蓋更新使用者屬性的值
    • 僅儲存最新上報的數據，涵蓋歷史數據，如：用戶會員等級。
    • Value 支援字串、數字、布林值、字串陣列、JSONObject，以及元素全部為 JSONObject 的 JSONArray。
  • 參數說明：
    • properties: 使用者屬性
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 呼叫範例：

              
              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)
  • 介面說明：
    • 單一覆寫更新使用者屬性的值
    • 僅儲存最新上報的數據，涵蓋歷史數據，如：用戶會員等級。
    • Value 類型規則與批次 propertySet 一致。
  • 參數說明：
    • property: 使用者屬性名
    • 值: 使用者屬性值
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 呼叫範例：

              
              MTMAApi.getInstance(this).propertySet("your_property_name","your_property_value", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

累加更新使用者屬性

• propertyIncrease(final Map<String, ? extends Number> properties, CallBack callBack)
  • 介面說明：
    • 對使用者屬性的值設定累加，批次請求
    • 累加所有上報的數據，如累計消費金額。
    • 只能對數值類型的用戶屬性調用這個接口，否則會被忽略, 如果這個用戶屬性之前不存在，則初始值當做 0 來處理。
  • 參數說明：
    • properties: 使用者屬性
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 呼叫範例：

              
              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)
  • 介面說明：
    • 對使用者屬性的值設定累加，單次請求
    • 累加所有上報的數據，如累計消費金額。
    • 只能對數值類型的用戶屬性調用這個接口，否則會被忽略, 如果這個用戶屬性之前不存在，則初始值當做 0 來處理。
  • 參數說明：
    • property: 使用者屬性名
    • 值: 使用者屬性值
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 呼叫範例：

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

            

追加用戶屬性

• propertyAdd(final String property, final String value, CallBack callBack)
  • 介面說明：
    • 對使用者屬性的值進行追加，單次請求
    • 可持續增加此集合元素，元素入庫去重處理，若已存在ABC，追加CD，最終為ABCD。
  • 參數說明：
    • property: 使用者屬性名
    • 值: 使用者屬性值
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 呼叫範例：

              
              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)
  • 介面說明：
    • 對使用者屬性的值進行追加，一次加入多個值
    • 可持續增加此集合元素，元素入庫去重處理，若已存在ABC，追加CD，最終為ABCD。
  • 參數說明：
    • property: 使用者屬性名
    • 值: 使用者屬性值
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 呼叫範例：

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

            

操作 object_array 元素

以下介面從 5.5.0 開始支持，僅用於 object_array 使用者屬性。原有 propertyAdd、propertyRemove 仍用於字串數組，行為不變。

• updateObjectArrayProperty(String property, String identifierKey, Object identifierValue, JSONObject values, CallBack callBack)
  • 根據唯一識別更新一個物件元素的子欄位。
  • identifierValue 支援字串或有限數字；values 不能修改識別欄位。
  • values 中使用 JSONObject.NULL 可刪除對應子欄位。

              
              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)
  • 向 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)
  • 根據唯一識別刪除整個物件元素。

              
              MTMAApi.getInstance(this).removeObjectArrayProperty(
        "devices", "device_id", "device_2", callBack);

            

移除使用者屬性

• propertyRemove(final String property, String values, final CallBack callBack)
  • 介面說明：
    • 移除使用者屬性的值操作。
    • 值為集合元素，元素入庫重處理，若已存在 ABCD，刪除 D，最終為 ABC。
  • 參數說明：
    • property: 使用者屬性名
    • 值: 使用者屬性值
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 呼叫範例：

              
              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)
  • 介面說明：
    • 使用者屬性的值操作移除，一次移除多個值。
    • 值為集合元素，元素入庫重處理，若已存在 ABCD，刪除 CD，最終為 AB。
  • 參數說明：
    • property: 使用者屬性名
    • 值: 使用者屬性值
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 呼叫範例：

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

            

刪除使用者屬性

支援的版本

開始支援的版本： 5.0.0

介面定義

• propertyDelete(final String property, final CallBack callBack)
  • 介面說明：
    • 刪除某個使用者屬性的所有 value 值
  • 參數說明：
    • property: 使用者屬性名
    • callBack：介面回調
  • 回傳說明：
    onCallBack(int code, String message)
    • code: 回傳碼，0 代表取得成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述

呼叫範例

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

            

事件上報

支援的版本

開始支援的版本： 5.0.0

介面定義

• onEvent(String eventKey, JSONObject properties)
  • 介面說明：
    • 事件上報
  • 參數說明：
    • eventKey: 事件名稱
    • properties：事件屬性，Key為屬性名稱，value為屬性值

呼叫範例

              
              JSONObject properties = new JSONObject();
properties.put("key1","v1");
properties.put("key2","v2");
MTMAApi.getInstance(this).onEvent("your_event_name",properties );

            

錯誤碼