iOS SDK API

SDK Interfaces

1. MTMAService: Contains all SDK interfaces.
2. MTMAConfig: Application configuration class.
3. MTMAInitResult: SDK initialization result class.
4. MTMAUserID: User identifier model.
5. MTMAUserContact: User contact information model.
6. MTMACollectControl: Data collection control model.

Start MA Features

Supported Versions

Supported since version: 5.0.0

email and phone identifiers supported since version: 5.5.0

Independent initialization supported since version: 5.5.0

Interface Definition

• + (void)start:(MTMAConfig * )config;
  • Description:
    • Enables EngageLab MA features.
    • start is the entry point for the other interfaces and must be called before any other interface.
    • The standalone version requires an MA AppKey. Initialization does not depend on the AppPush registration result.
    • You can repeat initialization or switch MA AppKeys within the same app process, without restarting the app. Each valid call runs separately and receives its own callback; calls are not merged.
    • start: and identifyAccount: execute in call order. The next call starts only after the previous call and its callback have finished. Modifying the original configuration object while a call is queued does not affect the submitted initialization parameters.
    • An MA AppKey switch takes effect when that initialization starts executing. The current project and identity do not change while the call is queued.
    • Every initialization requires a network connection to confirm the user identity. Use the EUID returned by the current callback. If the device is offline, execution resumes when connectivity returns, and subsequent calls wait in order. For failure results, see Error Codes.
  • Parameters
    • config: Configuration class.

Call Example

              
                  MTMAConfig *config = [[MTMAConfig alloc] init];
    config.appKey = @"your MA AppKey";
    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];

            

Set User Contact Information

Supported Versions

Supported since version: 5.0.0

Interface Definition

• + (void)setUserContact:(MTMAUserContact * )contact;
  • Description:
    • Sets user contact information.
  • Parameters
    • contacts: Sets multiple contact details; currently supports email, mobile_phone, landline_phone, and whatsapp_phone. Each key must be a string of 1–256 characters. Each value must be a string; "" clears that contact detail, while a nonempty string consisting only of whitespace is invalid.

Call Example

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

            

Report Events

Supported Versions

Supported since version: 5.0.0

Interface Definition

• **+ (void)eventRecord:(MTMAEventObject )event;*
  • Description:
    • Reports an event.
  • Parameters
    • Event reporting model.
    • eventName: Name of the event to report.
    • property: Event properties; each key is a property name and each value is its property value.

Call Example

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

            

Set User Identifiers

Supported Versions

Supported since version: 5.0.0

email and phone identifiers supported since version: 5.5.0

Interface Definition

• + (void)identifyAccount:(MTMAUserID * )userID;
  • Description:
    • Sets user identifiers.
  • Parameters
    • User identifier model.
    • userID: Set the unique identifier of the logged-in user here.
    • anonymousID: When a user is not logged in but provides other identifying information, set it as the anonymous ID, such as an email address or an identifier generated by a third party.
    • email: The user’s email address, used to identify the user.
    • phone: The user’s mobile phone number, including the country or region code, such as +8613800000000.
    • Provide at least one valid identifier; not all fields are required. For details, see Identifier Types, Lengths, and Formats.

Call Example

              
                  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 and phone here are used to match user identities and may return a new EUID. They are not interchangeable with the contact information set by setUserContact:.

A callback with code=0 means a usable EUID has been obtained, not that all identifiers were set successfully. The JSON in message contains local and server-side results for individual fields, with keys user_id, anonymous_id, email, and phone. Check the code of each corresponding field; an absent field does not indicate success.

If the server does not provide per-field results, message contains only local rejection results; if there are none, it is success. A failure message is not guaranteed to be JSON. For per-field error codes, see Per-Identifier Results.

For example:

              
              code=0
message={"email":{"code":0},"phone":{"code":3003,"msg":"User identifier value exceeds the length limit"}}

            

Set Channel Contact IDs

Supported Versions

Supported since version: 5.5.0

Interface Definition

