> This page is for Applications Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# 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](https://github.com/PerimeterX/px-iOS-Framework/tags) 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](https://github.com/PerimeterX/px-mobile-sdk-demo-app).
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:

**`3.1 - 3.2`**

```none title="3.1 - 3.2"
Xcode 15.0 - 15.4
Swift 5.9
```

**`3.0`**

```Text title="3.0"
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](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](https://github.com/PerimeterX/px-iOS-Framework).
> 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](https://guides.cocoapods.org/).

```none
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.

```swift
import PerimeterX_SDK
```

```objectivec
@import PerimeterX_SDK;
```

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

```swift
class AppDelegate: UIResponder, UIApplicationDelegate, PerimeterXDelegate
```

```objectivec
@interface AppDelegate : UIResponder <UIApplicationDelegate, PerimeterXDelegate>
```

3. Create and configure the `PXPolicy` object, in the `UIApplicationDelegate`'s `didFinishLaunchingWithOptions`function.

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

```objectivec
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.

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

```objectivec
[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.

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

```objectivec
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.

```swift
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)")
}
```

```objectivec
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:

* **Integration verification and testing**
  * [How to verify the integration](/applications/ios-how-to-verify-the-integration-in-your-app-with-the-sdk-v3)
  * [How to test your app with the SDK](/applications/ios-how-to-test-you-app-with-the-sdk)
* **Manual integration**
  * [Understanding the flow](/applications/ios-manual-integration-v3#understanding-the-flow)
  * [Adding SDK's HTTP headers to your URL requests](/applications/ios-manual-integration-v3#adding-sdks-http-headers-to-your-url-requests)
  * [Handle block responses from your server](/applications/ios-manual-integration-v3#handle-block-responses-from-your-server)
* **Handle block responses from the server**
  * [How to retry requests that were blocked](/applications/ios-how-to-retry-requests-that-were-blocked-v3)
  * [Checking the error](/applications/ios-handle-block-responses-from-the-server-v3#checking-the-error)
  * [When will you receive those errors](/applications/ios-handle-block-responses-from-the-server-v3#when-will-you-receive-those-errors)
  * [How the SDK presents the block page to the user](/applications/ios-handle-block-responses-from-the-server-v3#how-the-sdk-presents-the-block-page-to-the-user)
* **React Native support**
  * [Integration with React Native](/applications/ios-integration-with-react-native-v3)
* **Hybrid App support**
  * [What is "Hybrid App"](/applications/ios-hybrid-app-support-v3#what-is-hybrid-app)
  * [How to enable Hybrid App support](/applications/ios-hybrid-app-support-v3#how-to-enable-hybrid-app-support)
* **Account Defender**
  * [How to enable support for Account Defender](/applications/ios-enable-support-for-account-defender-v3)
* **Multiple AppIDs support**
  * [Integration with multiple AppIDs](/applications/ios-multiple-appids-support-v3)
* **Migrating from earlier SDK versions**
  * [From v2 to v3](/applications/ios-migrating-sdk-from-v2-to-v3)
  * [From v1 to v2](/applications/ios-migrating-sdk-from-v1-to-v2)

### Looking for earlier SDK version?

* [SDK v2 - How to integrate the SDK in your application](/applications/ios-how-to-integrate-the-sdk-in-your-application-v2)
* [SDK v1 - How to integrate the SDK in your application](/applications/ios-how-to-integrate-the-sdk-in-your-application-v1)