Contents x
    How to integrate the SDK in your application
    • 27 May 2024
    • Print
    • Dark
      Light
    Contents

    How to integrate the SDK in your application

    • Updated on 27 May 2024
    • Print
    • Dark
      Light
    Article summary

    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

    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?

    Was this article helpful?
    What's Next