• **+ (void)setChannelValueWithChannelId:(NSInteger)channelId values:(NSArray<NSString *> )values completion:(void (^)(NSInteger code, NSString message))completion;
  • Description:
    • Sets the RID or Token for a third-party Push channel.
    • The SDK automatically manages the EngageLab AppPush channel association; this API is not needed for AppPush.
    • Not integrating AppPush, or an AppPush registration failure, does not affect other MA features.
    • For consecutive calls, the SDK sends requests in call order and invokes a separate callback for each result.
    • If the MA AppKey, project, or identity changes while a request is queued, that request returns -2.
  • Parameters
    • channelId: Third-party Push channel ID in the MA console; must be greater than 0.
    • values: Array of RIDs or Tokens for the current channel. The SDK trims leading and trailing whitespace from each value before sending. Neither the array nor the trimmed elements may be empty.
    • completion: Request result callback; code 0 indicates success.

Call Example

              
                  [MTMAService setChannelValueWithChannelId:136
                                       values:@[@"third-party Push RID or Token"]
                                   completion:^(NSInteger code, NSString *message) {
    }];

            

Set the Reporting Interval

Supported Versions

Supported since version: 5.0.0

Interface Definition

• + (void)setReportInterval:(NSInteger)interval;
  • Description:
    • Sets the data reporting interval. If this API is not called, event data is reported every 10 seconds by default.
    • The reporting interval is cached in memory. Call this API during each app lifecycle for the setting to take effect.
  • Parameters
    • interval: Reporting interval, in s (seconds).

Call Example

              
                  [MTMAService setReportInterval:10];

            

Set the Maximum Number of Cached Events

Supported Versions

Supported since version: 5.0.0

Interface Definition

• + (void)setMaxEventCacheCount:(NSInteger)count;
  • Description:
    • Sets the maximum number of cached events. The default is 50 and the maximum is 500.
    • All data is reported when the cache limit is exceeded.
  • Parameters
    • count: Maximum number of cached events.

Call Example

              
                  [MTMAService setMaxEventCacheCount:50];

            

Set the Session Timeout

Supported Versions

Supported since version: 5.0.0

Interface Definition

• + (void)setNoActiveSessionEndDurationTime:(NSInteger)interval;
  • Description:
    • Sets the session timeout. The default is 30 minutes.
    • When the app moves to the background, the session timeout timer starts. If no activity occurs within this period, the current session ends.
  • Parameters
    • interval: Timeout duration, in s (seconds).

Call Example

              
                  [MTMAService setNoActiveSessionEndDurationTime:50];

            

Get EUID

Supported Versions

Supported since version: 5.0.0

Interface Definition

• + (nullable NSString * )EUID;
  • Description:
    • Gets the EngageLab MA EUID.
    • Returns nil if the SDK has not initialized successfully.

Call Example

              
                  [MTMAService EUID];

            

Set UTM Properties

Supported Versions

Supported since version: 5.0.0

Interface Definition

• + (void)setUtmProperties:(NSDictionary * )property;
  • Description:
    • UTM properties are standard event properties. If you can identify the advertisement from which a user accessed your app, we recommend setting the UTM information. These parameters are included when events are reported. The supported UTM properties are:
      • utm_source: Campaign source.
      • utm_medium: Campaign medium.
      • utm_term: Campaign term.
      • utm_content: Campaign content.
      • utm_campaign: Campaign name.
      • utm_id: Campaign ID.

Call Example

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

            

Set User Properties

Set and Overwrite User Properties

• + (void)setProperty:(NSDictionary * )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;
  • Description:
    • Sets user properties in batches of up to 100. If any property fails SDK validation, the entire batch is not sent.
    • Property names must be NSString values, start with a lowercase letter, contain only lowercase letters, digits, and underscores, and be no longer than 50 UTF-8 bytes. They must not start with el, engagelab, or metaverse.
    • Values support NSString, finite NSNumber values, NSSet/NSArray of strings, NSDictionary (object), and NSArray<NSDictionary *> (object_array).
    • Ordinary types are overwritten if present, or created if absent. object merges subfields; object_array replaces the entire array and preserves its order.
  • Call example:

              
                 [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 indicates successful server processing
   }];

            

• + (void)setProperty:(NSString * )key to:(id)value completion:(void (^)(NSInteger code, NSString * message))completion;
  • Description:
    • Sets the value of a single user property.
    • Property names, value types, and update semantics are identical to those of the batch API.
  • Call example:

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

            

