Guía de API de iOS

Versión aplicable

La versión del SDK de iOS de MTPush a la que corresponde este documento es v3.0.0 o posterior.

Configurar centro de datos

Descripción de la función

Esta función se utiliza para hacer coincidir el centro de datos que se ha seleccionado en el portal de EngageLab. Asegúrese de que el centro de datos configurado sea coherente con el seleccionado en el portal.
Si no se configura, el SDK utilizará el nodo predeterminado del centro de datos de Singapur.

En v4.3.5 y versiones posteriores, esta interfaz no es válida. Los desarrolladores no necesitan llamar manualmente a esta interfaz para configurar el centro de datos. El SDK hará coincidir automáticamente el centro de datos correspondiente en función del appkey.

Versiones compatibles

Versión inicial compatible: v4.3.0

Versión no válida

Versión a partir de la cual expira: v4.3.5

Definición de la interfaz

              
              + (void)setSiteName:(NSString *)siteName;

            

Descripción de parámetros

• siteName
  • Nombre del centro de datos

Instrucciones de llamada

Llamar a esta interfaz antes de llamar a la interfaz de inicialización (setupWithOption:channel:apsForProduction:advertisingIdentifier).

API de etiquetas y alias (iOS)

Descripción de la función

Las siguientes API permiten gestionar alias y etiquetas (tags).

Estas API pueden llamarse desde cualquier parte de la app.

Alias

Asigne un alias a un usuario que haya instalado la app para identificarlo como destinatario de futuros mensajes push. Solo se puede asignar un alias a cada usuario.

Se recomienda asignar alias distintos a los usuarios de una misma app para poder identificarlos de forma única.

El sistema permite vincular cada alias a un solo usuario.

Por ejemplo, en un juego que requiere iniciar sesión, puede utilizar userid como alias. Si el usuario no ha jugado durante 3 días, puede llamar a la API del servidor con ese userid para enviarle una notificación.

Etiquetas (tags)

Asigne etiquetas a los usuarios que hayan instalado la app para enviar mensajes push en lote según esas etiquetas.

Cada usuario puede tener varias etiquetas.

Por ejemplo: game, old_page, women

Añadir etiquetas

Esta API añade etiquetas y devuelve el resultado en el bloque de callback.

Note：Esta interfaz añade etiquetas; no reemplaza las existentes.

Versiones compatibles

Disponible desde v3.5.0.

Definición de la interfaz

              
              + (void)addTags:(NSSet<NSString *> *)tags
 completion:(MTPushTagsOperationCompletion)completion
        seq:(NSInteger)seq;

            

Parámetros

• tags

  • No puede ser nil ni un conjunto vacío ([NSSet set]).
  • Los elementos del conjunto deben ser de tipo NSString.
  • Debe configurar al menos una etiqueta por llamada.
  • Caracteres válidos para las etiquetas: letras (distinguen mayúsculas de minúsculas), números, guiones bajos, caracteres chinos y los caracteres especiales @!#$&*+=.|.
  • Límites: 40 bytes por etiqueta y un máximo de 1000 etiquetas, con una longitud total de hasta 5 K bytes. Calcule la longitud con codificación UTF-8.
  • Cada dispositivo admite hasta 1000 etiquetas. No hay límite para el número total de etiquetas de la app.

• completion

  • El callback devuelve las etiquetas correspondientes y el código de estado: 0 indica éxito; para otros valores, consulte la definición de códigos de error. seq es el número de secuencia enviado en la llamada.

• seq

  • Número de secuencia de la solicitud, devuelto sin cambios en el callback.

Reemplazar etiquetas

Esta API configura las etiquetas y devuelve el resultado en el bloque de callback.

Note：Esta interfaz reemplaza todas las etiquetas configuradas anteriormente; no añade etiquetas a las existentes.

Versiones compatibles

Disponible desde v3.5.0.

