Web Application Firewall:iOS アプリの SDK 統合

1. ヘッダーファイルの追加

• IDFA 版の場合は、次の import 文を追加します。

  #import <AliTigerTally_IDFA/AliTigerTally.h>

• 非 IDFA 版の場合は、次の import 文を追加します。

  #import <AliTigerTally_NOIDFA/AliTigerTally.h> 

2. データ署名の設定

1. ビジネスに合わせてカスタムのエンドユーザー識別子を設定します。これにより、WAF 保護ポリシーをより柔軟に設定できます。

   /**
   * ユーザーアカウントを設定します。
   *
   * @param account   アカウント情報。
   */
   - (void)setAccount:(NSString *)account;

   • パラメータ：

     • account：型：NSString。ユーザーを識別する文字列。非機密化された形式を使用することを推奨します。

   • 戻り値：なし。

   • 例：

     // ゲストユーザーの場合、setAccount をスキップして直接初期化できます。ユーザーがログインした後、setAccount を呼び出して再初期化します。
     [[AliTigerTally sharedInstance] setAccount:@"testAccount"];

2. SDK を初期化してデータ収集を実行します。

   初期化ごとに、デバイス情報が 1 回収集されます。init 関数を再度呼び出して、さまざまなビジネスシナリオに合わせてデータ収集を再初期化できます。

   初期化は、完全、カスタムプライバシー、非プライバシーの 3 つのデータ収集モードをサポートしています。非プライバシーモードでは、IDFA や IDFV など、エンドユーザーのプライバシーに関連するフィールドは除外されます。

   説明

   社内要件に準拠するため、データの完全性を確保できる適切なデータ収集モードを選択してください。データが完全であるほど、脅威の検出精度が向上します。

   // 初期化コールバック。インターフェース呼び出しのステータスコードを返します。
   typedef void (^TTInitListener)(int);
   
   /**
    * SDK を初期化します。
    *
    * @param appkey        キー。
    * @param options       オプションのパラメータ。
    * @param onInitFinish  初期化完了時のコールバック。
    * @return 初期化が成功したかどうかを示します。
    */
   - (int)init:(NSString *)appkey collectType:(TTCollectType)type options:(NSMutableDictionary *_Nullable)options listener:(TTInitListener _Nullable)onInitFinish;

   • パラメータ：

     • appkey：型：NSString。お使いの SDK 認証キー。

     • collectType：型：TTCollectType。データ収集モード。有効な値：

       フィールド	説明	例
       TT_DEFAULT	すべてのデータを収集します。	TT_DEFAULT
       TT_NO_BASIC_DATA	基本デバイスデータを収集しません。 これには、デバイス名、OS バージョン、画面解像度が含まれます。	TT_NO_X | TT_NO_Y (X と Y は除外するデータフィールドの種類を表します)
       TT_NO_UNIQUE_DATA	一意の識別子データを収集しません。 これには、IDFV と IDFA が含まれます。
       TT_NO_EXTRA_DATA	拡張デバイスデータを収集しません。 これには、接続中の Wi-Fi 情報 (SSID、BSSID) と周辺の Wi-Fi ネットワークのリストが含まれます。
       TT_NOT_GRANTED	上記のプライバシー関連データを収集しません。	TT_NOT_GRANTED

     • options：型：NSMutableDictionary。データ収集用のオプションパラメータ。デフォルト値は nil です。以下のパラメータが利用可能です：

       フィールド	説明	例
       IPv6	デバイス情報の報告に IPv6 ドメイン名を使用するかどうかを指定します。 0 (デフォルト)：IPv4 ドメイン名を使用します。 1：IPv6 ドメイン名を使用します。	1
       Intl	中国本土以外のドメイン名を使用してデバイス情報を報告するかどうかを指定します。 0 (デフォルト)：中国本土リージョンに報告します。 1：中国本土以外のリージョンに報告します。	1
       CustomUrl	データ報告サーバーのドメイン名を設定します。	https://cloudauth-device.us-west-1.aliyuncs.com
       CustomHost	データ報告サーバーのホストを設定します。	cloudauth-device.us-west-1.aliyuncs.com

       説明

       ほとんどの国際サイトでは、Intl パラメーターのみを設定します。特定のサイトにデータを報告するには、CustomUrl および CustomHost パラメーターを設定します。利用可能なサイトは次のとおりです。

       • Intl が 0 に設定されている場合、データは中国 (上海) のデフォルトサイトである https://cloudauth-device.cn-shanghai.aliyuncs.com に報告されます

       • Intl が 1 に設定されている場合:

         • デフォルトサイトはシンガポールです：https://cloudauth-device.ap-southeast-1.aliyuncs.com

         • インドネシア (ジャカルタ)：https://cloudauth-device.ap-southeast-5.aliyuncs.com

         • US (Silicon Valley)：https://cloudauth-device.us-west-1.aliyuncs.com

         • ドイツ (フランクフルト)：https://cloudauth-device.eu-central-1.aliyuncs.com

         • 中国 (香港)：https://cloudauth-device.cn-hongkong.aliyuncs.com

     • listener：型：TTInitListener。SDK の初期化コールバックインターフェース。このコールバックを使用して、初期化のステータスを確認できます。デフォルト値は nil です。

       TTCode	コード	説明
       TT_SUCCESS	0	初期化に成功しました。
       TT_NOT_INIT	-1	SDK が初期化されていません。
       TT_NOT_PERMISSION	-2	必要な iOS の権限がありません。
       TT_UNKNOWN_ERROR	-3	不明なシステムエラーが発生しました。
       TT_NETWORK_ERROR	-4	ネットワークエラーが発生しました。
       TT_NETWORK_ERROR_EMPTY	-5	ネットワークエラーが発生しました。返されたコンテンツは空の文字列です。
       TT_NETWORK_ERROR_INVALID	-6	ネットワークレスポンスの形式が無効です。
       TT_PARSE_SRV_CFG_ERROR	-7	サーバー設定の解析に失敗しました。
       TT_NETWORK_RET_CODE_ERROR	-8	ゲートウェイが失敗レスポンスを返しました。
       TT_APPKEY_EMPTY	-9	アプリキーが空です。
       TT_PARAMS_ERROR	-10	その他のパラメータエラーが発生しました。
       TT_FGKEY_ERROR	-11	キー計算エラーが発生しました。
       TT_APPKEY_ERROR	-12	SDK のバージョンがアプリキーのバージョンと一致しません。

   • 戻り値：型：int。エラーコード。0 は成功を示し、負の数は失敗を示します。

   • 例：

     // appkey は、Alibaba Cloud コンソールで取得した認証キーです。
     NSString *appKey = @"xxxxxxxxxxxxxxxxxxxxx";
     // オプションのパラメータ。IPv6 と中国本土以外からの報告を設定できます。
     NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
     [options setValue:@"0" forKey:@"IPv6"];     // IPv4 を使用します。
     [options setValue:@"0" forKey:@"Intl"];     // 中国本土リージョンにデータを報告します。
     // [options setValue:@"1" forKey:@"Intl"];  // 中国本土以外のリージョンにデータを報告します。
     // 米国 (西部) リージョンにデータを報告します。
     // [options setValue:@"https://cloudauth-device.us-west-1.aliyuncs.com" forKey:@"CustomUrl"];
     // [options setValue:@"cloudauth-device.us-west-1.aliyuncs.com" forKey:@"CustomHost"];
     
     // init の呼び出しごとに、デバイス情報が 1 回収集されます。init 関数を再度呼び出して、さまざまなビジネスシナリオに合わせて情報を再収集できます。
     // 完全なデータ収集。
     if (0 == [[AliTigerTally sharedInstance] init:appkey collectType:TT_DEFAULT options:options listener:nil]) {
         NSLog(@"初期化に成功しました");
     } else {
         NSLog(@"初期化に失敗しました");
     }
     
     // 特定の種類のプライベートデータを収集するには、「|」演算子を使用して複数の種類を指定します。
     TTCollectType collectPrivacy = TT_NO_BASIC_DATA | TT_NO_EXTRA_DATA;
     int ret = [[AliTigerTally sharedInstance] init:appkey collectType:collectPrivacy options:options listener:nil];
     
     // プライベートデータを収集しません。
     int ret = [[AliTigerTally sharedInstance] init:appkey collectType:TT_NOT_GRANTED options:options listener:nil];

