iOS 統合ガイド

EngageLab Behavioral CAPTCHA iOS SDKは、ネイティブiOSクライアント開発と統合するために設計されています。このSDKは、サードパーティライブラリに依存していません。

製品概要

環境要件

SDKのインポート

1. SDKを手動で追加する場合は、ダウンロードしたGTCaptcha4.frameworkファイルをプロジェクトにドラッグ＆ドロップし、必要に応じてアイテムをコピーにチェックを入れてください。

   Linked Frameworks and Librariesメソッドを使用してフレームワークをインポートします。GTCaptcha4.frameworkをプロジェクトにドラッグした後、.frameworkファイルがPROJECT -> Build Phases -> Linked Frameworks and Librariesに追加されていることを確認してください。

   

   SDKはXCFramework形式を提供しており、ダウンロードしたファイルのSDK -> XCFrameworkディレクトリにGTCaptcha4.xcframeworkとして配置されています。

2. 静的ライブラリのCategoryに対して、対応するターゲットのBuild Settings -> Other Linker Flagsに-ObjCを追加してください。

   

3. プロジェクトにGT4Captcha4.Bundleを含める必要があります。そうでない場合、検証が機能しません。SDKパスからGTCaptcha4.Bundleをプロジェクトにドラッグしてください。

   

WWDC23で、Appleはアプリケーション（SDKを含む）向けの新しいプライバシーポリシーを発表しました。専用トピックはこちら：Get started with privacy manifests - WWDC23 - Videos - Apple Developer。2023年秋から、新しくアップロードされたアプリケーションがプライバシーマニフェストを提供せずにAPIを使用する場合、メール通知が送信されます。2024年春から、プライバシーマニフェストが必須となります。関連するAPIとその使用理由については、こちらを参照してください：Describing use of required reason API | Apple Developer Documentation。使用理由がリストにない場合は、具体的な使用理由を直接提出できます。 新しいプライバシーマニフェストの作成手順については、Privacy manifest files | Apple Developer Documentationを参照してください。

Behavioral CAPTCHA iOS SDKは、リスク制御目的でディスク容量と環境検出情報を取得するためにこれらの機能を使用します。これには、NSPrivacyAccessedAPICategoryDiskSpaceおよびNSPrivacyAccessedAPICategoryFileTimestampカテゴリが含まれます。

インターフェースの設定

Behavioral CAPTCHAの製品構造フローを参照してください。最初にバックエンドで対応するサーバーサイドインターフェースを設定し、EngageLab管理コンソールから取得したcaptchaIdとKeyを構成する必要があります。

統合ユーザーは、iOS SDKを使用して以下のインターフェースを完了する必要があります：

1. IDを使用して検証の初期化を設定します。
2. 検証を開始します。
3. 検証結果のパラメータを取得し、送信された結果パラメータの二次検証を実行して偽造を防ぎます。
4. エラーデリゲートメソッドを使用して検証中の潜在的な問題を処理します。

検証結果と潜在的なエラーを処理するには、<GTCaptcha4SessionTaskDelegate>プロトコルに準拠する必要があります。

統合コードについては、以下の**コード例**を参照してください。

プロジェクトのコンパイルと実行

プロジェクトをコンパイルして、Behavioral CAPTCHAを体験してください。

コード例

初期化と検証呼び出し

プロジェクトで検証動的ライブラリGTCaptcha4.frameworkのヘッダーファイルをインポートします。

              
              #import <GTCaptcha4/GTCaptcha4.h>

            

UIButtonでの統合を参照してください。