object / object_array Rules

• object must be a nonempty NSDictionary. Subfield names must be nonempty NSString values and must not contain . or $.
• object subfield values support NSString, finite NSNumber values, NSSet/NSArray of strings, and NSNull. Nested object or object_array values are not supported.
• Calling setProperty again for an object merges only the supplied subfields. Omitted subfields remain unchanged. A subfield value of NSNull removes that subfield.
• object_array must be an NSArray<NSDictionary *>. Every object must be nonempty and follow the same subfield rules. Calling setProperty again replaces the entire array.
• Each object_array element must retain at least one subfield with a value other than NSNull. Objects whose subfield values are all NSNull are not allowed.
• An empty array can clear an existing array property. When creating a property for the first time, an empty array alone cannot distinguish a string list from an object_array. Use a nonempty array of objects to create an object_array.
• NSNull is allowed only as a subfield value within object/object_array. A top-level NSNull cannot delete an entire property; use deleteProperty:completion: to delete the property.

Examples of partially updating an object and removing a subfield:

              
              // Update only profile.score; leave profile.city unchanged
[MTMAService setProperty:@"profile"
                      to:@{ @"score": @200 }
              completion:completion];

// Remove only profile.city
[MTMAService setProperty:@"profile"
                      to:@{ @"city": NSNull.null }
              completion:completion];

            

Partially Update an object_array Element

Supported since version: 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;
  • Description:
    • Locates an object in an object_array through a unique subfield, then merges the subfields in values.
    • The subfield specified by identifierKey must already be defined in server metadata and must have type string or number. identifierValue must be a matching NSString or a non-Boolean, finite NSNumber and must match exactly one element in the current array.
    • values must be a nonempty dictionary that does not contain identifierKey or nested object/object_array values. Omitted fields remain unchanged; NSNull removes the corresponding subfield.
    • The property must already be defined as object_array in server metadata, and the current user must already have a value for it. To create it initially, pass a nonempty array of objects to setProperty:to:.
    • If the property is undefined, or defined but has no value for the current user, the server returns code=0 without making changes. code=0 only indicates successful request processing; check the MA console or server-side user properties to confirm the actual changes.
    • If the array exists but there is no match, there are multiple matches, the identifier field type differs, or a subfield does not meet its metadata definition, the server returns a failure code. Other elements are neither created nor modified.
  • Call example:

              
              // For the object with id == home, update city to Tokyo and remove zip
[MTMAService updateObjectArrayProperty:@"addresses"
                         identifierKey:@"id"
                       identifierValue:@"home"
                                values:@{
                                    @"city": @"Tokyo",
                                    @"zip": NSNull.null
                                }
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

Append an object_array Element

Supported since version: 5.5.0

• **+ (void)addObjectArrayProperty:(NSString )key object:(NSDictionary<NSString *, id> )object completion:(void (^)(NSInteger code, NSString * message))completion;
  • Description:
    • Appends one object to the end of an object_array without affecting existing elements. This differs from passing an entire array to setProperty:to:, which replaces the whole array.
    • object must be a nonempty NSDictionary with at least one subfield whose value is not NSNull. It follows the same subfield rules as object and does not support nested object/object_array values.
    • The property must already be defined as object_array in server metadata. If it is undefined, the server returns code=0 without making changes. First create it by passing a nonempty array of objects to setProperty:to:.
    • If the property is defined but the current user has no value for it, this API creates an array containing this one element.
  • Call example:

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

            

Remove an object_array Element

Supported since version: 5.5.0

• **+ (void)removeObjectArrayProperty:(NSString )key identifierKey:(NSString )identifierKey identifierValue:(id)identifierValue completion:(void (^)(NSInteger code, NSString * message))completion;
  • Description:
    • Locates and removes an entire array element through a unique subfield. To remove only a subfield within an element, pass NSNull for that subfield to updateObjectArrayProperty:.
    • The constraints on identifierKey / identifierValue are identical to those of updateObjectArrayProperty:: the subfield must already be defined in metadata, must have type string or number, and must match exactly one element in the current array.
    • If the property is not defined on the server, the current user has no value for it, or there is no matching element, the server ignores the request and returns code=0. Confirm the actual changes in the MA console or server-side user properties.
    • If there are multiple matches or the identifier field type differs, the server returns a failure code and does not delete other elements.
  • Call example:

              
              // Delete the address with id == office
[MTMAService removeObjectArrayProperty:@"addresses"
                         identifierKey:@"id"
                       identifierValue:@"office"
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

Increment User Properties

• **+ (void)increaseProperty:(NSString )key by:(NSNumber )amount completion:(void (^)(NSInteger code, NSString * message))completion;
  • Description:
    • Adds a value to a numeric user property, accumulating reported values, such as total spending.
    • This API applies only to user properties of type NSNumber; otherwise it is ignored. If the property does not exist, its initial value is treated as 0.
  • Call example:

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

    }];

            