3. データハッシュ。

   このカスタム署名インターフェースは、入力データをハッシュして whash 文字列を生成します。この文字列がカスタム署名として機能します。POST、PUT、および PATCH リクエストの場合は、リクエストボディを入力として使用します。GET および DELETE リクエストの場合は、完全な URL を使用します。生成された whash 文字列を HTTP リクエストヘッダーの ali_sign_whash フィールドに追加する必要があります。

   // リクエストタイプ：
   typedef NS_ENUM(NSInteger, TTRequestType) {
       TT_GET=0, TT_POST, TT_PUT, TT_PATCH, TT_DELETE
   };
   
   /**
    * カスタム署名データをハッシュします。
    * @param type  データ型。
    * @param input 署名するデータ。
    * @return whash 文字列。
    */
   - (NSString *)vmpHash:(TTRequestType)type input:(NSData *)input;

   • パラメータ：

     • type：型：TTRequestType。データ型。有効な値：

       • GET：GET リクエストデータ。

       • POST：POST リクエストデータ。

       • PUT：PUT リクエストデータ。

       • PATCH：PATCH リクエストデータ。

       • DELETE：DELETE リクエストデータ。

     • input：型：NSData。署名するデータ。type に応じて、リクエストボディまたは URL を渡します。

   • 戻り値：型：NSString。whash 文字列。

   • 例：

     // GET リクエスト
     NSString *url = @"https://tigertally.aliyun.com/apptest";
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_GET input:[url dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@", whash);
     
     // POST リクエスト
     NSString *body = @"hello world";
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_POST input:[body dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@", whash);

   説明

   このインターフェースは、WAF コンソールでカスタム署名オプションを有効にしている場合にのみ呼び出す必要があります。デフォルトの署名設定を使用する場合は、このステップをスキップできます。

4. データ署名。

   このメソッドは VMP テクノロジーを使用し、input データに署名して、リクエスト認証用の wtoken 文字列を返します。

   /**
    * データに署名します。
    * @param input 署名するデータ。
    * @return wtoken 文字列。
    */
   - (NSString *)vmpSign:(NSData *)input;

   • パラメータ：

     • input：型：NSData。署名するデータ。これは通常、リクエストボディ全体またはカスタム署名による whash です。

   • 戻り値：型：NSString。wtoken 文字列。

   • 例：

     // コンソールで設定されたデフォルトの署名 (カスタム署名は選択されていません)。
     NSString *body = @"hello world";
     NSString *wtoken = [[AliTigerTally sharedInstance] vmpSign:[body dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"wtoken: %@", wtoken);
     
     // コンソールで設定されたカスタム署名。
     // POST リクエストのカスタム署名。
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_POST input:[body dataUsingEncoding:NSUTF8StringEncoding]];
     NSString *wtoken = [[AliTigerTally sharedInstance] vmpSign:[whash dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@, wtoken: %@", whash, wtoken);
     
     // GET リクエストのカスタム署名。
     NSString *url = @"https://tigertally.aliyun.com/apptest";
     NSString *whash = [[AliTigerTally sharedInstance] vmpHash:TT_GET input:[url dataUsingEncoding:NSUTF8StringEncoding]];
     NSString *wtoken = [[AliTigerTally sharedInstance] vmpSign:[whash dataUsingEncoding:NSUTF8StringEncoding]];
     NSLog(@"whash: %@, wtoken: %@", whash, wtoken);

     説明

     • カスタム署名を使用する場合、vmpSign インターフェースの input には vmpHash によって生成された whash 文字列を指定する必要があります。アプリ保護のシナリオベースポリシーを設定する場合、カスタム署名フィールドに ali_sign_whash を設定する必要があります。

     • vmpHash を呼び出して GET リクエストの whash を生成する場合、入力 URL が最終的なネットワークリクエスト URL と同一であることを確認してください。一部のフレームワークは文字やパラメーターを自動的にエンコードするため、URL エンコーディングには特に注意してください。

     • vmpHash インターフェースの input は空にできません。入力が URL の場合、パスまたはパラメーターを含む必要があります。

     • vmpSign を呼び出す際、リクエストボディが空の場合 (たとえば、GET リクエストやボディのない POST リクエストなど)、nil または [@"" dataUsingEncoding:NSUTF8StringEncoding] のような空の文字列の NSData 表現を渡します。

     • whash または wtoken が次のいずれかの文字列を返す場合、エラーを示します：

       • you must call init first: init 関数が呼び出されていません。

       • you must input correct data: 入力データが無効です。

       • you must input correct type: 入力タイプが無効です。

3. 二次検証

1. 結果の確認。

   二次検証が必要かどうかを判断するには、レスポンスのクッキーとボディを確認します。ヘッダーに複数の Set-Cookie フィールドが含まれている場合は、このインターフェースを呼び出す前に、それらを 1 つのクッキー文字列にマージします。

   /**
    * 二次検証を実行するかどうかを確認します。
    *
    * @param cookie  レスポンスの Cookie。
    * @param body    レスポンスボディ。
    * @return 0：合格、1：二次検証が必要。
    */
   - (int)cptCheck:(NSString *)cookie body:(NSData *)body;

   • パラメータ：

     • cookie：型：NSString。リクエストレスポンス内のすべてのクッキー。

     • body：型：NSData。リクエストレスポンスのボディ全体。

   • 戻り値：型：int。判定結果。0 はリクエストが合格したことを示し、1 は二次検証が必要であることを示します。

   • • 例：

     NSString *cookie = @"key1=value1;key2=value2;";
     NSData *body = xxx;
     int recheck = [[AliTigerTally sharedInstance] cptCheck:cookie body:body];
     NSLog(@"recheck: %d", recheck);

2. スライダーの作成。

   cptCheck の結果が検証の必要性を示している場合は、スライダーオブジェクトを作成します。TTCaptcha オブジェクトは、スライダーウィンドウを制御するための show および dismiss メソッドを提供します。TTOption を使用してそのパラメータを設定し、TTDelegate を使用してそのステータスコールバックを処理します。スライダーウィンドウをカスタマイズするには、カスタムページへの URL を提供する必要があります。この URL には、ローカルの HTML ファイルまたはリモートページを指定できます。

   /**
    * 検証用のスライダーを表示します。
    *
    * @param view      親コンポーネント。
    * @param option    パラメータ。
    * @param detegate  コールバックプロトコル。
    */
   - (TTCaptcha *)cptCreate:(UIView *)view option:(TTOption *)option delegate:(id<TTDelegate>)detegate;
   
   
   @protocol TTDelegate <NSObject>
   @required
   // スライダー検証が成功しました。
   - (void)success:(TTCaptcha *)captcha data:(NSString *)data;
   
   // スライダー検証が失敗しました。
   - (void)failed:(TTCaptcha *)captcha code:(NSString *)code;
   @end
   
   
   @interface TTOption : NSObject
   // タップによるキャンセル可否。
   @property (nonatomic, assign) BOOL cancelable;
   
   // カスタムページ。
   @property (nonatomic, strong) NSString *customUri;
   
   // 言語。
   @property (nonatomic, strong) NSString *language;
   @end
   
   
   @interface TTCaptcha : NSObject
   
   - (instancetype)init:(UIView *)view option:(TTOption *)option delegate:(id<TTDelegate>)delegate;
   
   // データ分析用のスライダートレース ID を取得します。
   - (NSString *)getTraceId;
   
   // スライダーを表示します。
   - (void)show;
   
   // スライダーを閉じます。
   - (void)dismiss;
   
   @end

   • パラメータ：

     • view：型：View。現在のページビュー。

     • option：型：TTOption。スライダーの設定パラメータ。

     • delegate：型：TTDelegate。スライダーのステータスコールバック。

   • 戻り値：型：TTCaptcha。スライダーオブジェクト。

   • 例：

     #pragma mark - TTDelegate
     - (void)failed:(TTCaptcha *)captcha code:(nonnull NSString *)code {
         NSLog(@"captcha failed: %@", code);
     }
     
     - (void)success:(TTCaptcha *)captcha data:(nonnull NSString *)data {
         NSLog(@"captcha success: %@", data);
     }
     
     TTOption *option = [[TTOption alloc] init];
     // option.customUri = @"ali-tt-captcha-demo-ios";
     option.language   = @"cn";
     option.cancelable = true;
     
     TTCaptcha *captcha = [[AliTigerTally sharedInstance] cptCreate:[self view] option:option delegate:self];
     [captcha show];

     説明

     「検証に失敗しました」というエラーは、ユーザーがスライダーを操作中または操作後に例外が検出されたことを示します。

     次の表にエラーコードを示します。

     • 1001：検証チャレンジに失敗しました。

     • 1002：システム例外が発生しました。

     • 1003：無効なパラメータが指定されました。

     • 1005：検証がキャンセルされました。

     • 8001：スライダーの表示に失敗しました。

     • 8002：スライダー検証データで例外が発生しました。

     • 8003：スライダー検証中に内部例外が発生しました。

     • 8004：ネットワークエラーが発生しました。