Definición de la interfaz

              
              + (void)setTags:(NSSet<NSString *> *)tags
 completion:(MTPushTagsOperationCompletion)completion
        seq:(NSInteger)seq;

            

Parámetros

• tags

  • No puede ser nil ni un conjunto vacío ([NSSet set]).
  • Los elementos del conjunto deben ser de tipo NSString.
  • Debe configurar al menos una etiqueta por llamada.
  • Caracteres válidos para las etiquetas: letras (distinguen mayúsculas de minúsculas), números, guiones bajos, caracteres chinos y los caracteres especiales @!#$&*+=.|.
  • Límites: 40 bytes por etiqueta y un máximo de 1000 etiquetas, con una longitud total de hasta 5 K bytes. Calcule la longitud con codificación UTF-8.
  • Cada dispositivo admite hasta 1000 etiquetas. No hay límite para el número total de etiquetas de la app.

• completion

  • El callback devuelve las etiquetas correspondientes y el código de estado: 0 indica éxito; para otros valores, consulte la definición de códigos de error. seq es el número de secuencia enviado en la llamada.

• seq

  • Número de secuencia de la solicitud, devuelto sin cambios en el callback.

Eliminar etiquetas

Esta API elimina etiquetas y devuelve el resultado en el bloque de callback.

Versiones compatibles

Disponible desde v3.5.0.

Definición de la interfaz

              
              + (void)deleteTags:(NSSet<NSString *> *)tags
 completion:(MTPushTagsOperationCompletion)completion
        seq:(NSInteger)seq;

            

Parámetros

• tags

  • No puede ser nil ni un conjunto vacío ([NSSet set]).
  • Los elementos del conjunto deben ser de tipo NSString.
  • Debe eliminar al menos una etiqueta por llamada.
  • Caracteres válidos para las etiquetas: letras (distinguen mayúsculas de minúsculas), números, guiones bajos, caracteres chinos y los caracteres especiales @!#$&*+=.|.
  • Límites: 40 bytes por etiqueta y un máximo de 1000 etiquetas para eliminar, con una longitud total de hasta 5 K bytes. Calcule la longitud con codificación UTF-8.

• completion

  • El callback devuelve las etiquetas correspondientes y el código de estado: 0 indica éxito; para otros valores, consulte la definición de códigos de error. seq es el número de secuencia enviado en la llamada.

• seq

  • Número de secuencia de la solicitud, devuelto sin cambios en el callback.

Borrar todas las etiquetas

Esta API borra todas las etiquetas y devuelve el resultado en el bloque de callback.

Versiones compatibles

Disponible desde v3.5.0.

Definición de la interfaz

              
              + (void)cleanTags:(MTPushTagsOperationCompletion)completion
        seq:(NSInteger)seq;

            

Parámetros

• completion

  • El valor tags devuelto en el callback es nil. El código de estado 0 indica éxito; para otros valores, consulte la definición de códigos de error. seq es el número de secuencia enviado en la llamada.

• seq

  • Número de secuencia de la solicitud, devuelto sin cambios en el callback.

Consultar etiquetas

Esta API obtiene todas las etiquetas y devuelve el resultado en el bloque de callback.

Versiones compatibles

Disponible desde v3.5.0.

Definición de la interfaz

              
              + (void)getAllTags:(MTPushTagsOperationCompletion)completion
        seq:(NSInteger)seq;

            

Parámetros

• completion

  • El valor tags del callback contiene el resultado de la consulta. El código de estado 0 indica éxito; para otros valores, consulte la definición de códigos de error. seq es el número de secuencia enviado en la llamada.

• seq

  • Número de secuencia de la solicitud, devuelto sin cambios en el callback.

Verificar una etiqueta

Esta API verifica si la etiqueta indicada ya está configurada.

Versiones compatibles

Disponible desde v3.5.0.

Definición de la interfaz

              
              + (void)validTag:(NSString *)tag
 completion:(MTPushTagValidOperationCompletion)completion
        seq:(NSInteger)seq;

            