• **+ (void)increaseProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;*
  • Description:
    • Adds values to multiple numeric user properties, accumulating reported values, such as total spending.
    • This API applies only to user properties of type NSNumber; otherwise it is ignored. If the property does not exist, its initial value is treated as 0.
  • Call example:

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

    }];

            

Append Values to User Properties

• **+ (void)addProperty:(NSString )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion
  • Description:
    • Adds values to a property of type NSSet or NSArray.
    • As described above, the NSSet or NSArray elements must be NSString values; otherwise the operation is ignored. If the property does not yet exist, an empty NSSet or NSArray is initialized.
  • Call example:

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

    }];

            

• **+ (void)addProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger, NSString * _Nonnull))completion;*
  • Description:
    • Adds values to multiple properties of type NSSet or NSArray.
    • As described above, the NSSet or NSArray elements must be NSString values; otherwise the operation is ignored. If the property does not yet exist, an empty NSSet or NSArray is initialized.
  • Call example:

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

    }];

            

Remove Values from User Properties

• **+ (void)removeProperty:(NSString * )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion;*
  • Description:
    • Removes values from a property of type NSSet or NSArray.
    • content must be an NSSet or NSArray whose elements are NSString values.
  • Call example:

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

    }];

            

Delete User Properties

Supported Versions

Supported since version: 5.0.0

Interface Definition

• + (void)deleteProperty:(NSString * )key completion:(void (^)(NSInteger code, NSString * message))completion;
  • Description:
    • Deletes the entire contents of a user property, including ordinary types, object, and object_array.
    • If the user property does not exist, the operation is ignored.

Call Example

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

    }];

            

Control Data Collection

Supported Versions

Supported since version: 5.0.0

Interface Definition

• **+ (void)setCollectControl:(MTMACollectControl )control;*
  • Description:
    • Controls whether the data items in MTMACollectControl are collected.

Call Example

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

            

MTMAConfig Class

Application configuration class. Its properties are described below:

MTMAInitResult Class

SDK initialization result object returned by resultCompletion. You do not need to create or invoke it separately. Its properties are described below:

MTMAUserID Class

User identifier model. Pass it through MTMAConfig.userID during initialization or through identifyAccount: at runtime.

All four identifiers are optional. Leading and trailing spaces are trimmed; empty values and 0/null/undefined/nan (case-insensitive) are treated as omitted. They do not participate in matching and do not produce per-field results. The following constraints apply to values retained after this cleanup:

Fields that are not NSString or have an invalid format are excluded with 3013; overlength fields are excluded with 3003. These results are recorded, and the remaining valid fields are still submitted. If no valid field remains, initialization continues without identifiers, while identifyAccount: returns -3 without sending a request. The SDK does not modify the caller’s object; email is converted to lowercase by the server.

On successful initialization, userID.completion returns code=0. message is an empty string or JSON containing only locally rejected fields; it does not include server-side per-field results and cannot confirm that all identifiers have been bound. Use config.resultCompletion as the authoritative SDK initialization result; this callback does not include per-identifier JSON. For runtime callbacks, see Set User Identifiers.

MTMACollectControl Class

User data collection control model. Its properties are described below:

MTMAUserContact Class

User channel model. Its properties are described below.
Omitting a value or setting it to nil leaves it unchanged. Setting it to the empty string "" clears that contact detail. A nonempty string consisting only of whitespace is invalid.

MTMAEventObject Class

Custom event object class. Its properties are described below: