Guía de integración de iOS

El SDK de iOS de Verificación de comportamiento (Behavioral Verification) de EngageLab está diseñado para desarrolladores que realizan integraciones con desarrollo de cliente nativo iOS. El SDK no depende de bibliotecas de terceros.

Visión general del producto

Requisitos de entorno

Importación del SDK

1. Si se va a añadir el SDK manualmente, arrastrar el archivo GTCaptcha4.framework obtenido de la descarga al proyecto, asegurarse de que Copy items if needed esté seleccionado.

   Utilizar el método Linked Frameworks and Libraries para importar el framework. Tras arrastrar GTCaptcha4.framework al proyecto, asegurarse de que el archivo .framework se haya añadido en PROJECT -> Build Phases -> Linked Frameworks and Libraries.

   

   El SDK proporciona un formato XCFramework, ubicado en el directorio SDK -> XCFramework dentro de los archivos descargados como GTCaptcha4.xcframework.

2. Para Category en bibliotecas estáticas, añadir -ObjC en Other Linker Flags, dentro de Build Settings, para el target correspondiente.

   

3. También se debe incluir GT4Captcha4.Bundle en el proyecto; de lo contrario, la verificación no funcionará. Arrastrar GTCaptcha4.Bundle desde el directorio del SDK al proyecto.

   

En la WWDC23, Apple anunció nuevas políticas de privacidad para aplicaciones (incluidos los SDK), con una sesión dedicada Get started with privacy manifests - WWDC23 - Videos - Apple Developer. El 27 de julio, Apple publicó una actualización indicando que, a partir de otoño de 2023, si las aplicaciones recién subidas utilizan API relacionadas sin proporcionar un manifiesto de privacidad, se recibirá una notificación por correo electrónico. A partir de primavera de 2024, los manifiestos de privacidad serán obligatorios. Para las API implicadas y los motivos de uso, consultar: Describing use of required reason API | Apple Developer Documentation. Si el motivo de uso no figura en la lista, se puede enviar directamente una explicación específica de uso.

Para crear un nuevo manifiesto de privacidad, consultar Privacy manifest files | Apple Developer Documentation.

El SDK de iOS de Verificación de comportamiento utiliza algunas funciones para obtener la capacidad de disco y la información de detección del entorno con fines de control de riesgos, lo que implica las categorías NSPrivacyAccessedAPICategoryDiskSpace y NSPrivacyAccessedAPICategoryFileTimestamp. Se deja constancia de ello mediante el presente texto.

Interfaz de configuración

Consultar el Product Structure Process de Verificación de comportamiento. En primer lugar, se debe configurar en el backend la interfaz del lado del servidor correspondiente y configurar captchaId y Key obtenidos desde la Consola de administración de EngageLab.

Los desarrolladores que integren el SDK deben utilizar las siguientes interfaces proporcionadas por el SDK de iOS:

1. Configurar la inicialización de la verificación mediante el ID.
2. Iniciar la verificación.
3. Obtener los parámetros del resultado de verificación y realizar una validación secundaria de los parámetros de resultado enviados para evitar falsificaciones.
4. Gestionar posibles incidencias durante la verificación mediante métodos delegados de error.

Se debe implementar el protocolo <GTCaptcha4SessionTaskDelegate> para gestionar los resultados de verificación y los posibles errores.

Consultar Ejemplos de código a continuación para el código de integración.

Compilar y ejecutar el proyecto

Compilar el proyecto y probar la verificación de comportamiento.

Ejemplos de código

Inicialización y llamada de verificación

Importar en el proyecto el archivo de cabecera de la biblioteca dinámica de verificación GTCaptcha4.framework.

              
              #import <GTCaptcha4/GTCaptcha4.h>

            

Se toma como ejemplo la integración en un UIButton.