Parámetros

• tag

  • No puede ser nil ni una cadena vacía.
  • Caracteres válidos para las etiquetas: letras (distinguen mayúsculas de minúsculas), números, guiones bajos, caracteres chinos y los caracteres especiales @!#$&*+=.|.
  • Límite: 40 bytes por etiqueta, calculados con codificación UTF-8.

• completion

  • El callback devuelve la etiqueta correspondiente y el código de estado: 0 indica éxito; para otros valores, consulte la definición de códigos de error. seq es el número de secuencia enviado en la llamada.
  • Compruebe isBind en el callback: YES indica que la etiqueta ya está configurada.

• seq

  • Número de secuencia de la solicitud, devuelto sin cambios en el callback.

Tags Block

              
              typedef void (^MTPushTagsOperationCompletion)(NSInteger iResCode, NSSet *iTags, NSInteger seq);
typedef void (^MTPushTagValidOperationCompletion)(NSInteger iResCode, NSSet *iTags, NSInteger seq, BOOL isBind);

            

Configurar alias

Esta API configura el alias.

Versiones compatibles

Disponible desde v3.5.0.

Definición de la interfaz

              
              + (void)setAlias:(NSString *)alias
  completion:(MTPushAliasOperationCompletion)completion
         seq:(NSInteger)seq;

            

Parámetros

• alias
  • No puede ser nil ni una cadena vacía. @""
  • Cada llamada configura un alias válido y reemplaza el anterior.
  • Caracteres válidos para el alias: letras (distinguen mayúsculas de minúsculas), números, guiones bajos, caracteres chinos y los caracteres especiales @!#$&*+=.|.
  • Límite: 40 bytes por alias, calculados con codificación UTF-8.

• completion

  • El callback devuelve el alias correspondiente y el código de estado: 0 indica éxito; para otros valores, consulte la definición de códigos de error. seq es el número de secuencia enviado en la llamada.

• seq

  • Número de secuencia de la solicitud, devuelto sin cambios en el callback.

Eliminar alias

Esta API elimina el alias y devuelve el resultado en el bloque de callback.

Versiones compatibles

Disponible desde v3.5.0.

Definición de la interfaz

              
              + (void)deleteAlias:(MTPushAliasOperationCompletion)completion
            seq:(NSInteger)seq;

            

Parámetros

• completion

  • El valor tags devuelto en el callback es nil. El código de estado 0 indica éxito; para otros valores, consulte la definición de códigos de error. seq es el número de secuencia enviado en la llamada.

• seq

  • Número de secuencia de la solicitud, devuelto sin cambios en el callback.

Consultar alias

Esta API consulta el alias actual y devuelve el resultado en el bloque de callback.

Versiones compatibles

Disponible desde v3.5.0.

Definición de la interfaz

              
              + (void)getAlias:(MTPushAliasOperationCompletion)completion
         seq:(NSInteger)seq;

            

Parámetros

• completion

  • El valor tags del callback contiene el resultado de la consulta. El código de estado 0 indica éxito; para otros valores, consulte la definición de códigos de error. seq es el número de secuencia enviado en la llamada.

• seq

  • Número de secuencia de la solicitud, devuelto sin cambios en el callback.

Alias Block

              
              typedef void (^MTPushAliasOperationCompletion)(NSInteger iResCode, NSString *iAlias, NSInteger seq);

            

Mensajería in-app

Ejemplo de uso

Instrucciones de uso

Utilizar las interfaces pageEnterTo: y pageLeave: conjuntamente. Llamar a pageEnterTo: al entrar en una página y a pageLeave: al salir de la página.

Obtener RegistrationID

Obtener registrationID

Llamar a esta API para obtener el RegistrationID de la aplicación. El valor correspondiente solo se devuelve si la aplicación se registra correctamente en el servidor de MTPush; de lo contrario, se devuelve una cadena vacía.

