iOS SDK API

SDK 介面說明

1. MTMAService，包含 SDK 所有介面。
2. MTMAConfig，應用設定資訊類。
3. MTMAInitResult，SDK 初始化結果類。
4. MTMAUserID，使用者識別模型。
5. MTMAUserContact, 使用者聯絡方式模型。
6. MTMACollectControl, 資料蒐集控制模型。

啟動 MA 業務功能

支援的版本

開始支援的版本： 5.0.0

email、phone 識別開始支援的版本：5.5.0

獨立初始化開始支援的版本： 5.5.0

介面定義

• + (void)start:(MTMAConfig * )config;
  • 介面說明:
    • 啟用 EngageLab MA 功能。
    • start 介面是其他介面的開始介面，所以必須先呼叫 start 介面，才能呼叫其他介面
    • 獨立版必須設定 MA AppKey，初始化不依賴 AppPush 的註冊結果。
    • 同一個 App 處理程序內可以重複初始化或切換 MA AppKey，無需重啟 App。每次有效呼叫都會單獨執行並回呼，不會合併。
    • start: 與 identifyAccount: 按呼叫順序執行，前一次呼叫及其回呼結束後，才執行下一次。排隊期間修改原設定物件，不影響已提交的初始化參數。
    • MA AppKey 的切換在該次初始化開始執行時生效，排隊期間不改變目前專案或身分。
    • 每次初始化都需要聯網確認使用者身分，請以本次回呼的 EUID 為準。裝置離線時等待網路恢復後繼續，後續呼叫按順序等待；失敗結果見 錯誤碼。
  • 參數說明
    • config 設定類

呼叫範例

              
                  MTMAConfig *config = [[MTMAConfig alloc] init];
    config.appKey = @"你的 MA AppKey";
    config.resultCompletion = ^(MTMAInitResult *result) {
        if (result.isSuccess) {
            NSLog(@"MTMA 初始化成功");
        } else {
            NSLog(@"MTMA 初始化失敗，code=%ld，message=%@", (long)result.code, result.message);
        }
    };
    [MTMAService start:config];

            

設定使用者聯絡方式

支援的版本

開始支援的版本： 5.0.0

介面定義

• + (void)setUserContact:(MTMAUserContact * )contact;
  • 介面說明:
    • 設定使用者聯絡方式
  • 參數說明
    • contacts：設定多個聯絡方式，目前支援 email、mobile_phone、landline_phone、whatsapp_phone。Key 必須為長度 1～256 的字串；value 必須為字串，"" 表示清空該聯絡方式，非空但全是空白的字串無效

呼叫範例

              
                  MTMAUserContact *contact = [[MTMAUserContact alloc] init];
    contact.contacts = @{@"mobile_phone":@"13*********"};
    contact.completion = ^(NSInteger code, NSString * _Nonnull message) { };
    [MTMAService setUserContact:contact];

            

事件上報

支援的版本

開始支援的版本： 5.0.0

介面定義

• **+ (void)eventRecord:(MTMAEventObject )event;*
  • 介面說明:
    • 上報事件
  • 參數說明
    • 上報事件模型
    • eventName：上報的事件名稱
    • property：事件屬性，Key為屬性名稱，value為屬性值

呼叫範例

              
                  MTMAEventObject *object = [[MTMAEventObject alloc] init];
    object.eventName = @"sndefineevent2";
    object.property = @{
        @"key1":@"value1",
        @"key2":@"value2",
    };
    [MTMAService eventRecord:object];

            

設定使用者識別

支援的版本

開始支援的版本： 5.0.0

email、phone 識別開始支援的版本：5.5.0

介面定義

• + (void)identifyAccount:(MTMAUserID * )userID;
  • 介面說明:
    • 設定使用者識別
  • 參數說明
    • 使用者識別模型
    • userID：將唯一的登入使用者識別設定在此
    • anonymousID：當使用者未登入，但提供了其他可作為識別的資訊時，可將其設定為匿名ID，如電子郵件地址、第三方生成的識別ID
    • email：使用者的電子郵件地址，用於識別使用者身分
    • phone：使用者的手機號碼，需包含國家或地區代碼，如 +8613800000000
    • 至少提供一個有效識別，無需全部填寫。詳細要求見本文 使用者識別的類型、長度和格式說明

