iOS-Integrationsleitfaden

Das EngageLab Behavioral Verification iOS SDK ist für Entwickler:innen konzipiert, die native iOS-Client-Anwendungen integrieren möchten. Das SDK ist eigenständig und benötigt keine externen Bibliotheken.

Produktübersicht

Systemvoraussetzungen

SDK importieren

1. Wenn Sie das SDK manuell hinzufügen, fügen Sie die Datei GTCaptcha4.framework aus dem Download Ihrem Projekt hinzu und aktivieren Sie „Copy items if needed“.

   Verwenden Sie die Methode Linked Frameworks and Libraries, um das Framework zu importieren. Nachdem Sie GTCaptcha4.framework in das Projekt eingefügt haben, stellen Sie sicher, dass die .framework-Datei unter PROJECT -> Build Phases -> Linked Frameworks and Libraries hinzugefügt wurde.

   

   Das SDK wird auch als XCFramework bereitgestellt. Sie finden diese im Verzeichnis SDK -> XCFramework der heruntergeladenen Dateien als GTCaptcha4.xcframework.

2. Fügen Sie für Category in statischen Bibliotheken -ObjC zu den Other Linker Flags in den Build Settings des jeweiligen Targets hinzu.

   

3. Sie müssen außerdem GTCaptcha4.Bundle in Ihr Projekt einbinden, damit die Verifizierung funktioniert. Ziehen Sie das GTCaptcha4.Bundle aus dem SDK-Verzeichnis in Ihr Projekt.

   

Auf der WWDC23 hat Apple neue Datenschutzrichtlinien für Apps (einschließlich SDKs) vorgestellt. Eine eigene Session finden Sie unter Get started with privacy manifests - WWDC23 - Videos - Apple Developer. Am 27.07.2023 veröffentlichte Apple ein Update, wonach ab Herbst 2023 neu hochgeladene Apps, die entsprechende APIs ohne Privacy Manifest nutzen, eine E-Mail-Benachrichtigung erhalten. Ab Frühjahr 2024 werden Privacy Manifests verpflichtend. Für betroffene APIs und Nutzungsgründe siehe: Describing use of required reason API | Apple Developer Documentation. Falls Ihr Anwendungsfall nicht gelistet ist, können Sie eine eigene Begründung einreichen.

Zur Erstellung eines neuen Privacy Manifests siehe Privacy manifest files | Apple Developer Documentation.

Das Behavioral Verification iOS SDK nutzt bestimmte Funktionen zur Ermittlung der Speicherkapazität und zur Umgebungsprüfung zur Risikokontrolle. Dabei werden die Kategorien NSPrivacyAccessedAPICategoryDiskSpace und NSPrivacyAccessedAPICategoryFileTimestamp verwendet. Dies wird hiermit offengelegt.

Konfigurationsschnittstelle

Weitere Informationen finden Sie im Produktstruktur-Prozess der Behavioral Verification. Zuerst müssen Sie die entsprechende Server-Schnittstelle in Ihrem Backend einrichten und das captchaId sowie den Key aus der EngageLab Management Console konfigurieren.

Entwickler:innen, die das SDK integrieren, nutzen die folgenden Schnittstellen des iOS SDKs:

1. Initialisierung der Verifizierung mit der ID konfigurieren.
2. Verifizierung starten.
3. Verifizierungsparameter abrufen und eine sekundäre Validierung der übermittelten Parameter durchführen, um Fälschungen zu verhindern.
4. Mögliche Fehler während der Verifizierung über Error-Delegate-Methoden behandeln.

Sie müssen das Protokoll <GTCaptcha4SessionTaskDelegate> implementieren, um die Verifizierungsergebnisse und Fehler zu verarbeiten.

Siehe die Codebeispiele unten für Integrationscode.

Projekt kompilieren und ausführen

Kompilieren Sie Ihr Projekt und testen Sie die Behavioral Verification.

Codebeispiele

Initialisierung und Verifizierungsaufruf

Importieren Sie die Header-Datei der Verifizierungs-Bibliothek GTCaptcha4.framework in Ihr Projekt:

              
              #import <GTCaptcha4/GTCaptcha4.h>

            

Beispielhaft wird die Integration in einem UIButton gezeigt.

