Guía de integración del SDK MA para iOS

Versiones aplicables

Esta guía se aplica al SDK MTMA independiente v5.5.0 y posteriores. Actualmente, el SDK solo admite dispositivos con iOS 10 o superior.

Para versiones anteriores a 5.5.0, consulte la guía de integración anterior a 5.5.0.

A partir de v5.5.0, el SDK MTMA puede integrarse e inicializarse de forma independiente, sin depender de AppPush. MTMA y AppPush tienen código independiente, aunque el SDK oficial sigue distribuyéndose en el paquete combinado de Push. Puede integrar únicamente MTMA de ese paquete, o integrar MTMA y MTPush juntos.

Configurar el proyecto

Importar el SDK

Importación mediante CocoaPods

              
                  pod 'MTMA'

    Nota: Si no puede importar la última versión, ejecute pod repo update para actualizar el repositorio local de pods y vuelva a ejecutar pod 'MTMA'.

            

• Para instalar una versión específica, utilice lo siguiente (ejemplo con MTMA 5.5.0):

              
                  pod 'MTMA', '5.5.0'

            

Importación manual

• Descomprima el paquete del SDK. En Xcode, seleccione “Add files to 'Your project name'...” y añada MTMA-ios-x.x.x.xcframework al directorio del proyecto.

Manifiesto de privacidad

El paquete del SDK incluye PrivacyInfo.xcprivacy. Si no se incorpora automáticamente a la aplicación empaquetada, utilice este archivo como referencia para completar el manifiesto de privacidad de la aplicación.

Inicializar el SDK

El SDK MTMA independiente se inicializa con la MA AppKey, sin esperar a que AppPush se inicialice o se registre correctamente.

Antes de inicializarlo, configure en la consola de MA el iOS Bundle ID de la fuente de datos correspondiente a la MA AppKey del proyecto actual, de modo que coincida con el de la aplicación, y habilite la fuente de datos. El SDK lee automáticamente el Bundle Identifier de la aplicación; no es necesario configurarlo por separado. La inicialización falla si no está vinculado o no coincide.

Si la inicialización devuelve 55004 y el message indica packageName is not bound, compruebe la vinculación anterior.

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

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

    return YES;
}

            

Descripción de algunos parámetros

• appKey
  • MA AppKey obligatoria, formada por 24 letras o dígitos.
  • La MA AppKey y la Push AppKey son independientes y pueden ser iguales o distintas.
• resultCompletion
  • Callback del resultado de inicialización. Utilice result.isSuccess para comprobar si ha tenido éxito; en caso de fallo, result.code y result.message permiten investigar la causa.
  • Consulte el objeto devuelto y sus campos en Clase MTMAInitResult.

La inicialización requiere conexión a la red. Si el dispositivo está sin conexión, el SDK espera a que se restablezca y continúa automáticamente, sin devolver inmediatamente un fallo en el callback.

El SDK permite repetir la inicialización y cambiar la MA AppKey. Cada llamada válida se ejecuta en orden y recibe su propio callback. Consulte las reglas en Iniciar la función MA.

Establecer identificadores de usuario durante la inicialización

Para establecer identificadores de usuario durante la inicialización, páselos mediante MTMAConfig.userID. userID, anonymousID, email y phone son opcionales. El siguiente ejemplo utiliza userID:

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

MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = @"Su MA AppKey";
config.userID = userID;
config.resultCompletion = ^(MTMAInitResult *result) {
    if (result.isSuccess) {
        NSLog(@"MTMA se ha inicializado correctamente");
    } else {
        NSLog(@"Error al inicializar MTMA, code=%ld, message=%@", (long)result.code, result.message);
    }
};
[MTMAService start:config];

            

También puede inicializar el SDK sin establecer identificadores de usuario. Una inicialización correcta no garantiza que todos los identificadores se hayan establecido correctamente. Consulte la validación de campos y los callbacks en Clase MTMAUserID.

Escenarios de inicialización

Utilizar AppPush conjuntamente

Al configurar la fuente de datos móvil en la consola de MA, seleccione el uso conjunto con AppPush y la aplicación AppPush que realmente integra. Inicialice AppPush con la AppKey de esa aplicación.

MTMA y AppPush se inicializan por separado, sin un orden de inicialización obligatorio.

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

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

            

Cuando AppPush se registra correctamente y obtiene el Push RegistrationID, el SDK MTMA configura automáticamente el canal AppPush. La falta de registro de AppPush o un fallo al configurar el canal no afectan a la inicialización de MTMA ni a la recopilación y el envío de eventos.

Establecer los ID de contacto del canal

Para utilizar Push de terceros, establezca su RID o Token después de que MTMA se haya inicializado correctamente.

              
              [MTMAService setChannelValueWithChannelId:136
                                   values:@[@"RID o Token de Push"]
                               completion:^(NSInteger code, NSString *message) {
    NSLog(@"result：%ld - %@", code, message);
}];

            

Descripción de algunos parámetros

• channelId
  • ID del canal Push de terceros configurado en la consola de MA; debe ser mayor que 0.
• values
  • Array de RID o Token del Push de terceros. Ni el array ni sus elementos pueden estar vacíos.
  • Si el RID o Token cambia, vuelva a llamar a la interfaz para actualizarlo.

Esta interfaz se utiliza únicamente para Push de terceros. Consulte las restricciones en Establecer los ID de contacto del canal.

Actualizar desde versiones anteriores

• El SDK oficial sigue distribuyéndose en el paquete combinado de Push. Los proyectos que ya integran AppPush y MTMA juntos no necesitan cambiar el método de importación manual.
• Después de actualizar a v5.5.0, es obligatorio establecer appKey en MTMAConfig.
• MTMAConfig.userID y los cuatro campos de identificadores de usuario son propiedades opcionales. Trátelos como opcionales al integrar con Swift.
• Se conserva el callback completion anterior, pero se recomienda utilizar resultCompletion. Si establece ambos, solo se invoca resultCompletion.
• Push RegistrationID y MA RID son identidades de dispositivo distintas y no son intercambiables.