Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Objective 

This is a crisp integration documentation to plug ShieldSquare Radware Bot Manager iOS SDK directly into your iOS application to protect your API servers from the malicious bots originating from Mobile App. 

Prerequisite & Compatibility 

  1. Ensure you have created

    an account in ShieldSquare admin

    an account in Radware Bot Manager portal before getting started

  2. Ensure you have already integrated

    ShieldSquare

    Radware Bot Manager at your Web server or

    Application

    application server

  3. Operating System supported: iOS 8 or above

  4. Devices supported: iPhone, iPad, iPod touch

  5. XCode version: 8 or above

  6. Swift version: 4.0.3, 4.1.2 (For any specific versions, write to

    support@shieldsquare

    botmanager_support@radware.com for the custom build) 

Info

Write to support@shieldsquarebotmanager_support@radware.com for for your custom SDK for integration. 

How it works?

...

  1. When your mobile app makes a REST call to your server/API, the data request is sent to ShieldSquare connector integrated at your Origin/Web server. In parallel, ShieldSquare SDK asynchronously collects data and sends  to ShieldSquare bot engine for analysis. Data consists of

    device

    device details (characteristics, orientation & acceleration) and behavioral details (events : buttons clicked, ads clicked, articles read/shared/liked, comments posted, screens viewed, purchases made, levels completed etc.,) based on your business logic from the interactions of the user with your Mobile App. 

  2. ShieldSquare connector sends the data to the ShieldSquare bot engine via ShieldSquare endpoint (deployed across the world using the global load balancer for minimal latency).

  3. ShieldSquare bot engine analyses the data from the endpoint and responds with appropriate action to humans and bots. 

  4. Your origin/web server either sends the requested App data to the user or challenge with CAPTCHA or block the page based on the response from ShieldSquare.

     ShieldSquare

     ShieldSquare SDK has the capability to render in-app CAPTCHA / Block page. 

Info
  • You have to be in 'Active mode' for receiving response codes for CAPTCHA/Block by configuring the responses for different categories of bad bots in 'Bot response page' in ShieldSquare admin portal. ShieldSquare recommends to handle empty data when the user solves the CAPTCHA.  

  • If required,

    ShieldSquare

    the Radware Bot Manager bot engine can also be configured to send response code (CAPTCHA / Block) directly to ShieldSquare SDK.

Integration steps

  1. Integrate ShieldSquare SDK into your project

  2. Configure the ShieldSquare SDK 

  3. Test and release your Application 

1. Integrate

...

Radware Bot Manager SDK into your project 

a. Unzip the package ss2_ios_sdk_vx.x.x.zip which would contain below files.

  • ShieldSquare.framework

  • sscustomization.json

b. Drag and drop ss2_ios_sdk_vx.x.x folder into your Xcode project. Ensure the 'Destination' is checked for 'Copy items if needed' and the appropriate destination group folder is selected.Image Removed

...

c. Select the Project file and add ShieldSquare.framework under Embedded binaries. 

d. Select your project from the project navigator and choose your deployment target.Image Removed

...

e. Open the Build Phases tab and under 'Link Binary with Libraries', verify 'ShieldSquare.framework' is added. Image Removed

...

2. Configure the ShieldSquare SDK 

...

1) SS_SUBSCRIBER_ID (String Type)
2) SS_RECAPTCHA_KEY (String Type)
3) SS_RECAPTCHA_DOMAIN (String Type)Image Removed

...

Info
  • ShieldSquare support team will provide unique customer ID for your account. 

  • Ensure you can configure a required response 'CAPTCHA' or 'Block' from the Bot Response page in ShieldSquare

    Admin Dashboard 

    Admin Dashboard for different types of bots. 

  • You can ignore RECAPTCHA key and domain if you use text CAPTCHA. 

b. Do the following modifications in appdelegate file 

  • Include ShieldSquare header file 

FadeToGrey
Code Block
theme
import ShieldSquare
  • Incorporate below snippet in didFinishLaunchingWithOptions method above return true statement 

Code Block
themeFadeToGrey
ShieldEngine.setup(keyWindow: window!, verifyViewType:
ShieldEngine.SSCaptchaViewType.sstextcaptcha)
ShieldEngine.setUserId(userId: "Visitor ID") // Set the User ID parameter of visitor 
Info

If you want to use Google reCAPTCHA, you have to replace 'sstextcaptcha' with 'ssrecaptcha' in the above method along with domain & key values in the info.plist. For now, we only support google Invisible reCAPTCHA and we recommend that you keep the difficulty level for reCAPTCHA as Medium.

  • Add a method in 'appdelegate class' to track bot events

Code Block
themelanguageFadeToGreyjava
public static func logShieldEvents(resultObject: HTTPURLResponse?) {
DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
ShieldEngine.trackBot(httpResponseObject: resultObject)
}
}
  • Add below block of code whenever the Network call completed. This method requires “HTTPURLResponse” as a result object. Cookies headers will be retrieved by the framework using result objects will be provided by the client app. This is to add Cookie storing capability to your App ( if it doesn't have already) to help ShieldSquare to set four first-party cookies to identify patterns of the user interactions. 

FadeToGrey
Code Block
theme
AppDelegate.logShieldEvents(resultObject: response as? HTTPURLResponse)

c. To collect custom events data, insert below analytics snippet whenever there is an event triggered in your app (Eg:  App open, User signed in, Pages/screens viewed, the article read/liked/shared/commented, app version updated etc.,). ShieldSquare collects the events data in a batch process in fixed time intervals.

FadeToGrey
Code Block
theme
ShieldEngine.trackEvents(
eventName: "login_success",
screenName:"",
eventParams: ["value" : "test", "sessionId" : "1234-1234-1234"])
Info
  • Ensure you have imported ShieldSquare before adding any changes to collect events. 

  • You can add any number of values and keys in the 'eventParams'  

3. Test and release your application 

...