Configurar el badge

Descripción de la función

Para enviar mensajes push, basta con configurar el badge +1; EngageLab incrementará automáticamente en +1 el valor de badge almacenado en el servidor para cada usuario y luego lo enviará al usuario.

Registrar/actualizar notificaciones locales

Descripción de obtención

Asignar request.requestIdentifier en request como parámetro para actualizar el push existente; de lo contrario, se registra un nuevo push.

Configuración del nivel de registro

Habilitar el modo de depuración

Descripción de obtención

Cuando se necesite más información de depuración, Llamar a esta API para habilitar el modo Debug.

Deshabilitar la información de registro

Descripción de obtención

Llamar a esta API cuando no se necesite información de depuración (se recomienda llamar a esta API al publicar para ocultar la información de registro y ahorrar rendimiento).

Configurar el modo de cifrado TCP

Instrucciones de llamada

Llamar a este método antes de inicializar la interfaz.

Desactivar el servicio push (turnOffPush)

Versión compatible

Disponible desde MTPush iOS SDK v5.4.3.

Descripción

Esta API impide la reconexión automática, cierra la conexión persistente, detiene la recopilación y el envío de información del cliente, detiene los mensajes dentro de la aplicación y anula el registro del token APNs actual. Mientras el push está desactivado, no están disponibles las API que dependen de la red push o de la identidad de registro. Las API locales de notificaciones, permisos, callbacks y registro siguen disponibles.

Definición de la API

              
              + (void)turnOffPush:(nullable MTPushRegistrationCompletion)completion;

            

Ejemplo de código

              
              [MTPushService turnOffPush:^(NSInteger code, NSString *message) {
    NSLog(@"turnOffPush code: %ld, message: %@", (long)code, message);
}];

            

Parámetros

• completion: Optional result callback; it runs on the main thread.

Callback

El callback se ejecuta en el hilo principal:

Notas de uso

turnOffPush no devuelve 6052. Después de desactivar push, las API que requieren red o identidad de registro utilizan 6052 para indicar que la operación no está disponible. El simulador de iOS no admite la anulación de APNs y solo escribe un aviso en el registro.

Reactivar el servicio push (turnOnPush)

Versión compatible

Disponible desde MTPush iOS SDK v5.4.3.

Descripción

Reactiva el servicio con nuevos parámetros de inicialización, restaura la recopilación y el envío de información, los mensajes dentro de la aplicación y la conexión persistente, y registra de nuevo el token APNs. Pase el nuevo deviceToken del callback de AppDelegate a registerDeviceToken:. La API retorna inmediatamente y no proporciona callback de resultado.

Definición de la API

              
              + (void)turnOnPush:(NSString *)appKey
           channel:(nullable NSString *)channel
  apsForProduction:(BOOL)isProduction
advertisingIdentifier:(nullable NSString *)advertisingId;

            

Ejemplo de código

              
              [MTPushService turnOnPush:@"your_app_key"
                  channel:@"App Store"
         apsForProduction:YES
  advertisingIdentifier:nil];

            

Parámetros

• appKey: Nuevo EngageLab AppKey; no puede estar vacío.
• channel: Canal de distribución; puede estar vacío.
• isProduction: Entorno APNs; YES para producción y NO para desarrollo.
• advertisingId: Identificador publicitario; puede estar vacío.

Función de difusión por voz

Configurar appGroupId

Instrucciones de llamada

Llamar a esta interfaz antes de la interfaz de inicialización.

Configurar si se habilita la difusión por voz

Instrucciones de llamada

Llamar a esta interfaz antes de la interfaz de inicialización. Está deshabilitada de forma predeterminada.

Configurar si se debe restablecer RegistrationID al sustituir el dispositivo

Instrucciones de uso

Llamar a este método antes de la interfaz de inicialización. Está deshabilitado de forma predeterminada.

LiveActivity

