> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/ios/get-started/integration.md).
# Get started integrating Apryse iOS SDK
Integrate a free trial of the Apryse iOS SDK into your Xcode projects with this comprehensive guide. Choose between Swift Package Manager, CocoaPods, or manual installation for seamless integration. G
Welcome to Apryse. This guide will help you integrate a free trial of the Apryse iOS SDK into your Xcode projects for iOS applications. You can either integrate Apryse frameworks automatically using Swift Package Manager, CocoaPods, or install them manually by downloading the SDK. Pick whichever your option you prefer, but integrating with Swift Package Manager is the recommended approach. Your free trial includes unlimited trial usage and support from solution engineers.
{% tabs %}
{% tab title="Integrate with CocoaPods" %}
## CocoaPods Integration for iOS
## Prerequisites
* [Xcode](https://developer.apple.com/xcode/)
* [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#installation)
{% hint style="info" %}
**No trial license key required.**
The trial of Apryse Mobile SDK does not require a trial key. A commercial license key is required for use in a production environment. Please [contact sales](https://apryse.com/form/contact-sales) to purchase a commercial key or if you need any other license key assistance.
{% endhint %}
{% hint style="warning" %}
**Keep your license keys confidential.**
License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).
{% endhint %}
## Integrating Apryse SDK for your iOS application
{% hint style="info" %}
**Framework format**
The default CocoaPods integration uses [.xcframeworks](https://help.apple.com/xcode/mac/11.4/#/dev6f6ac218b). If you wish to use the older .framework format, you can remove the `xcframeworks` path component from the podspec URLs throughout this guide.
{% endhint %}
This guide will use the latest versions of `PDFNet.xcframework` and `Tools.xcframework`. To do this, modify your PodFile to include the `PDFTron` and `PDFTronTools` pods:
{% code lineNumbers="true" %}
```ruby
pod 'PDFTron', podspec: 'https://www.pdftron.com/downloads/ios/cocoapods/xcframeworks/pdftron/latest.podspec'
pod 'PDFTronTools', podspec: 'https://www.pdftron.com/downloads/ios/cocoapods/xcframeworks/pdftron-tools/latest.podspec'
```
{% endcode %}
Then run `pod install` in your project directory. You should be able to use the `PDFNet` and `Tools` libraries after this process.
You can find out more about other [integration options for Apryse SDK with CocoaPods](#more-integration-options).
## Add Required Permissions
Apryse uses a select number AppStore permissions to allow certain functionality such as adding image stamps and detecting the Apple Pencil. Your app's plist must include the following keys (with whatever description is appropriate for your app), or it will be rejected from the AppStore.
{% code lineNumbers="true" %}
```xml
NSCameraUsageDescription
This will allow you to use the image from your camera.
NSPhotoLibraryAddUsageDescription
This will allow you to add images to your photo library.
NSPhotoLibraryUsageDescription
This will allow you to create signatures and annotations from images in your photo library.
NSBluetoothAlwaysUsageDescription
This will allow us to detect if an Apple Pencil is paired, enabling palm rejection and the ability to scroll with one finger while annotating.
NSBluetoothPeripheralUsageDescription
This will allow us detect if an Apple Pencil is paired, enabling palm rejection and the ability to scroll with one finger while annotating.
```
{% endcode %}
## Initialize Apryse
Initialize Apryse before you use any Apryse related classes or methods. This only needs to be done once.
The best practice to do this is to use the optional `application:willFinishLaunchingWithOptions:` method in the `AppDelegate` class found in either the `AppDelegate.swift` or `AppDelegate.m` file in the left pane depending on your choice of language:
{% tabs %}
{% tab title="Swift" %}
{% code lineNumbers="true" %}
```swift
// In AppDelegate.swift
import UIKit
import PDFNet
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
//... Any methods already here
func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions:[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
PTPDFNet.initialize("Insert Commercial License Key Here After Purchase")
return true
}
}
```
{% endcode %}
{% endtab %}
{% tab title="Obj-C" %}
{% code lineNumbers="true" %}
```objc
// In AppDelegate.m
#import "AppDelegate.h"
#import
@interface AppDelegate ()
@end
@implementation AppDelegate
// ... Any methods already here
- (BOOL)application:(UIApplication *)application willFinishLaunchingWithOptions:(nullable NSDictionary *)launchOptions{
[PTPDFNet Initialize:@"Insert Commercial License Key Here After Purchase"];
return true;
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
While you are trialing Apryse, you can pass any string to the initialize method. A string that is not a license key will enable demo mode, where all pages are lightly watermarked.
You can now use Apryse SDK to [view, annotate and edit documents](/ios/get-started/viewdoc.md).
## More Integration Options
You have several options for adding the Apryse iOS SDK to your project with CocoaPods. The standard way to install the SDK, which is used above in this guide, is to use the latest official release version. It is also possible to "pin" the Apryse pods to a specific version of the SDK using the full version number of the release. The following subsections outline these different options.
The `PDFNet.xcframework` and `Tools.xcframework` libraries are distributed as separate pods.
#### Latest
For the **latest** official release version of the `PDFNet.xcframework` and `Tools.xcframework` libraries, add the following to your Podfile:
{% code lineNumbers="true" %}
```ruby
pod 'PDFTron', podspec: 'https://www.pdftron.com/downloads/ios/cocoapods/xcframeworks/pdftron/latest.podspec'
pod 'PDFTronTools', podspec: 'https://www.pdftron.com/downloads/ios/cocoapods/xcframeworks/pdftron-tools/latest.podspec'
```
{% endcode %}
Then, run `pod install`.
When a new official version of the SDK is released, you can easily update the Apryse pods with the `pod update` command without having to modify your Podfile.
#### Specific
For a **specific** release of the `PDFNet.xcframework` and `Tools.xcframework` libraries, add the following to your Podfile:
{% code lineNumbers="true" %}
```ruby
pod 'PDFTron', podspec: 'https://www.pdftron.com/downloads/ios/cocoapods/xcframeworks/pdftron/11.8.0.86165.podspec'
pod 'PDFTronTools', podspec: 'https://www.pdftron.com/downloads/ios/cocoapods/xcframeworks/pdftron-tools/11.8.0.86165.podspec'
```
{% endcode %}
#### Legacy
The legacy "pdfnet" and "pdfnet-no-tools" pods are no longer recommended for new projects due to incompatibilities with specific setups. These pods are deprecated and while they are still made available for new releases of the SDK, migrating to the new "pdftron" and "pdftron-tools" pods should be done when possible. Note, the legacy "pdfnet" pod is used for the React Native wrapper.
Then, run `pod install`.
*Note: CocoaPods distributes the dynamic frameworks only. If you wish to use the static frameworks, you will have to integrate it manually.*
## Next step
View a document
{% endtab %}
{% tab title="Integrate with Swift Package Manager" %}
## Swift Package Manager Integration for iOS
{% hint style="info" %}
**No trial license key required.**
The trial of Apryse Mobile SDK does not require a trial key. A commercial license key is required for use in a production environment. Please [contact sales](https://apryse.com/form/contact-sales) to purchase a commercial key or if you need any other license key assistance.
{% endhint %}
{% hint style="warning" %}
**Keep your license keys confidential.**
License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).
{% endhint %}
## Integrating Apryse SDK for your iOS application
Apple has information on using [Swift Package Manager](https://developer.apple.com/xcode/adding_package_dependencies_to_your_app/), which you may review for topics not covered in this guide.
Apryse is available as a Swift Package from the following URL:
{% code lineNumbers="true" %}
```sh
https://github.com/ApryseSDK/pdftron-apple-package
```
{% endcode %}
To include it, open your project's Swift Package Manager pane:
Enter the github link to the package. Add a high maximum version number to ensure you are always up-to-date. Apryse versioning does not strictly follow a semantic versioning system. (We very rarely make changes that break public APIs.)
## Add Required Permissions
Apryse uses a select number AppStore permissions to allow certain functionality such as adding image stamps and detecting the Apple Pencil. Your app's plist must include the following keys (with whatever description is appropriate for your app), or it will be rejected from the AppStore.
{% code lineNumbers="true" %}
```xml
NSCameraUsageDescription
This will allow you to use the image from your camera.
NSPhotoLibraryAddUsageDescription
This will allow you to add images to your photo library.
NSPhotoLibraryUsageDescription
This will allow you to create signatures and annotations from images in your photo library.
NSBluetoothAlwaysUsageDescription
This will allow us to detect if an Apple Pencil is paired, enabling palm rejection and the ability to scroll with one finger while annotating.
NSBluetoothPeripheralUsageDescription
This will allow us detect if an Apple Pencil is paired, enabling palm rejection and the ability to scroll with one finger while annotating.
```
{% endcode %}
## Initialize Apryse
You only need to explicitly initialize Apryse when you have purchased a license key.
Initialize Apryse before you use any Apryse related classes or methods. This only needs to be done once.
The best practice to do this is to use the optional `application:willFinishLaunchingWithOptions:` method in the `AppDelegate` class found in either the `AppDelegate.swift` or `AppDelegate.m` file in the left pane depending on your choice of language:
{% tabs %}
{% tab title="Swift" %}
{% code lineNumbers="true" %}
```swift
// In AppDelegate.swift
import UIKit
import PDFNet
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
//... Any methods already here
func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions:[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
PTPDFNet.initialize("Insert Commercial License Key Here After Purchase")
return true
}
}
```
{% endcode %}
{% endtab %}
{% tab title="Obj-C" %}
{% code lineNumbers="true" %}
```objc
// In AppDelegate.m
#import "AppDelegate.h"
#import
@interface AppDelegate ()
@end
@implementation AppDelegate
// ... Any methods already here
- (BOOL)application:(UIApplication *)application willFinishLaunchingWithOptions:(nullable NSDictionary *)launchOptions{
[PTPDFNet Initialize:@"Insert Commercial License Key Here After Purchase"];
return true;
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
While you are trialing Apryse, you can pass any string to the initialize method. A string that is not a license key will enable demo mode, where all pages are lightly watermarked.
You can now use Apryse SDK to [view, annotate and edit documents](/ios/get-started/viewdoc.md).
*Note: SPM distributes the dynamic .xcframework only. If you wish to use the .framework, you will need to use CocoaPods or Manual integration. If you wish to use the static framework, you will have to integrate it manually.*
## Next step
View a document
{% endtab %}
{% tab title="Integrate Manually" %}
## Manually integrating iOS PDF library
## Prerequisites
* [Xcode](https://developer.apple.com/xcode/)
1. Apryse iOS SDK
Download the SDK
[Download](https://docs.apryse.com/downloads/ios/dmg/PDFNet.dmg)
{% code lineNumbers="true" %}
```sh
Take note of the location of your `PDFNet.dmg` download.
```
{% endcode %}
{% hint style="info" %}
**No trial license key required.**
The trial of Apryse Mobile SDK does not require a trial key. A commercial license key is required for use in a production environment. Please [contact sales](https://apryse.com/form/contact-sales) to purchase a commercial key or if you need any other license key assistance.
{% endhint %}
{% hint style="warning" %}
**Keep your license keys confidential.**
License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).
{% endhint %}
## Setup
1. Create a new Xcode Project. Call it `pdfhello`. For the purposes of this guide, select a view scene application.
2. From your `PDFNet.dmg` download, copy the `/Lib/` folder into `pdfhello/`.
## Integrating Apryse SDK for your iOS application
1. Select the project in the left pane and go to the `General` tab. Scroll down to find the `Embedded Binaries` section. Here, add `Lib/Tools/Tools.framework` and `Lib/Framework-dynamic/PDFNet.framework` from the `Lib/` folder you copied into your project. You can do this by dragging them in from Finder or by clicking the `+` sign to browse your files.
1. Go to the `Build Phases` tab and click on the `+` button to add a `New Run Script Phase`. Copy and paste the following into the shell command:This will ensure invalid slices are striped from the framework before being submitted to the app store ([a longstanding Xcode bug](https://openradar.appspot.com/24537878)).
{% code lineNumbers="true" %}
```bash
bash "$BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/PDFNet.framework/strip-framework.sh"
```
{% endcode %}
## Add Required Permissions
Apryse uses a select number AppStore permissions to allow certain functionality such as adding image stamps and detecting the Apple Pencil. Your app's plist must include the following keys (with whatever description is appropriate for your app), or it will be rejected from the AppStore.
{% code lineNumbers="true" %}
```xml
NSCameraUsageDescription
This will allow you to use the image from your camera.
NSPhotoLibraryAddUsageDescription
This will allow you to add images to your photo library.
NSPhotoLibraryUsageDescription
This will allow you to create signatures and annotations from images in your photo library.
NSBluetoothAlwaysUsageDescription
This will allow us to detect if an Apple Pencil is paired, enabling palm rejection and the ability to scroll with one finger while annotating.
NSBluetoothPeripheralUsageDescription
This will allow us detect if an Apple Pencil is paired, enabling palm rejection and the ability to scroll with one finger while annotating.
```
{% endcode %}
## Initialize Apryse
Initialize Apryse before you use any Apryse related classes or methods. This only needs to be done once.
The best practice to do this is to use the optional `application:willFinishLaunchingWithOptions:` method in the `AppDelegate` class found in either the `AppDelegate.swift` or `AppDelegate.m` file in the left pane depending on your choice of language:
{% tabs %}
{% tab title="Swift" %}
{% code lineNumbers="true" %}
```swift
// In AppDelegate.swift
import UIKit
import PDFNet
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
//... Any methods already here
func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions:[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
PTPDFNet.initialize("Insert Commercial License Key Here After Purchase")
return true
}
}
```
{% endcode %}
{% endtab %}
{% tab title="Obj-C" %}
{% code lineNumbers="true" %}
```objc
// In AppDelegate.m
#import "AppDelegate.h"
#import
@interface AppDelegate ()
@end
@implementation AppDelegate
// ... Any methods already here
- (BOOL)application:(UIApplication *)application willFinishLaunchingWithOptions:(nullable NSDictionary *)launchOptions{
[PTPDFNet Initialize:@"Insert Commercial License Key Here After Purchase"];
return true;
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
While you are trialing Apryse, you can pass any string to the initialize method. A string that is not a license key will enable demo mode, where all pages are lightly watermarked.
## Next step
View a document
{% endtab %}
{% endtabs %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.apryse.com/ios/get-started/integration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.