Installing the SDK

Prerequisites

The following are required to install the PerimeterX iOS SDK:

  1. Administrative access to the PerimeterX Portal to:

    1. Retrieve the PerimeterX application ID (AppID).

    2. Set the token expiration and validity.

  2. An active PerimeterX Enforcer.

Integration

Adding PerimeterX SDK to your project with:

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:

platform :ios, '13.0'
use_frameworks!

target '<Your App Name>' do
    pod 'PerimeterX', '[PERIMETERX_IOS_SDK_VERSION]'
end

Manual

  1. Download PerimeterX_SDK.xcframework from https://github.com/PerimeterX/px-iOS-Framework

  2. In Xcode, add the framework to the "Frameworks and Libraries" section in your target.

Implementation

In your AppDelegate:

  1. Import the SDK.
import PerimeterX_SDK
@import PerimeterX_SDK;
  1. Make the AppDelegate class to conform to the PerimeterXDelegate.
class AppDelegate: UIResponder, UIApplicationDelegate, PerimeterXDelegate
@interface AppDelegate : UIResponder <UIApplicationDelegate, PerimeterXDelegate>
  1. Verify the SDK's version.
print("SDK version: \(PerimeterX.sdkVersion())")
NSLog(@"SDK version: %@", [PerimeterX sdkVersion]);
  1. Call the PerimeterX/start(appId:delegate:enableDoctorCheck:completion:) function with your AppID.
PerimeterX.start(appId: "<APP_ID>", delegate: self, enableDoctorCheck: false) { success, error in
        if success {
            if let vid = PerimeterX.vid(forAppId: nil) {
                print("vid: \(vid)")
            }
        }
        else {
            if let error = error {
                print("error: \(error)")
            }
            
            // make sure to start the sdk again when it fails (network issue, etc.)
        }
    }
[PerimeterX startWithAppId:@"<APP_ID>" delegate:self enableDoctorCheck:NO completion:^(BOOL success, NSError * _Nullable error) {
        if (success) {
            NSString *vid = [PerimeterX vidForAppId:nil];
            NSLog(@"vid: %@", vid);
        }
        else {
            NSLog(@"error: %@", error);
            
            // make sure to start the sdk again when it fails (network issue, etc.)
        }
    }];
  1. That's it! 🎉

Enable manual interception

The SDK automatically intercepts HTTP requests and adds relevant HTTP headers. However, you can disable this and add those HTTP headers manually.

  1. After calling the PerimeterX/start(appId:delegate:enableDoctorCheck:completion:) function, disable the automatic interception in the policy.
let policy = PXPolicy()
policy.requestsInterceptedAutomaticallyEnabled = false
PerimeterX.setPolicy(policy: policy, forAppId: nil, completion: nil)
PXPolicy *policy = [[PXPolicy alloc] init];
policy.requestsInterceptedAutomaticallyEnabled = NO;
[PerimeterX setPolicyWithPolicy:policy forAppId:nil completion:nil];
  1. Before sending your URL request, take HTTP headers from the SDK and add them to your request.
let headers = PerimeterX.headersForURLRequest(forAppId: nil)
NSDictionary<NSString *, NSString *> *headers = [PerimeterX headersForURLRequestForAppId:nil];
  1. After receiving an error in the response, pass the information to SDK.
let isHandledByPX = PerimeterX.handleResponse(forAppId: nil, data: data, response: response)
    if isHandledByPX {
        print("block response was handled by PX")
    }
BOOL isHandledByPX = [PerimeterX handleResponseForAppId:nil data:data response:response];
    if (isHandledByPX) {
        NSLog(@"block response was handled by PX");
    }

Migrating from earlier SDK version (1.x)

Start the SDK

In version 1.x, the start function is called with two parameters: AppId and enableDoctorCheck (the later was added in 1.16.0).

In version 2.0, the PerimeterX/start(appId:delegate:enableDoctorCheck:completion:) function has another parameter: delegate (PerimeterXDelegate) to handle the SDK's events. Notice that the new Interceptor will be enabled in 2.0. This has effect on the integration with the SDK, which will be described later in this document.

Set custom parameters

In version 1.x, the set custom parameters function is called with the dictionary parameter only.

In version 2.0, the PerimeterX/setCustomParameters(parameters:forAppId:completion:) function has another optional param: the AppID. This is required only when using multiple AppIDs.

Get VID

In version 1.x, the get VID function is called without any parameters.

In version 2.0, the PerimeterX/vid(forAppId:) function has another optional param: the AppID. This is required only when using multiple AppIDs.

Get HTTP headers

In version 1.x, the get HTTP headers function is called without any parameters.

In version 2.0, the PerimeterX/headersForURLRequest(forAppId:) function has another optional param: the AppID. This is required only when using multiple AppIDs.

🚧

Important

The Get HTTP headers function should NOT be used when the interceptor is enabled.

Check error and handle response

In version 1.x, a function is called to get the PX's error response from the request's response which called another function to handle the PX's error response.

In version 2.0 the flow is as following:

  1. If the interceptor is enabled, simply check whether the request was blocked with the PerimeterX/isRequestBlockedError(error:) function
  2. If the interceptor is disabled, use the PerimeterX SDK to handle the response with the PerimeterX/handleResponse(forAppId:data:response:) function. If it was a blocked response, the SDK will handle it and the function will return true

Other functions

All other functions existing in version 1.x were removed from the SDK's API in version 2.0.


Did this page help you?