Informar de liveActivity PushToStartToken

Llamar a esta API para informar del pushToStartToken de una liveActivity y devolver el resultado en el bloque.

Informar de liveActivity PushToken (actualizar token)

Llamar a esta API para informar del PushToken de una liveActivity concreta y devolver el resultado en el bloque.

Informar visualización y clic de mensaje personalizado

Descripción de la función

• Llamar a reportCustomDisplay: tras mostrar visualmente el mensaje personalizado al usuario; solo los mensajes reportados explícitamente cuentan para las estadísticas de visualización.
• Llamar a reportCustomClick: después de que el usuario interactúe con (haga clic en) el mensaje personalizado.
• messageId se obtiene del callback del mensaje personalizado mediante userInfo[@"_j_msgid"].

Definición de interfaz

Objective-C

              
              /*!
 * @abstract Informar visualización de mensaje personalizado
 *
 * @param messageId  ID del mensaje obtenido del callback del mensaje personalizado userInfo[@"_j_msgid"], no debe ser nil (tipo NSNumber; usar stringValue para convertir a NSString)
 *
 * @discussion Llamar tras completar la visualización del mensaje personalizado. La llegada del mensaje ≠ visualización; solo se contabiliza cuando se reporta explícitamente.
 */
+ (void)reportCustomDisplay:(NSString *)messageId;

/*!
 * @abstract Informar clic en mensaje personalizado
 *
 * @param messageId  ID del mensaje obtenido del callback del mensaje personalizado userInfo[@"_j_msgid"], no debe ser nil (tipo NSNumber; usar stringValue para convertir a NSString)
 *
 * @discussion Llamar tras el clic del usuario en el mensaje personalizado. Abrir la app ≠ clic; debe ser activado por la interacción del usuario con el mensaje.
 */
+ (void)reportCustomClick:(NSString *)messageId;

            

Ejemplo

Objective-C

              
              // Tras mostrar el mensaje personalizado
[MTPushService reportCustomDisplay:[userInfo[@"_j_msgid"] stringValue]];

// Tras el clic del usuario en el mensaje personalizado
[MTPushService reportCustomClick:[userInfo[@"_j_msgid"] stringValue]];

            

Swift

              
              // Tras mostrar el mensaje personalizado
MTPushService.reportCustomDisplay((userInfo["_j_msgid"] as? NSNumber)?.stringValue)

// Tras el clic del usuario en el mensaje personalizado
MTPushService.reportCustomClick((userInfo["_j_msgid"] as? NSNumber)?.stringValue)

            

Push VoIP

Descripción de la función

A partir de iOS 8, las notificaciones VoIP basadas en PushKit permiten activar una app cuyo proceso ha finalizado y ejecutar código.

Advertencia: desde iOS 13, Apple no permite utilizar PushKit para escenarios distintos de llamadas VoIP. Para usar PushKit, debe integrar las interfaces de CallKit.

Versión compatible

Disponible desde v4.4.0.

Registrar el token

registerVoipToken:

Envía el token VoIP al servidor de EngageLab.

Definición de la interfaz

              
              + (void)registerVoipToken:(NSData *)voipToken;

            

Parámetros

• voipToken: token VoIP devuelto por el sistema.

Procesar mensajes VoIP

handleVoipNotification:

Procesa el mensaje VoIP recibido para registrar estadísticas de entrega VoIP.

Definición de la interfaz

              
              + (void)handleVoipNotification:(NSDictionary *)remoteInfo;

            

Parámetros

• remoteInfo: contenido del mensaje.

Interfaces de Notification Service Extension

Versiones compatibles

Notification Service Extension SDK v3.0.0 y posteriores.

Descripción de la función

Utilice el SDK de Notification Service Extension para informar de la entrega de notificaciones push.

Configurar appkey

Esta interfaz debe llamarse de antemano para configurar appkey.