呼叫範例

              
                  MTMAUserID *userid = [[MTMAUserID alloc] init];
    userid.userID = @"member_10001";
    userid.anonymousID = @"anonymous_10001";
    userid.email = @"member_10001@example.com";
    userid.phone = @"+8613800000000";
    userid.completion = ^(NSInteger code, NSString *message) {
        NSLog(@"result：%ld - %@", code, message);
    };
    [MTMAService identifyAccount:userid];

            

email、phone 在這裡用於使用者身分比對，可能回傳新的 EUID，與 setUserContact: 設定的聯絡方式不能互相替代。

回呼 code=0 表示已取得可用 EUID，不代表所有識別都設定成功。message 中的 JSON 包含本地和伺服器端的逐項結果，key 為 user_id、anonymous_id、email、phone。請按對應欄位的 code 判斷結果，缺少欄位不代表成功。

伺服器端未提供逐項結果時，message 僅含本地拒絕結果；無本地拒絕時為 success。失敗 message 不保證是 JSON。逐項錯誤碼見 使用者識別逐項結果。

例如：

              
              code=0
message={"email":{"code":0},"phone":{"code":3003,"msg":"使用者識別值超過限定長度"}}

            

設定通道聯絡ID

支援的版本

開始支援的版本： 5.5.0

介面定義

• **+ (void)setChannelValueWithChannelId:(NSInteger)channelId values:(NSArray<NSString *> )values completion:(void (^)(NSInteger code, NSString message))completion;
  • 介面說明:
    • 為第三方 Push 通道設定 RID 或 Token
    • EngageLab AppPush 的通道關係由 SDK 自動處理，不需要呼叫該介面設定
    • 未集成 AppPush 或 AppPush 註冊失敗，不影響 MA 其他功能使用
    • 連續呼叫時，SDK 按呼叫順序依次請求，並分別回呼結果
    • 排隊期間 MA AppKey、專案或身分發生變化時，對應請求回傳 -2
  • 參數說明
    • channelId：MA 控制台中的第三方 Push 通道 ID，必須大於 0
    • values：目前通道的 RID 或 Token 陣列。SDK 去除每個值的首尾空白後傳送，陣列及裁剪後的元素均不能為空
    • completion：請求結果回呼，code 為 0 表示成功

呼叫範例

              
                  [MTMAService setChannelValueWithChannelId:136
                                       values:@[@"第三方 Push RID 或 Token"]
                                   completion:^(NSInteger code, NSString *message) {
    }];

            

設定上報資料間隔

支援的版本

開始支援的版本： 5.0.0

介面定義

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

呼叫範例

              
                  [MTMAService setReportInterval:10];

            

設定事件快取上限條數

支援的版本

開始支援的版本： 5.0.0

介面定義

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

呼叫範例

              
                  [MTMAService setMaxEventCacheCount:50];

            

設定工作階段逾時時間

支援的版本

開始支援的版本： 5.0.0

介面定義

• + (void)setNoActiveSessionEndDurationTime:(NSInteger)interval;
  • 介面說明:
    • 設定工作階段逾時時間，預設 30 分鐘
    • App 切換到背景，工作階段開始逾時計時，逾時時間內沒有活動，就結束目前工作階段
  • 參數說明
    • interval 逾時時長，單位s(秒)

呼叫範例

              
                  [MTMAService setNoActiveSessionEndDurationTime:50];

            

取得 EUID

支援的版本

開始支援的版本： 5.0.0

介面定義

• + (nullable NSString * )EUID;
  • 介面說明:
    • 取得 EngageLab MA 的 EUID
    • SDK 未初始化成功時回傳 nil

呼叫範例

              
                  [MTMAService EUID];

            

設定 UTM 屬性

支援的版本

開始支援的版本： 5.0.0

介面定義

• + (void)setUtmProperties:(NSDictionary * )property;
  • 介面說明:
    • UTM 屬性為標準事件屬性，若開發者能識別使用者是從哪一個廣告跳轉訪問 App ，建議設定 UTM 資訊，我們將在事件上報時傳遞該參數。目前能夠設定 UTM 屬性為：
      • utm_source 廣告系列來源
      • utm_medium 廣告系列媒介
      • utm_term 廣告系列字詞
      • utm_content 廣告系列內容
      • utm_campaign 廣告系列名稱
      • utm_id 廣告系列ID

