iOS MA SDK Integration Guide

Applicable Versions

This guide applies to the standalone MTMA SDK v5.5.0 and later. The SDK currently supports iOS 10 and later.

For versions earlier than 5.5.0, see the Integration Guide Before 5.5.0.

Starting with v5.5.0, the MTMA SDK can be integrated and initialized independently, without depending on AppPush. MTMA and AppPush have separate codebases. The official SDK is still distributed in the combined Push package; developers can integrate only MTMA from that package, or both MTMA and MTPush.

Configure the Project

Import the SDK

Import via CocoaPods

              
                  pod 'MTMA'

    Note: If you cannot import the latest version, run pod repo update to update the local pod repository, then run pod 'MTMA' again.

            

• To install a specific version, use the following syntax (MTMA 5.5.0 in this example):

              
                  pod 'MTMA', '5.5.0'

            

Manual Import

• Extract the SDK package. In Xcode, select “Add files to 'Your project name'...” and add MTMA-ios-x.x.x.xcframework to your project directory.

Privacy Manifest

The SDK package includes PrivacyInfo.xcprivacy. If it is not automatically included in the packaged app, use this file as a reference to complete your app’s privacy manifest.

Initialize the SDK

The standalone MTMA SDK is initialized with an MA AppKey and does not need to wait for AppPush initialization or successful registration.

Before initialization, open the MA console and configure the data source associated with the MA AppKey in the current project with the same iOS Bundle ID as your app, then enable the data source. The SDK reads the app’s Bundle Identifier automatically; no separate setting is required. Initialization fails if the Bundle ID is not bound or does not match.

If initialization returns 55004 and message contains packageName is not bound, check the binding configuration above.

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

            

Selected Parameters

• appKey
  • MA AppKey. Required; must contain exactly 24 letters or digits.
  • The MA AppKey and Push AppKey are independent and may be identical or different.
• resultCompletion
  • Initialization result callback. Use result.isSuccess to determine success; on failure, provide result.code and result.message for troubleshooting.
  • For the returned object and its fields, see MTMAInitResult Class.

Initialization requires a network connection. When the device is offline, the SDK waits and automatically resumes when connectivity returns, rather than immediately invoking a failure callback.

The SDK supports repeated initialization and switching MA AppKeys. Each valid call runs in order and receives its own callback. For details, see Start MA Features.

Set User Identifiers During Initialization

To set user identifiers during initialization, pass them through MTMAConfig.userID. userID, anonymousID, email, and phone are all optional. The following example uses 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 initialization succeeded");
    } else {
        NSLog(@"MTMA initialization failed, code=%ld, message=%@", (long)result.code, result.message);
    }
};
[MTMAService start:config];

            

Initialization is also possible without user identifiers. Successful initialization does not mean that every identifier was set successfully. For field validation and callbacks, see MTMAUserID Class.

Initialization Scenarios

Use AppPush Alongside MTMA

When configuring a mobile data source in the MA console, select the option to also use AppPush and choose the AppPush application actually integrated. Initialize AppPush with that application’s AppKey.

Initialize MTMA and AppPush separately. No fixed initialization order is required.

              
              // Initialize the Push SDK
[MTPushService setupWithOption:launchOptions
                        appKey:pushAppKey
                       channel:channel
              apsForProduction:isProduction
         advertisingIdentifier:nil];

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

            

After AppPush registers successfully and obtains a Push RegistrationID, the MTMA SDK automatically sets the AppPush channel. Missing AppPush registration or a channel setup failure does not affect MTMA initialization, event collection, or reporting.

Set Channel Contact IDs

To use a third-party Push service, set its RID or Token after MTMA initializes successfully.

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

            

Selected Parameters

• channelId
  • The third-party Push channel ID configured in the MA console; must be greater than 0.
• values
  • Array of third-party Push RIDs or Tokens. Neither the array nor its elements may be empty.
  • Call the API again to update the value whenever the RID or Token changes.

This API is only for third-party Push services. For detailed constraints, see Set Channel Contact IDs.

Upgrading from Earlier Versions

• The official SDK is still distributed in the combined Push package. Projects already integrating both AppPush and MTMA do not need to change their manual import procedure.
• After upgrading to v5.5.0, you must set appKey in MTMAConfig.
• MTMAConfig.userID and all four user identifier fields are optional. Handle them as optional properties when integrating with Swift.
• The legacy completion callback remains available, but resultCompletion is recommended. If both are set, only resultCompletion is invoked.
• Push RegistrationID and MA RID represent different device identities and must not be used interchangeably.