iOS MA SDK 集成指引 | Marketing Automation 客戶端 SDK 繁體中文

適用版本

本文適用於 v5.5.0 及以後版本的獨立版 MTMA SDK。目前 SDK 只支援 iOS 10 以上版本的手機系統。

5.5.0 以前的集成方式請查看 5.5.0 以前集成指引。

v5.5.0 開始，MTMA SDK 不需要依賴 AppPush，可以單獨集成和初始化。MTMA 與 AppPush 程式碼獨立，正式 SDK 仍透過 Push 組合包發佈，開發者可以只集成組合包中的 MTMA，也可以同時集成 MTMA 和 MTPush。

設定專案

導入 SDK

Cocoapods 導入

pod 'MTMA' 注：如果無法導入最新版本，請執行 pod repo update 命令來升級本機的 pod 庫，然後重新 pod 'MTMA'

              
                  pod 'MTMA'

    注：如果無法導入最新版本，請執行 pod repo update 命令來升級本機的 pod 庫，然後重新 pod 'MTMA'

此代碼塊在浮窗中顯示

如果需要安裝指定版本則使用以下方式（以 MTMA 5.5.0 版本為例）：

pod 'MTMA', '5.5.0'

              
                  pod 'MTMA', '5.5.0'

此代碼塊在浮窗中顯示

手動導入

將 SDK 包解壓，在 Xcode 中選擇 “Add files to 'Your project name'...”，將 MTMA-ios-x.x.x.xcframework 添加到你的專案目錄中。

隱私清單

SDK 包內已提供 PrivacyInfo.xcprivacy。如果打包後的 App 沒有自動帶入，請參考該文件補充 App 的隱私清單。

初始化 SDK

獨立版 MTMA SDK 使用 MA AppKey 進行初始化，不需要等待 AppPush 初始化或註冊成功。

初始化前，請在 MA 控制台為目前專案下 MA AppKey 對應的資料源設定與 App 一致的 iOS Bundle ID，並啟用資料源。SDK 自動讀取 App 的 Bundle Identifier，無須另行設定；未綁定或不一致會導致初始化失敗。

若初始化回傳 55004，且 message 提示 packageName is not bound，請檢查上述綁定設定。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { MTMAConfig *config = [[MTMAConfig alloc] init]; config.appKey = @"your MA AppKey"; config.resultCompletion = ^(MTMAInitResult *result) { NSLog(@"result：%ld - %@", result.code, result.message); }; [MTMAService start:config]; return YES; }

              
              - (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    MTMAConfig *config = [[MTMAConfig alloc] init];
    config.appKey = @"your MA AppKey";
    config.resultCompletion = ^(MTMAInitResult *result) {
        NSLog(@"result：%ld - %@", result.code, result.message);
    };
    [MTMAService start:config];

    return YES;
}

此代碼塊在浮窗中顯示

部分參數說明

appKey
- MA AppKey，必填，必須為 24 位字母或數字。
- MA AppKey 與 Push AppKey 相互獨立，可以相同，也可以不同。
resultCompletion
- 初始化結果回呼，透過 result.isSuccess 判斷是否成功；失敗時可提供 result.code 和 result.message 排查原因。
- 回傳物件及欄位說明見 MTMAInitResult 類。

初始化需要聯網。裝置離線時，SDK 等待網路恢復後自動繼續，不會立即回呼失敗。

SDK 支援重複初始化和切換 MA AppKey，每次有效呼叫按順序執行並分別回呼。詳細規則見啟動 MA 業務功能。

初始化時設定使用者識別

如需在初始化時設定使用者識別，可透過 MTMAConfig.userID 傳入。userID、anonymousID、email、phone 均為可選欄位，以下以 userID 為例：

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

              
              MTMAUserID *userID = [[MTMAUserID alloc] init];
userID.userID = @"member_10001";

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

此代碼塊在浮窗中顯示

不設定使用者識別也可以初始化。初始化成功不代表每個識別都設定成功，欄位驗證及回呼說明見 MTMAUserID 類。

初始化場景

場景	接入方式
MA 與 AppPush 使用相同 AppKey	分別初始化 MTMA 和 AppPush，設定相同的 AppKey，初始化順序不限
只使用 MTMA	只集成和初始化 MTMA，不需要集成 AppPush
先使用 MTMA，後來加入 AppPush	保留 MTMA 集成，加入並初始化 AppPush；AppPush 註冊成功後自動設定通道
MA 與 AppPush 使用不同 AppKey	分別初始化 MTMA 和 AppPush，設定各自的 AppKey，初始化順序不限
使用 JPush 或其他第三方 Push	分別初始化 MTMA 和第三方 Push，待 MTMA 初始化成功且取得第三方 RID 或 Token 後，呼叫第三方 Push 通道設定介面

同時使用 AppPush

在 MA 控制台設定行動端資料來源時，請選擇同時使用 AppPush，並選擇實際接入的 AppPush 應用。初始化 AppPush 時使用所選應用的 AppKey。

MTMA 和 AppPush 分別初始化，不要求固定的初始化順序。

// 初始化 Push SDK [MTPushService setupWithOption:launchOptions appKey:pushAppKey channel:channel apsForProduction:isProduction advertisingIdentifier:nil]; // 初始化 MTMA SDK MTMAConfig *config = [[MTMAConfig alloc] init]; config.appKey = maAppKey; config.resultCompletion = ^(MTMAInitResult *result) { NSLog(@"result：%ld - %@", result.code, result.message); }; [MTMAService start:config];

              
              // 初始化 Push SDK
[MTPushService setupWithOption:launchOptions
                        appKey:pushAppKey
                       channel:channel
              apsForProduction:isProduction
         advertisingIdentifier:nil];

// 初始化 MTMA SDK
MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = maAppKey;
config.resultCompletion = ^(MTMAInitResult *result) {
    NSLog(@"result：%ld - %@", result.code, result.message);
};
[MTMAService start:config];

此代碼塊在浮窗中顯示

AppPush 註冊成功並取得 Push RegistrationID 後，MTMA SDK 會自動設定 AppPush 通道。AppPush 未註冊或通道設定失敗，不影響 MTMA 初始化、事件蒐集和上報。

設定通道聯絡ID

如需使用第三方 Push，請在 MTMA 初始化成功後設定第三方 Push 的 RID 或 Token。

[MTMAService setChannelValueWithChannelId:136 values:@[@"push rid or token"] completion:^(NSInteger code, NSString *message) { NSLog(@"result：%ld - %@", code, message); }];

              
              [MTMAService setChannelValueWithChannelId:136
                                   values:@[@"push rid or token"]
                               completion:^(NSInteger code, NSString *message) {
    NSLog(@"result：%ld - %@", code, message);
}];

此代碼塊在浮窗中顯示

部分參數說明

channelId
- MA 控制台中設定的第三方 Push 通道 ID，必須大於 0。
values
- 第三方 Push 的 RID 或 Token 陣列，陣列及元素均不能為空。
- RID 或 Token 變化後，需要再次呼叫介面更新。

該介面只用於第三方 Push，詳細約束見設定通道聯絡ID。

舊版升級說明

正式 SDK 仍透過 Push 組合包發佈，原來同時集成 AppPush 和 MTMA 的專案不需要調整手動導入方式。
升級到 v5.5.0 後，必須設定 MTMAConfig 的 appKey。
MTMAConfig.userID 和四個使用者識別欄位均為可選屬性，Swift 接入時請按可選屬性處理。
舊版 completion 回呼繼續保留，建議改用 resultCompletion；同時設定時只回呼 resultCompletion。
Push RegistrationID 和 MA RID 是不同的裝置身分，不能混用。