1. 初期化

   検証マネージャインスタンスGTCaptcha4Sessionを初期化します。UIButtonの初期化メソッドで、GTCaptcha4Sessionインスタンスの登録メソッドを呼び出して登録データを取得します：

   #define captchaID @"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" @interface ViewController () <GTCaptcha4SessionTaskDelegate> @property (strong, nonatomic) IBOutlet UIButton *startBtn; @property (nonatomic, strong) GTCaptcha4Session *captchaSession; @end @implementation ViewController - (GTCaptcha4Session *)captchaSession { if (!_captchaSession) { /// インスタンス作成 GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration]; // config.timeout = 8.0f; /// 中間ページアドレスを設定、例に従って設定する必要があります config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html"; /// apiServerとstaticServerを設定、例に従って設定する必要があります config.apiServers = @[@"captcha-api.engagelab.com"]; config.staticServers = @[@"captcha-stat.engagelab.com/www/js"]; /// リクエストプロトコル config.protocol = @"https"; _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config]; _captchaSession.delegate = self; } return _captchaSession; } - (void)viewDidLoad { [super viewDidLoad]; // 検証セッションを事前に初期化します。ここで呼び出さない場合、遅延ロードモードが使用されます。 [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) {
           /// インスタンス作成
           GTCaptcha4SessionConfiguration *config = [GTCaptcha4SessionConfiguration defaultConfiguration];
           // config.timeout = 8.0f;
           /// 中間ページアドレスを設定、例に従って設定する必要があります
           config.resourcePath = @"https://captcha-stat.engagelab.com/www/gt4-index.html";
           /// apiServerとstaticServerを設定、例に従って設定する必要があります
           config.apiServers = @[@"captcha-api.engagelab.com"];
           config.staticServers = @[@"captcha-stat.engagelab.com/www/js"];
           /// リクエストプロトコル
           config.protocol = @"https";
           _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID configuration:config];
   
           _captchaSession.delegate = self;
       }
   
       return _captchaSession;
   }
   
   - (void)viewDidLoad {
       [super viewDidLoad];
   
       // 検証セッションを事前に初期化します。ここで呼び出さない場合、遅延ロードモードが使用されます。
       [self captchaSession];
   
       [self.startBtn addTarget:self action:@selector(start) forControlEvents:UIControlEventTouchUpInside];
   }
   
               

   このコードブロックはフローティングウィンドウ内に表示されます

   その他のオプション設定項目については、GTCaptcha4SessionConfigurationで定義されたインターフェースまたはプロパティを参照してください。

2. 検証の呼び出し

   初期化後、以下のメソッドを呼び出して検証を行います：

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

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

   このコードブロックはフローティングウィンドウ内に表示されます

検証結果の処理

検証結果が検証されて初めて検証が完了します。GTCaptcha4SessionTaskDelegateプロトコルに準拠した後、以下のデリゲートメソッドを処理します：

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceive:(NSString *)code result:(NSDictionary *)result {
    NSLog(@"result: %@", result);
    // codeが@"1"の場合、ユーザーは検証を完了しました。codeが@"0"の場合、ユーザーの検証は失敗しました。
    if ([@"1" isEqualToString:code]) {
        if (result && result.count > 0) {
            // 辞書をフォーム形式に変換して送信（実際のインターフェースデータ形式の要件に基づいて構築）。
            __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];

            // 開発者のバックエンドが提供する検証検証インターフェース
            NSURL *url = [NSURL URLWithString:@"https://***/validate"];
            NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
            request.HTTPMethod  = @"POST";
            request.HTTPBody    = data;

            // バックエンドに送信して結果を検証
            [[[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
                if (!error && data) {
                    // 検証結果を処理
                    NSString *msg = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
                    NSLog(@"result: %@", msg);
                }
                else {
                    NSLog(@"error: %@", error);
                }
            }] resume];
        }
    }
}

            

検証エラーの処理

検証中に予期しないエラーが発生する可能性があります。GTCaptcha4SessionTaskDelegateプロトコルに準拠した後、以下のデリゲートメソッドを処理します：

              
              - (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession didReceiveError:(GTC4Error *)error {
    // ユーザーにエラー情報とエラーコードを表示します。

    // エラー詳細をログに記録します。
    NSLog(@"error: %@", error.description);
}

            

エラー理由とエラーコードをユーザーに表示して、オンライン問題のトラブルシューティングを容易にすることを強くお勧めします。

Swiftの例

より詳細なサンプルコードについては、公式デモを参照してください。Swiftのサンプルコードについては、デモソースコード内のDefaultDemoViewController.swiftファイルを参照してください。