1. Initialisierung

   Initialisieren Sie eine Instanz des Verifizierungsmanagers GTCaptcha4Session. In der Initialisierungsmethode des UIButton rufen Sie die Registrierungsfunktion der GTCaptcha4Session-Instanz auf, um die Registrierungsdaten zu erhalten:

   #define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" @interface ViewController () <GTCaptcha4SessionTaskDelegate> @property (strong, nonatomic) IBOutlet UIButton *startBtn; @property (nonatomic, strong) GTCaptcha4Session *captchaSession; @end @implementation ViewController - (GTCaptcha4Session *)captchaSession { if (!_captchaSession) { /// Instanz erstellen GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration]; // config.timeout = 8.0f; /// Adresse der Zwischenseite setzen, muss wie im Beispiel gesetzt werden config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html"; /// apiServer und staticServer setzen, müssen wie im Beispiel gesetzt werden config.apiServers = @[@"captcha-api.engagelab.com"]; config.staticServers = @[@"captcha-stat.engagelab.com/www/js"]; /// Protokoll angeben config.protocol = @"https"; _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config]; _captchaSession.delegate = self; } return _captchaSession; } - (void)viewDidLoad { [super viewDidLoad]; // Die Verifizierungssitzung vorinitialisieren. Falls nicht hier aufgerufen, wird Lazy Loading verwendet. [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) {
           /// Instanz erstellen
           GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration];
           // config.timeout = 8.0f;
           /// Adresse der Zwischenseite setzen, muss wie im Beispiel gesetzt werden
           config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html";
           /// apiServer und staticServer setzen, müssen wie im Beispiel gesetzt werden
           config.apiServers = @[@"captcha-api.engagelab.com"];
           config.staticServers = @[@"captcha-stat.engagelab.com/www/js"];
           /// Protokoll angeben
           config.protocol = @"https";
           _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config];
   
           _captchaSession.delegate = self;
       }
   
       return _captchaSession;
   }
   
   - (void)viewDidLoad {
       [super viewDidLoad];
   
       // Die Verifizierungssitzung vorinitialisieren. Falls nicht hier aufgerufen, wird Lazy Loading verwendet.
       [self captchaSession];
   
       [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside];
   }
   
               

   Diesen Codeblock im schwebenden Fenster anzeigen

   Weitere optionale Konfigurationsmöglichkeiten finden Sie in den Schnittstellen oder Eigenschaften der GTCaptcha4SessionConfiguration.

2. Verifizierung aufrufen

   Nach der Initialisierung rufen Sie die folgende Methode zur Verifizierung auf:

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

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

   Diesen Codeblock im schwebenden Fenster anzeigen

Verifizierungsergebnisse verarbeiten

Die Verifizierung ist erst abgeschlossen, wenn die Ergebnisse validiert wurden. Sie müssen folgende Delegate-Methoden nach Implementierung des Protokolls GTCaptcha4SessionTaskDelegate behandeln:

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceive:(NSString *)code result:(NSDictionary *)result {
    NSLog(@"result: %@", result);
    // code ist @"1", wenn die Verifizierung erfolgreich war, @"0" bei Fehlschlag
    if ([@"1" isEqualToString:code]) {
        if (result && result.count > 0) {
            // Dictionary in Form-Format für die Übermittlung umwandeln (je nach Backend-API anpassen)
            __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-Validierungs-API
            NSURL *url = [NSURL URLWithString:@"https://***/validate"];
            NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
            request.HTTPMethod  = @"POST";
            request.HTTPBody    = data;

            // Zur Validierung an das Backend senden
            [[[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
                if (!error && data) {
                    // Verifizierungsergebnis verarbeiten
                    NSString *msg = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
                    NSLog(@"result: %@", msg);
                }
                else {
                    NSLog(@"error: %@", error);
                }
            }] resume];
        }
    }
}

            

Fehlerbehandlung bei der Verifizierung

Während der Verifizierung können unerwartete Fehler auftreten. Diese können Sie in folgender Delegate-Methode nach Implementierung des Protokolls GTCaptcha4SessionTaskDelegate behandeln:

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceiveError:(GTC4Error *)error {
    // Fehlerinformationen und Fehlercodes den Nutzer:innen anzeigen

    // Fehlerdetails protokollieren
    NSLog(@"error: %@", error.description);
}

            

Es wird dringend empfohlen, bei Verifizierungsfehlern sowohl den Grund als auch den Fehlercode anzuzeigen, um die Fehlerbehebung im Live-Betrieb zu erleichtern.

Swift-Beispiel

Weitere ausführliche Beispielcodes finden Sie im offiziellen Demo-Projekt. Beispielcode für Swift finden Sie in der Datei DefaultDemoViewController.swift im Demo-Quellcode.

Schlagwörter: iOS SDK Integration, CAPTCHA Sicherheit, Apple Datenschutz, Verifizierungs-API

Jetzt starten:

• Demo buchen
• Mehr erfahren