Product guides

How to integrate the SDK in your application

Suggest Edits

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:

Xcode 15.0 - 15.4
Swift 5.9

Xcode 14.0 - 14.2
Swift 5.7

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

📘

SDK link repository

We recommend using the following link repository: https://github.com/PerimeterX/px-iOS-Framework-spm.
The main git repository for is very large, and Swift Package Manager always downloads the full repository with all git history. This link repository is much smaller, so can be downloaded much more quickly.

Instead of downloading the full git history of PerimeterX iOS SDK and building it from source, this repository just contains a pointer to the precompiled XCFramework included in the latest PerimeterX iOS SDK release.

CocoaPods

Add the PerimeterX pod to your Podfile.

platform :ios, '13.0'
use_frameworks!

target '<Your App Name>' do
    pod 'PerimeterX', '<version>'
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.

    import PerimeterX_SDK

    @import PerimeterX_SDK;

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

    class AppDelegate: UIResponder, UIApplicationDelegate, PerimeterXDelegate

    @interface AppDelegate : UIResponder <UIApplicationDelegate, PerimeterXDelegate>

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

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

    PXPolicy *policy = [[PXPolicy alloc] init];
// 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.

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

    [policy setWithDomains:[NSSet setWithObject:@"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.

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

    NSError *error = nil;
[PerimeterX startWithAppId:@"<APP_ID>" delegate:self policy:policy error:&error];
if (error != nil) {
    NSLog(@"failed to start. error: %@", error);
}

📘

What happens when you start the SDK

The PerimeterX/start(appId:delegate:policy:) function set up the session for a given AppID. It's essential to call this function as early as possible in your application and before any URL request to your server.

Adding custom parameters

You may add custom parameters for additional configuration.

do {
    var customParameters = [String: String]()
    customParameters["custom_param1"] = "hello"
    customParameters["custom_param2"] = "world"
    try PerimeterX.setCustomParameters(parameters: customParameters)
}
catch {
    print("failed to set custom parameters: \(error)")
}

NSMutableDictionary<NSString *, NSString *> *customParameters = [[NSMutableDictionary<NSString *, NSString *> alloc] init];
customParameters[@"custom_param1"] = @"hello";
customParameters[@"custom_param2"] = @"world";
NSError *error = nil;
[PerimeterX setCustomParametersWithParameters:customParameters forAppId:nil error:&error];
if (error != nil) {
   NSLog(@"failed to set custom parameters. error: %@", error);
}

🚧

Device's motion detection

The SDK creates an instance ofCMMotionManager. However if your app also creates an instance ofCMMotionManager you should disable the motion detection in the SDK because it's not recommended to have more than one instance in the app. You can do this by settingallowDeviceMotionDetection=false in the policy.

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:

Looking for earlier SDK version?

Updated 12 days ago