How to integrate the SDK in your application

v3.0

Introducing the software documentation and the demo app!

The software documentation provides elaborated information on every class, function and member in the SDK. The class documentation is a .doccarchive file that can be opened with Xcode. To get it, please follow those steps:

1. Open the tag list in the SDK repo.
2. Select the wanted version.
3. Download the source code (zip file).
4. Unzip the file and open the PerimeterX_SDK.doccarchive file via Xcode.

The demo app gives you a general idea on how you should implement the SDK in you app. To download it, please follow those steps:

1. Open the demo app repo.
2. Download the content of the repo.
3. Unzip the file and open the iOS demo app.

Prerequisites

The following are required to install the SDK:

1. Administrative access to the HUMAN Portal to:
   1. Retrieve the application ID (AppID).
   2. Set the token expiration and validity.
2. An active Enforcer.

Choose the SDK version according to your development environment:

1
Xcode 15.0 - 15.4
2
Swift 5.9

Adding SDK to your project:

You can add the SDK to your project with one of the following options:

Swift Package Manager

Add the package from the following repository: https://github.com/PerimeterX/px-iOS-Framework

CocoaPods

Add the PerimeterX pod to your Podfile.

1
platform :ios, '13.0'
2
use_frameworks!
3
4
target '<Your App Name>' do
5
    pod 'PerimeterX', '<version>'
6
end

Manual

1. Open the SDK repo.
2. Download the content of the repo.
3. Unzip the file and copy the PerimeterX_SDK.xcframework file to you project.
4. In Xcode, add the framework to the “Frameworks, Libraries, and Embedded Content” section in your target.

How to start the SDK

Starting the SDK should be the first thing that runs in your app. Therefore, you should start it in your AppDelegate class:

1. Import the SDK.

1
import PerimeterX_SDK

2. Make your AppDelegate class to conform to the PerimeterXDelegate (optional).

1
class AppDelegate: UIResponder, UIApplicationDelegate, PerimeterXDelegate

3. Create and configure the PXPolicy object, in the UIApplicationDelegate’s didFinishLaunchingWithOptionsfunction.

1
let policy = PXPolicy()
2
// configure the policy instacne

4. It’s recommended to tell the SDK which domains it should intercept. Not setting domains will cause the SDK to intercept URL requests from ALL domains, including 3rd party libraries.

1
policy.set(domains: ["my-domain.com"], forAppId: "<APP_ID>")

5. Call the PerimeterX/start(appId:delegate:policy:) function, with your AppID and the policy, in the UIApplicationDelegate’s didFinishLaunchingWithOptions function. This function should be called only once.

1
do {
2
    try PerimeterX.start(appId: "<APP_ID>", delegate: self, policy: policy)
3
}
4
catch {
5
    print("failed to start. error: \(error)")
6
}

Adding custom parameters

You may add custom parameters for additional configuration.

1
do {
2
    var customParameters = [String: String]()
3
    customParameters["custom_param1"] = "hello"
4
    customParameters["custom_param2"] = "world"
5
    try PerimeterX.setCustomParameters(parameters: customParameters)
6
}
7
catch {
8
    print("failed to set custom parameters: \(error)")
9
}

Summary

After writing the code above, the SDK will:

1. Intercept your URL requests.
2. Add SDK’s HTTP headers to those URL requests.
3. Handle block responses from the server by presenting a challenge to the user.

Next steps

Review the following topics:

• Integration verification and testing
  • How to verify the integration
  • How to test your app with the SDK
• Manual integration
  • Understanding the flow
  • Adding SDK’s HTTP headers to your URL requests
  • Handle block responses from your server
• Handle block responses from the server
  • How to retry requests that were blocked
  • Checking the error
  • When will you receive those errors
  • How the SDK presents the block page to the user
• React Native support
  • Integration with React Native
• Hybrid App support
  • What is “Hybrid App”
  • How to enable Hybrid App support
• Account Defender
  • How to enable support for Account Defender
• Multiple AppIDs support
  • Integration with multiple AppIDs
• Migrating from earlier SDK versions
  • From v2 to v3
  • From v1 to v2

Looking for earlier SDK version?

• SDK v2 - How to integrate the SDK in your application
• SDK v1 - How to integrate the SDK in your application