Definición de la interfaz

              
              + (void)mtpushSetAppkey:(NSString *)appkey

            

Parámetros

• appkey: debe coincidir con el appkey del SDK MTPush de la app principal.

Estadísticas de visualización de mensajes

Llame a esta interfaz de estadísticas de entrega para informar de los datos de MTPush incluidos en el cuerpo del mensaje APNs.

Definición de la interfaz

              
              + (void)mtpushReceiveNotificationRequest:(UNNotificationRequest *)request with:(void (^)(void))completion

            

Parámetros

• request: UNNotificationRequest.
• completion: callback del informe de entrega. Realice las operaciones de visualización de APNs en este callback.

Deshabilitar los registros

Los registros están habilitados de forma predeterminada. Se recomienda deshabilitarlos al publicar la app para reducir operaciones de E/S innecesarias.

Definición de la interfaz

              
              + (void)setLogOff

            

Difusión por voz

Esta función es compatible con iOS 14 y versiones posteriores.

Versión compatible

Disponible desde v4.3.4.

Configurar appGroupId

              
              + (void)mtpushSetAppGroupId:(NSString *)appGroupId;

            

Parámetros

• appGroupId: debe coincidir con el valor configurado en la app principal mediante + (void)setAppGroupId:(NSString *)appGroupId;.

Procesar notificaciones de voz

Llame a esta interfaz de estadísticas de entrega para informar de los datos de MTPush incluidos en el cuerpo del mensaje APNs.

Definición de la interfaz

              
              + (void)handleVoice:(UNNotificationRequest *)request with:(void (^)(NSString *soundName))completion;

            

Parámetros

• request: UNNotificationRequest.
• completion: callback que se ejecuta al finalizar el procesamiento de la notificación de voz. Si se procesa correctamente, devuelve el nombre del sonido soundName; utilícelo para reemplazar el valor de UNNotificationRequest.content.sound.

Ejemplo de uso

Objective-C

              
              - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {

  UNMutableNotificationContent *bestAttemptContent = [request.content mutableCopy];

  [MTNotificationExtensionService mtpushSetAppGroupId:@"xxx"];
  [MTNotificationExtensionService setSiteName:@"SU_SITE_NAME"];  // Desde v4.3.5 no es necesario configurar el centro de datos manualmente
  [MTNotificationExtensionService mtpushSetAppkey:@"SU_APPKEY"];

  // Procesar el archivo de voz
  [MTNotificationExtensionService handleVoice:request with:^(NSString *soundName) {
      if (soundName && soundName.length >= 0 ) {
        // Tras procesar el archivo de voz, configure sound con el nombre del archivo resultante
        bestAttemptContent.sound = [UNNotificationSound soundNamed:soundName];
      }
      // Continuar llamando a la API de estadísticas de push
    [MTNotificationExtensionService mtpushReceiveNotificationRequest:request with:^ {
      NSLog(@"apns upload success");
      self.contentHandler(bestAttemptContent);
    }];

  }];

}

            

Swift

              
              func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
    var bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent) ?? request.content

    MTNotificationExtensionService.mtpushSetAppGroupId("xxx")
    MTNotificationExtensionService.setSiteName("SU_SITE_NAME") // Desde v4.3.5 no es necesario configurar el centro de datos manualmente
    MTNotificationExtensionService.mtpushSetAppkey("SU_APPKEY")

    // Procesar el archivo de voz
    MTNotificationExtensionService.handleVoice(request) { (soundName) in
        if let soundName = soundName, soundName.count >= 0 {
            // Tras procesar el archivo de voz, configure sound con el nombre del archivo resultante
            bestAttemptContent.sound = UNNotificationSound(named: UNNotificationSoundName(soundName))
        }
        // Continuar llamando a la API de estadísticas de push
        MTNotificationExtensionService.mtpushReceiveNotificationRequest(request) {
            print("apns upload success")
            self.contentHandler(bestAttemptContent)
        }
    }
}