1. Inicialización

   Inicializar una instancia del gestor de verificación GTCaptcha4Session. En el método de inicialización de UIButton, llamar al método de registro de la instancia de GTCaptcha4Session para obtener los datos de registro:

   #define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" @interface ViewController () <GTCaptcha4SessionTaskDelegate> @property (strong, nonatomic) IBOutlet UIButton *startBtn; @property (nonatomic, strong) GTCaptcha4Session *captchaSession; @end @implementation ViewController - (GTCaptcha4Session *)captchaSession { if (!_captchaSession) { /// Create instance GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration]; // config.timeout = 8.0f; /// Set intermediate page address, must be set as per the example config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html"; /// Set apiServer and staticServer, must be set as per the example config.apiServers = @[@"captcha-api.engagelab.com"]; config.staticServers = @[@"captcha-stat.engagelab.com/www/js"]; /// Request protocol config.protocol = @"https"; _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config]; _captchaSession.delegate = self; } return _captchaSession; } - (void)viewDidLoad { [super viewDidLoad]; // Pre-initialize the verification session. If not called here, lazy loading will be used. [self captchaSession]; [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside]; }

                 
                 #define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   
   @interface ViewController () <GTCaptcha4SessionTaskDelegate>
   
   @property (strong, nonatomic) IBOutlet UIButton *startBtn;
   
   @property (nonatomic, strong) GTCaptcha4Session *captchaSession;
   
   @end
   
   @implementation ViewController
   
   - (GTCaptcha4Session *)captchaSession {
       if (!_captchaSession) {
           /// Create instance
           GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration];
           // config.timeout = 8.0f;
           /// Set intermediate page address, must be set as per the example
           config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html";
           /// Set apiServer and staticServer, must be set as per the example
           config.apiServers = @[@"captcha-api.engagelab.com"];
           config.staticServers = @[@"captcha-stat.engagelab.com/www/js"];
           /// Request protocol
           config.protocol = @"https";
           _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config];
   
           _captchaSession.delegate = self;
       }
   
       return _captchaSession;
   }
   
   - (void)viewDidLoad {
       [super viewDidLoad];
   
       // Pre-initialize the verification session. If not called here, lazy loading will be used.
       [self captchaSession];
   
       [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside];
   }
   
               

   Este bloque de código se muestra en una ventana flotante

   Para otros elementos de configuración opcionales, consultar las interfaces o propiedades definidas en GTCaptcha4SessionConfiguration.

2. Ejecutar la verificación

   Tras la inicialización, llamar al siguiente método para realizar la verificación:

   - (void)start { [self.captchaSession verify]; }

                 
                 - (void)start {
       [self.captchaSession verify];
   }
   
               

   Este bloque de código se muestra en una ventana flotante

Gestión de resultados de verificación

La verificación solo se completa tras validar los resultados de verificación. Es necesario gestionar los siguientes métodos delegados tras implementar el protocolo GTCaptcha4SessionTaskDelegate:

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceive:(NSString *)code result:(NSDictionary *)result {
    NSLog(@"result: %@", result);
    // code is @"1" if the user completed the verification, @"0" if the user failed verification
    if ([@"1" isEqualToString:code]) {
        if (result && result.count > 0) {
            // Convert dictionary to form format for submission (construct based on actual interface data format requirements)
            __block NSMutableArray<NSString *> *kvPairs = [NSMutableArray array];

            [result enumerateKeysAndObjectsUsingBlock:^(id  _Nonnull key, id  _Nonnull obj, BOOL * _Nonnull stop) {
                if ([key isKindOfClass:[NSString class]] &&
                    [obj isKindOfClass:[NSString class]]) {
                    NSString *kvPair = [NSString stringWithFormat:@"%@=%@", key, obj];
                    [kvPairs addObject:kvPair];
                }
            }];

            NSString *formStr = [kvPairs componentsJoinedByString:@"&"];
            NSData *data = [formStr dataUsingEncoding:NSUTF8StringEncoding];

            // Backend verification interface provided by the business
            NSURL *url = [NSURL URLWithString:@"https://***/validate"];
            NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
            request.HTTPMethod  = @"POST";
            request.HTTPBody    = data;

            // Submit to the backend for result validation
            [[[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
                if (!error && data) {
                    // Handle verification results
                    NSString *msg = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
                    NSLog(@"result: %@", msg);
                }
                else {
                    NSLog(@"error: %@", error);
                }
            }] resume];
        }
    }
}

            

Gestión de errores de verificación

Durante la verificación pueden producirse errores inesperados. Tras implementar el protocolo GTCaptcha4SessionTaskDelegate, se pueden gestionar mediante el siguiente método delegado:

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceiveError:(GTC4Error *)error {
    // Display error information and error code to the user

    // Log error details
    NSLog(@"error: %@", error.description);
}

            

Se recomienda encarecidamente mostrar al usuario tanto el motivo del error como el código de error al presentar errores de verificación, a fin de facilitar la resolución de incidencias en entorno productivo.

Ejemplo en Swift

Para ver un código de ejemplo más detallado, consultar la Demo oficial proporcionada. Para el código de ejemplo en Swift, consultar el archivo DefaultDemoViewController.swift en el código fuente de la Demo.