呼叫範例

              
                  [MTMAService setUtmProperties:@{@"utm_source":@"value"}];

            

設定使用者屬性

覆蓋更新使用者屬性

• + (void)setProperty:(NSDictionary * )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;
  • 介面說明:
    • 批量設定使用者屬性；一次最多 100 個。任意一個屬性在 SDK 驗證失敗時，整批請求都不會傳送。
    • 屬性名必須是 NSString：以小寫字母開頭，只能包含小寫字母、數字、底線，最長 50 個 UTF-8 位元組，且不能以 el、engagelab、metaverse 開頭。
    • Value 支援 NSString、有限數值 NSNumber、字串 NSSet/NSArray、NSDictionary（object）和 NSArray<NSDictionary *>（object_array）。
    • 普通類型已存在時覆蓋，不存在時建立；object 使用子欄位合併語義；object_array 使用整體替換語義並保持陣列順序。
  • 呼叫範例:

              
                 [MTMAService setProperty:@{
       @"level": @"gold",
       @"profile": @{ @"city": @"Singapore", @"score": @100 },
       @"addresses": @[
           @{ @"id": @"home", @"city": @"Singapore" },
           @{ @"id": @"office", @"city": @"Tokyo" }
       ]
   } completion:^(NSInteger code, NSString * _Nonnull message) {
       // code == 0 表示伺服器端處理成功
   }];

            

• + (void)setProperty:(NSString * )key to:(id)value completion:(void (^)(NSInteger code, NSString * message))completion;
  • 介面說明:
    • 設定使用者的單個使用者屬性的內容。
    • 屬性名、Value 類型和更新語義與批量介面完全一致。
  • 呼叫範例:

              
                 [MTMAService setProperty:@"profile"
                         to:@{ @"city": @"Singapore", @"score": @100 }
                 completion:^(NSInteger code, NSString * _Nonnull message) {
   }];

            

object / object_array 規則

• object 必須是非空 NSDictionary。子欄位名必須是非空 NSString，不能包含 . 或 $。
• object 子欄位值支援 NSString、有限數值 NSNumber、字串 NSSet/NSArray 和 NSNull；不支援繼續巢狀嵌入 object 或 object_array。
• 再次對 object 呼叫 setProperty 時，只合併本次傳入的子欄位；未傳子欄位保持不變。子欄位值傳 NSNull 表示移除該子欄位。
• object_array 必須是 NSArray<NSDictionary *>；每個物件都必須非空，並遵守相同的子欄位規則。再次呼叫 setProperty 會整體替換陣列。
• object_array 的每個元素必須至少保留一個非 NSNull 子欄位，不能傳入所有子欄位值均為 NSNull 的物件。
• 空陣列可用於清空一個已經存在的陣列屬性，但首次建立時無法僅根據空陣列區分字串列表和 object_array；首次建立 object_array 請傳非空物件陣列。
• NSNull 只允許作為 object/object_array 的子欄位值。不能用頂層 NSNull 刪除完整屬性；刪除完整屬性請呼叫 deleteProperty:completion:。

object 局部更新和移除子欄位範例：

              
              // 只更新 profile.score，profile.city 保持不變
[MTMAService setProperty:@"profile"
                      to:@{ @"score": @200 }
              completion:completion];

// 只移除 profile.city
[MTMAService setProperty:@"profile"
                      to:@{ @"city": NSNull.null }
              completion:completion];

            

局部更新 object_array 元素

開始支援的版本：5.5.0

