Android SDK API

SDK 接口說明

• MTMAApi，包含 SDK 所有接口。

啟用MA功能

支援的版本

開始支援的版本： 5.0.0

接口定義

• start(UserIdentity userIdentity,CallBack callBack)
  • 接口說明：
    • 開始使用 MA 功能，啟用時可以同時設置用戶標識信息
  • 參數說明：
    • userIdentity：調用標識，如果沒有可設置 null
      • setUserId(String userId)：userId，將唯一的登錄用戶標識設置在此
      • setAnonymousId(String anonymousId)：anonymousId，當用戶未登錄，但提供了其他可作為標識的信息時，可將其設置為匿名ID，如郵箱地址、第三方生成的標識ID
    • callBack：結果數據回調
  • 返回說明：
    onCallBack(int code, String message)
    • code: 返回碼，0 代表獲取成功，-1 為失敗，詳見 message 參數描述
    • message：原因描述

調用示例

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

                    }
                });

        

設置用戶標識

建議在用戶登錄、提供相關信息時設置該接口，獲得與該用戶匹配的 EUID

支援的版本

開始支援的版本： 5.0.0

接口定義

• _setUserIdentity(UserIdentity userIdentity, CallBack callBack) _
  • 接口說明：
    • 設置用戶標識，如：用戶會員卡號。
  • 參數說明：
    • userIdentity：調用標識
      • setUserId(String userId)：userId，將唯一的登錄用戶標識設置在此
      • setAnonymousId(String anonymousId)：anonymousId，當用戶未登錄，但提供了其他可作為標識的信息時，可將其設置為匿名ID，如郵箱地址、第三方生成的標識ID
    • callBack：接口回調
  • 返回說明：
    onCallBack(int code, String message)
    • code: 返回碼，0 代表獲取成功，-1 為失敗，詳見 message 參數描述

調用示例

                          UserIdentity userIdentity = new UserIdentity();
                userIdentity.setUserId("您的userId");
                userIdentity.setAnonymousId("您的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);
                    }
                });

        

設置用戶聯繫方式

當用戶的聯繫方式發生變更時，可使用本接口更新用戶的「聯繫方式」。

支援的版本

開始支援的版本： 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();

        

設置上報數據間隔

和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("你的utm_source");
                utmProperties.setUtmCampaign("您的utm_campaign");
                utmProperties.setUtmContent("您的utm_content");
                utmProperties.setUtmId("您的utm_id" );
                utmProperties.setUtmMedium("您的utm_medium");
                utmProperties.setUtmTerm("您的utm_term");
                MTMAApi.getInstance(this).setUtmProperties(utmProperties);

        

設置 採集權限

支援的版本

開始支援的版本： 5.0.0

接口定義

• setCollectControl(MTMACollectControl control)
  • 接口說明：
    • 設置 採集權限，如果需要開啟/關閉某些數據採集，請調用本接口
  • 參數說明：
    • control： 權限設置，默認開

調用示例

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

        

設置用戶屬性

設置用戶屬性的值，若用戶屬性不存在，後台會自動創建。

覆蓋更新用戶屬性

• propertySet(final JSONObject properties, final CallBack callBack)
  • 接口說明：
    • 批量覆蓋更新用戶屬性的值
    • 僅保存最新上報的數據，覆蓋歷史數據，如：用戶會員等級。
  • 參數說明：
    • properties: 用戶屬性
    • callBack：接口回調
  • 返回說明：
    onCallBack(int code, String message)
    • code: 返回碼，0 代表獲取成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 調用示例：

          try {JSONObject properties = new JSONObject();
    properties.put("你的用戶屬性名","你的屬性值");
    properties.put("你的用戶屬性名 2","你的屬性值 2");
    properties.put("你的用戶屬性名 3","你的屬性值 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)
  • 接口說明：
    • 單個覆蓋更新用戶屬性的值
    • 僅保存最新上報的數據，覆蓋歷史數據，如：用戶會員等級。
  • 參數說明：
    • property: 用戶屬性名
    • value: 用戶屬性值
    • callBack：接口回調
  • 返回說明：
    onCallBack(int code, String message)
    • code: 返回碼，0 代表獲取成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 調用示例：

          MTMAApi.getInstance(this).propertySet("你的用戶屬性名","你的屬性值", 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("你的用戶屬性名",1);
properties.put("你的用戶屬性名 2",2);
properties.put("你的用戶屬性名 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: 用戶屬性名
    • value: 用戶屬性值
    • callBack：接口回調
  • 返回說明：
    onCallBack(int code, String message)
    • code: 返回碼，0 代表獲取成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 調用示例：

          MTMAApi.getInstance(this).propertyIncrease("你的用戶屬性名",1, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

        

追加用戶屬性

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

          MTMAApi.getInstance(this).propertyAdd("你的用戶屬性名","你的用戶屬性值", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

        

• propertyAdd(final String property, final Set values, CallBack callBack)
  • 接口說明：
    • 對用戶屬性的值進行追加，一次添加多個值
    • 可持續增加該集合元素，元素入庫去重處理，若已存在ABC，追加CD，最終為ABCD。
  • 參數說明：
    • property: 用戶屬性名
    • value: 用戶屬性值
    • callBack：接口回調
  • 返回說明：
    onCallBack(int code, String message)
    • code: 返回碼，0 代表獲取成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 調用示例：

          Set<String> properties = new HashSet<>();
properties.add("你的用戶屬性值");
properties.add("你的用戶屬性值 2");
properties.add("你的用戶屬性值 3");
MTMAApi.getInstance(this).propertyAdd("你的用戶屬性名",properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

        

移除用戶屬性

• propertyRemove(final String property, String values, final CallBack callBack)
  • 接口說明：
    • 對用戶屬性的值操作移除。
    • 該值為集合元素，元素入庫去重處理，若已存在ABCD，刪除D，最終為ABC。
  • 參數說明：
    • property: 用戶屬性名
    • value: 用戶屬性值
    • callBack：接口回調
  • 返回說明：
    onCallBack(int code, String message)
    • code: 返回碼，0 代表獲取成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 調用示例：

          MTMAApi.getInstance(this).propertyRemove("你的用戶屬性名","你的用户属性值", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

        

• propertyRemove(final String property, Set values, final CallBack callBack)
  • 接口說明：
    • 對用戶屬性的值操作移除，一次移除多個值。
    • 該值為集合元素，元素入庫去重處理，若已存在ABCD，刪除CD，最終為AB。
  • 參數說明：
    • property: 用戶屬性名
    • value: 用戶屬性值
    • callBack：接口回調
  • 返回說明：
    onCallBack(int code, String message)
    • code: 返回碼，0 代表獲取成功，-1 為失敗，詳見錯誤碼描述
    • message：原因描述
  • 調用示例：

          Set<String> properties = new HashSet<>();
properties.add("你的用戶屬性值");
properties.add("你的用戶屬性值 2");
properties.add("你的用戶屬性值 3");
MTMAApi.getInstance(this).propertyRemove("你的用戶屬性名",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("你的用戶屬性名", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

        

自定義事件上報

支援的版本

開始支援的版本： 5.0.0

接口定義

• onEvent(String eventKey, JSONObject property)
  • 接口說明：
    • 自定義事件上報
  • 參數說明：
    • eventKey: 事件名稱
    • property：事件屬性，Key為屬性名稱，value為屬性值

調用示例

          JSONObject property = new JSONObject();
properties.put("key1","v1");
properties.put("key2","v2");
MTMAApi.getInstance(this).onEvent("你的事件名稱",property );

        

錯誤碼：