• **+ (void)updateObjectArrayProperty:(NSString *)key identifierKey:(NSString )identifierKey identifierValue:(id)identifierValue values:(NSDictionary<NSString *, id> )values completion:(void (^)(NSInteger code, NSString * message))completion;
  • 介面說明:
    • 在 object_array 中透過唯一子欄位定位一個物件，然後合併 values 中的子欄位。
    • identifierKey 對應的子欄位必須已經在伺服器端中繼資料中定義，類型只能是 string 或 number；identifierValue 必須是相同類型的 NSString 或非布林、有限數值 NSNumber，並且在目前陣列中只能比對一項。
    • values 必須是非空字典，不能包含 identifierKey，也不能巢狀嵌入 object/object_array。未傳欄位保持不變；值傳 NSNull 時移除該子欄位。
    • 該屬性必須已經在伺服器端中繼資料中定義為 object_array，且目前使用者已有該屬性值。首次建立可用 setProperty:to: 傳入非空物件陣列。
    • 屬性尚未定義，或已定義但目前使用者還沒有值時，伺服器端回傳 code=0 但不產生修改。code=0 僅表示請求處理成功，應透過 MA 控制台或伺服器端使用者屬性確認實際修改結果。
    • 已有陣列但沒有比對項、比對多項、識別欄位類型不一致或子欄位不符合中繼資料定義時，由伺服器端回傳失敗碼，不會建立或修改其他元素。
  • 呼叫範例:

              
              // id == home 的物件：把 city 更新為 Tokyo，同時移除 zip
[MTMAService updateObjectArrayProperty:@"addresses"
                         identifierKey:@"id"
                       identifierValue:@"home"
                                values:@{
                                    @"city": @"Tokyo",
                                    @"zip": NSNull.null
                                }
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

追加 object_array 元素

開始支援的版本：5.5.0

• **+ (void)addObjectArrayProperty:(NSString )key object:(NSDictionary<NSString *, id> )object completion:(void (^)(NSInteger code, NSString * message))completion;
  • 介面說明:
    • 往 object_array 末尾追加一個物件元素，不影響已有元素。與 setProperty:to: 傳整個陣列的整體替換語義不同。
    • object 必須是非空 NSDictionary，至少保留一個非 NSNull 子欄位，子欄位規則與 object 一致，不支援巢狀嵌入 object/object_array。
    • 該屬性必須已經在伺服器端中繼資料中定義為 object_array。尚未定義時伺服器端回傳 code=0 但不產生修改，請先用 setProperty:to: 傳非空物件陣列完成首次建立。
    • 屬性已定義但目前使用者還沒有值時，本介面會用這一個元素建立陣列。
  • 呼叫範例:

              
              [MTMAService addObjectArrayProperty:@"addresses"
                                object:@{
                                    @"id": @"school",
                                    @"city": @"Osaka"
                                }
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

移除 object_array 元素

開始支援的版本：5.5.0

• **+ (void)removeObjectArrayProperty:(NSString )key identifierKey:(NSString )identifierKey identifierValue:(id)identifierValue completion:(void (^)(NSInteger code, NSString * message))completion;
  • 介面說明:
    • 透過唯一子欄位定位並移除整個陣列元素。只想移除元素裡的某個子欄位，請用 updateObjectArrayProperty: 把該子欄位傳 NSNull。
    • identifierKey / identifierValue 的約束與 updateObjectArrayProperty: 完全一致：子欄位必須已在中繼資料中定義，類型只能是 string 或 number，且在目前陣列中只能比對一項。
    • 該屬性尚未在伺服器端定義，或目前使用者沒有該屬性值、沒有比對項時，伺服器端忽略本次請求並回傳 code=0，需透過 MA 控制台或伺服器端使用者屬性確認實際修改結果。
    • 比對多項或識別欄位類型不一致時，由伺服器端回傳失敗碼，不會誤刪其他元素。
  • 呼叫範例:

              
              // 刪掉 id == office 的那個地址
[MTMAService removeObjectArrayProperty:@"addresses"
                         identifierKey:@"id"
                       identifierValue:@"office"
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

累加更新使用者屬性

• **+ (void)increaseProperty:(NSString )key by:(NSNumber )amount completion:(void (^)(NSInteger code, NSString * message))completion;
  • 介面說明:
    • 給一個數值類型的使用者屬性增加一個數值，累加所有上報的資料，如累計消費金額。
    • 只能對 NSNumber 類型的使用者屬性呼叫這個介面，否則會被忽略, 如果這個使用者屬性之前不存在，則初始值當做 0 來處理。
  • 呼叫範例:

              
                  [MTMAService increaseProperty:@"key" by:@(2) completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

• **+ (void)increaseProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;*
  • 介面說明:
    • 給多個數值類型的使用者屬性增加數值，累加所有上報的資料，如累計消費金額。
    • 只能對 NSNumber 類型的使用者屬性呼叫這個介面，否則會被忽略, 如果這個使用者屬性之前不存在，則初始值當做 0 來處理。
  • 呼叫範例:

              
                  [MTMAService increaseProperty:@{@"key1":@(5),@"key2":@(3)} completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

追加使用者屬性

• **+ (void)addProperty:(NSString )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion
  • 介面說明:
    • 向一個 NSSet 或者 NSArray 類型的屬性添加一些值。
    • 如前面所述，這個 NSSet 或者 NSArray 的元素必須是 NSString，否則，會忽略, 同時，如果要 add 的使用者屬性之前不存在，會初始化一個空的 NSSet 或者 NSArray。
  • 呼叫範例:

              
                  [MTMAService addProperty:@"key" by:@[@"value"] completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

• **+ (void)addProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger, NSString * _Nonnull))completion;*
  • 介面說明:
    • 向多個 NSSet 或者 NSArray 類型的屬性添加一些值。
    • 如前面所述，這個 NSSet 或者 NSArray 的元素必須是 NSString，否則，會忽略, 同時，如果要 add 的使用者屬性之前不存在，會初始化一個空的 NSSet 或者 NSArray。
  • 呼叫範例:

              
                  [MTMAService addProperty:@{@"key1":@[@"value"],@"key2":@[@"value"]} completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

移除使用者屬性

• **+ (void)removeProperty:(NSString * )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion;*
  • 介面說明:
    • 向一個 NSSet 或者 NSArray 類型的屬性刪除一些值。
    • 參數 content 類型為 NSSet 或者 NSArray，裡面的元素必須是 NSString。
  • 呼叫範例:

              
                  [MTMAService removeProperty:@"key" by:@[@"value"] completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

刪除使用者屬性

支援的版本

開始支援的版本： 5.0.0

介面定義

• + (void)deleteProperty:(NSString * )key completion:(void (^)(NSInteger code, NSString * message))completion;
  • 介面說明:
    • 刪除某個使用者屬性的全部內容，適用於普通類型、object 和 object_array。
    • 如果這個使用者屬性之前不存在，則直接忽略。

呼叫範例

              
                  [MTMAService deleteProperty:@"key" completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

資料蒐集控制

支援的版本

開始支援的版本： 5.0.0

介面定義

• **+ (void)setCollectControl:(MTMACollectControl )control;*
  • 介面說明:
    • 控制 MTMACollectControl 類中資料項是否蒐集

呼叫範例

              
                  MTMACollectControl *collectControl = [[MTMACollectControl alloc] init];
    collectControl.idfa = YES;
    collectControl.idfv = YES;
    collectControl.carrier = YES;
    [MTMAService setCollectControl:collectControl];

            

MTMAConfig 類

應用設定資訊類。以下是屬性說明：

MTMAInitResult 類

resultCompletion 回傳的 SDK 初始化結果物件，不需要單獨建立或呼叫。以下是屬性說明：

MTMAUserID 類

使用者識別模型類。初始化時透過 MTMAConfig.userID 傳入，執行期間透過 identifyAccount: 傳入。

四個識別均為可選欄位，統一去除首尾空格；空值及 0/null/undefined/nan（忽略大小寫）按未傳處理，不參與比對，也不產生逐欄位結果。以下約束適用於清洗後保留的值：

非 NSString 或格式不合法的欄位按 3013、超長欄位按 3003 剔除並記錄結果，其餘合法欄位繼續提交。沒有合法欄位時，初始化按未傳身分繼續，identifyAccount: 回傳 -3 且不傳送請求。SDK 不修改呼叫方物件；email 由伺服器端轉為小寫。

初始化成功時，userID.completion 回傳 code=0，message 為空字串或僅含本地拒絕欄位 JSON，不包含伺服器端逐項結果，不能據此認為所有識別都已綁定。SDK 初始化結果以 config.resultCompletion 為準，該回呼不包含逐識別 JSON。執行期間回呼說明見 設定使用者識別。

MTMACollectControl 類

使用者資料蒐集控制模型類。以下是屬性說明：

MTMAUserContact 類

使用者通道模型類。以下是屬性說明：
如果不設定或者設定為 nil 則認為不修改，設定為 "" 空字串時認為清空該聯絡方式；非空但全是空白的字串無效

MTMAEventObject 類

自訂事件物件類。以下是屬性說明：