# Installation and configuration (iOS) In this article, you will find out how to install and initialize the Synerise SDK in an iOS application. While performing the actions from this guide, keep the presented order.
The [Settings](/developers/mobile-sdk/settings#pre-initialization-settings) article contains additional information about SDK behaviors you may need prior to configuration.
If you want to find out what kind of benefits you can get from integrating with mobile SDK, go [here](/developers/mobile-sdk/overview). ## Requirements --- You need: * Access to a [workspace](/docs/settings/business-profile) * A Profile [API Key](/docs/settings/tool/api#adding-api-keys) When creating the API key, use allowlisting or denylisting to only allow the events you intend to use. * One of the following dependency managers: - [CocoaPods](https://guides.cocoapods.org/using/getting-started.html) - CocoaPods is a dependency manager for iOS projects. - [Carthage](https://github.com/Carthage/Carthage) - Carthage is a simple, decentralized dependency manager for iOS projects. - [Swift Package Manager](https://www.swift.org/package-manager/) - Swift Package Manager (SPM) is a dependency manager built into Xcode. * Recommended environment: - Xcode 16 - iOS SDK 18 * Target deployment: - **iOS 13.0+** for SDK versions 5.0.0 and higher - **iOS 9.0+** for SDK versions lower than 5.0.0
Bitcode is not supported in SDK version 5.0.0 and higher. Xcode ignores bitcode.
### Apple Frameworks The Synerise SDK references the following Apple frameworks: - `Foundation.framework` - `UIKit.framework` - `CoreGraphics.framework` - `SystemConfiguration.framework` - `MobileCoreServices.framework` - `CoreTelephony.framework` - `Security.framework` - `CommonCrypto.framework` - `WebKit.framework` - `UserNotifications.framework` ### 3rd Party Frameworks - [AFNetworking (fork)](https://github.com/AFNetworking/AFNetworking) - [TrustKit](https://github.com/datatheorem/TrustKit) - [Aspects](https://github.com/steipete/Aspects) ## Installation --- ### CocoaPods 1. Add CocoaPods dependency to **Synerise SDK** into your `Podfile`: 
use_frameworks!

       target YOUR_PROJECT_TARGET do
         pod 'SyneriseSDK'
       end
2. Execute the following shell command in the directory depending on your project configuration: 
pod repo update  
       pod install
### Swift Package Manager (SPM) 1. Go to Xcode project’s settings and navigate to the Package Dependencies tab. 2. Below the packages list, click the Add button. 3. Enter the URL of Synerise SDK repository **(https://github.com/Synerise/synerise-ios-sdk)** in the search text field. 4. Under the Dependency Rule section, select the SDK version. Finally, click **Add Package**. 5. Select the package that best suits your needs and click **Add Package**. ### Carthage 1. Add the Carthage dependency to **Synerise SDK** into your `Cartfile`: 
github "synerise/ios-sdk"
2. Execute the shell command in directory depending on your project configuration: 
carthage update
3. Go to Xcode project target's **General** section. 4. In Finder, open `/Carthage/Build/iOS` 5. Drag `SyneriseSDK.framework` to **Embedded Binaries**. 6. Make sure the **Copy items if needed** option is selected. 7. Click **Finish**. ## Initialization --- ### Setting up 1. Go to Xcode project target's **General** section. 2. Find the **Other Linker Flags** property and add the ***-ObjC*** flag. 2. If you are going to use push notifications: 1. Go to `Info.plist` 2. Add a row for **Required background mode** with the following array type value: `App downloads content in response to push notifications` or add the code below directly: 
<key>UIBackgroundModes</key>
           <array>
               <string>remote-notification</string>
           </array>
3. If you are going to use HTTP addresses (instead of only HTTPS), change the allowlist domains in your app by adding configuration to `Info.plist` in one of the following ways: - Add configured domain/domains that you need. 
<key>NSAppTransportSecurity</key>
          <dict>
              <key>NSExceptionDomains</key>
              <dict>
                  <key>yourdomain.com</key>
                  <dict>
                  <!--Include to allow subdomains-->
                  <key>NSIncludesSubdomains</key>
                  <true/>
                  <!--Include to allow HTTP requests-->
                  <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
                  <true/>
                  <!--Include to specify minimum TLS version-->
                  <key>NSTemporaryExceptionMinimumTLSVersion</key>
                  <string>TLSv1.1</string>
                  </dict>
              </dict>
          </dict>
- Give permission for all domains. 
<key>NSAppTransportSecurity</key>
          <dict>
              <key>NSAllowsArbitraryLoads</key><true/>
          </dict>
### Importing Synerise SDK Import the **Synerise SDK** header into the files that contain code relating to SDK.
```Swift import SyneriseSDK ```
```Objective-C #import ```
In Objective-C, you can include it in your Prefix Header (PCH) and Synerise SDK will be imported to all files automatically.
### Basic initialization Initialize Synerise SDK and provide the [Profile API Key](/docs/settings/tool/api). You may initialize it wherever you want and when you need.
```Swift Synerise.initialize(apiKey: "YOUR_PROFILE_API_KEY") // 1 Synerise.setDebugModeEnabled(false) // 2 Synerise.setCrashHandlingEnabled(true) // 3 Synerise.setDelegate(self) // 4 ```
```Objective-C [SNRSynerise initializeWithApiKey:@"YOUR_PROFILE_API_KEY"]; // 1 [SNRSynerise setDebugModeEnabled:NO]; // 2 [SNRSynerise setCrashHandlingEnabled:YES]; // 3 [SNRSynerise setDelegate:self]; // 4 ```
Basic methods you need: 1. [`Synerise.initialize(apiKey:)`](/developers/mobile-sdk/method-reference/ios/lifecycle#initialization) - Initializes Synerise SDK. 2. [`Synerise.setDebugModeEnabled(_:)`](/developers/mobile-sdk/method-reference/ios/lifecycle#enable-debug-mode) - Enables debug mode for Synerise SDK. See [Debug mode](/developers/mobile-sdk/installation-and-configuration/ios#debug-mode) section for more information. 3. [`Synerise.setCrashHandlingEnabled(_:)`](/developers/mobile-sdk/method-reference/ios/lifecycle#enable-crash-handling) - Enables crash handling. Synerise SDK sends a crash event automatically when an uncaught exception occurs. 4. [`Synerise.setDelegate(_:)`](/developers/mobile-sdk/method-reference/ios/lifecycle#set-synerise-delegate)- Sets delegate to handle main actions from Synerise SDK. See [`SyneriseDelegate`](/developers/mobile-sdk/listeners-and-delegates/ios-delegates#synerise-delegate) section for more information. ### Initialization with custom API environment To change API base URL for on-premise installations, use the following initialization method:
```Swift Synerise.initialize(apiKey: "YOUR_PROFILE_API_KEY", baseUrl: "YOUR_API_BASE_URL") ```
```Objective-C [SNRSynerise initializeWithClientApiKey:@"YOUR_PROFILE_API_KEY" andBaseUrl:@"YOUR_API_BASE_URL"]; ```
### Advanced initialization This is an example of advanced initialization with: - custom API base URL for on-premise installations - request validation salt configured - debug mode enabled - crash handling enabled - most of the settings options available - main delegate [`SyneriseDelegate`](/developers/mobile-sdk/listeners-and-delegates/ios-delegates#synerise-delegate) - client's state delegate [`ClientStateDelegate`](/developers/mobile-sdk/listeners-and-delegates/ios-delegates#client-state-delegate)
We highly recommend to configure settings when Synerise SDK is initialized, before invoking the [`Synerise.initialize(apiKey:)`](/developers/mobile-sdk/method-reference/ios/lifecycle#initialization) method. See [Settings](/developers/mobile-sdk/settings) section for more details about settings options.
Secure sensitive keys (for example, `apiKey` and `requestValidationSalt`) with mechanisms like string obfuscation or encryption.
You can find more information about all [Synerise iOS SDK delegates here](/developers/mobile-sdk/listeners-and-delegates/ios-delegates).
```Swift Synerise.settings.sdk.enabled = true Synerise.settings.sdk.appGroupIdentifier = "YOUR_APP_GROUP_IDENTIFIER" Synerise.settings.sdk.keychainGroupIdentifier = "YOUR_KEYCHAIN_GROUP_IDENTIFIER" Synerise.settings.sdk.minTokenRefreshInterval = 1800 Synerise.settings.sdk.shouldDestroySessionOnApiKeyChange = false Synerise.settings.notifications.enabled = true Synerise.settings.notifications.disableInAppAlerts = true Synerise.settings.notifications.encryption = false Synerise.settings.tracker.autotracking.enabled = true Synerise.settings.tracker.autotracking.mode = AutoTrackMode.Fine Synerise.settings.tracker.autotracking.excludedClasses = [SampleViewController.self] Synerise.settings.tracker.autotracking.excludedViewTags = [0, 1, 2] Synerise.settings.tracker.tracking.enabled = true Synerise.settings.tracker.minBatchSize = 10 Synerise.settings.tracker.maxBatchSize = 100 Synerise.settings.tracker.autoFlushTimeout = 5.0 Synerise.settings.tracker.autoTracking.mode = .fine Synerise.settings.tracker.locationAutomatic = true Synerise.settings.injector.automatic = true Synerise.initialize(apiKey: "YOUR_PROFILE_API_KEY", baseUrl: "YOUR_API_BASE_URL") Synerise.setRequestValidationSalt("YOUR_REQUEST_VALIDATION_SALT") Synerise.setDebugModeEnabled(false) Synerise.setCrashHandlingEnabled(true) Synerise.setDelegate(self) Client.setClientStateDelegate(self) ```
```Objective-C SNRSynerise.settings.sdk.enabled = @YES; SNRSynerise.settings.sdk.appGroupIdentifier = @"YOUR_APP_GROUP_IDENTIFIER"; SNRSynerise.settings.sdk.keychainGroupIdentifier = @"YOUR_KEYCHAIN_GROUP_IDENTIFIER"; SNRSynerise.settings.sdk.minTokenRefreshInterval = 1800; SNRSynerise.settings.sdk.shouldDestroySessionOnApiKeyChange = NO; SNRSynerise.settings.notifications.enabled = YES; SNRSynerise.settings.notifications.disableInAppAlerts = YES; SNRSynerise.settings.notifications.encryption = NO; SNRSynerise.settings.tracker.autotracking.enabled = YES; SNRSynerise.settings.tracker.autotracking.mode = SNRTrackerAutoTrackModeFine; SNRSynerise.settings.tracker.autotracking.excludedClasses = [SampleViewController.class]; SNRSynerise.settings.tracker.autotracking.excludedViewTags = [@0, @2, @3]; SNRSynerise.settings.tracker.tracking.enabled = YES; SNRSynerise.settings.tracker.minBatchSize = 10; SNRSynerise.settings.tracker.maxBatchSize = 100; SNRSynerise.settings.tracker.autoFlushTimeout = 5.0; SNRSynerise.settings.tracker.autoTracking.mode = SNRTrackerAutoTrackModeFine; SNRSynerise.settings.tracker.locationAutomatic = YES; SNRSynerise.settings.injector.automatic = YES; [SNRSynerise initializeWithApiKey:@"YOUR_PROFILE_API_KEY" andBaseUrl:@"YOUR_API_BASE_URL"]; [SNRSynerise setRequestValidationSalt:@"YOUR_REQUEST_VALIDATION_SALT"]; [SNRSynerise setDebugModeEnabled:NO]; [SNRSynerise setCrashHandlingEnabled:YES]; [SNRSynerise setDelegate:self]; [SNRClient setClientStateDelegate:self]; ```
### Initialization process During initialization, the library starts and when it is ready or an error occurs, the SDK notifies you. When the delegate method is called, Synerise is ready to use.
```Swift // MARK: - SyneriseDelegate // This method is called when the Synerise SDK is initialized. func snr_initialized() { //... } // This method is called when an error occurs while initializing the Synerise SDK. func snr_initializationError(error: Error) { //... } ```
```Objective-C #pragma mark - SNRSyneriseDelegate // This method is called when the Synerise SDK is initialized. - (void)SNR_initialized { //... } // This method is called when an error occurs while initializing the Synerise SDK. - (void)SNR_initializationError:(NSError *)error { //... } ```
## Debug Mode --- You can enable debug logs for Synerise SDK by method [`Synerise.setDebugModeEnabled(_:)`](/developers/mobile-sdk/method-reference/ios/lifecycle#enable-debug-mode).
Do not use Debug Mode in a release version of your application.
```Swift Synerise.setDebugModeEnabled(true) // Enables logging for all modules ```
```Objective-C [SNRSynerise setDebugModeEnabled:YES]; // Enables logging for all modules ```
You can receive some logs about: - **Core**: push notifications - **Tracker**: auto-tracked events, declarative events, sending process - **Client**: customer state, authorization - **Injector**: campaigns, UI - **Promotions**: promotions, vouchers - **Content**: content widget, documents, recommendations ## Background Tasks --- [Background Tasks](https://developer.apple.com/documentation/backgroundtasks) is a mechanism to schedule and run code in the background to keep your app up to date. Synerise supports using Background Tasks since SDK version **4.23.0**. You can pass configured identifiers for Synerise SDK by using the [`Synerise.setBackgroundTaskIdentifiers(_:)`](/developers/mobile-sdk/method-reference/ios/lifecycle#set-background-task-identifiers) method. The identifiers that you are going to pass have to be configured properly in the host app. #### Benefits Currently, the SDK uses Background Tasks only to refresh the registration token for Push Notifications every 20 days. In these situations, the SDK invokes the [snr_registerForPushNotificationsIsNeeded(origin:)](/developers/mobile-sdk/listeners-and-delegates/ios-delegates#synerise-delegate-register-for-push-notifications-is-needed-by-origin) method or [snr_registerForPushNotificationsIsNeeded()](/developers/mobile-sdk/listeners-and-delegates/ios-delegates#synerise-delegate-register-for-push-notifications-is-needed) method. #### Setting up To configure Background Tasks in your app: 1. Go to Xcode project's target's **Signing & Capabilities** section. 2. In the **Background Modes** capability (you may need to add it), enable **Background fetch** and **Background processing**. 3. Go to `Info.plist`. 4. Add a row with the following array type value: `Permitted background task scheduler identifiers`. 5. Add string identifiers, each as a separate item to declare possible Background Tasks identifiers in your app. 6. Pass these Background Tasks identifiers to SDK by using the [`Synerise.setBackgroundTaskIdentifiers(_:)`](/developers/mobile-sdk/method-reference/ios/lifecycle#set-background-task-identifiers) method. You must invoke the method **BEFORE** your app is launched (before the `application(_ application:didFinishLaunchingWithOptions launchOptions:)` method finishes). Sample `\*.plist` configuration for Background Tasks:
Sample *.plist configuration for Background Tasks
Sample *.plist configuration for Background Tasks
Example code for passing Background Tasks identifiers to the SDK:
```Swift func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // ... Synerise.setBackgroundTaskIdentifiers(["YOUR_BACKGROUND_TASK_IDENTIFIER"]) return true } ```
```Objective-C - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // ... [SNRSynerise setBackgroundTaskIdentifiers:@[@"YOUR_BACKGROUND_TASK_IDENTIFIER"]]; return YES; } ```
The method's parameter is an array because of possible future purposes.
Do not use those identifiers for other Background Tasks in your app.
Documentation is available at [Apple Developer - Using background tasks to update your app](https://developer.apple.com/documentation/uikit/app_and_environment/scenes/preparing_your_ui_to_run_in_the_background/using_background_tasks_to_update_your_app). **IMPORTANT: To configure Background Tasks properly, you must set `SyneriseDelegate` before the SDK initialization.**
```Swift Synerise.setDelegate(self) Synerise.initialize(apiKey: "YOUR_PROFILE_API_KEY") // ... ```
```Objective-C [SNRSynerise setDelegate:self]; [SNRSynerise initializeWithApiKey:@"YOUR_PROFILE_API_KEY"]; // ... ```
## Privacy manifest --- From **1 May 2024**, Apple requires you to add a privacy manifest. It's a file in your project that describes your reason and method for collecting data. Third-party frameworks that track data should have a privacy manifest. When you create the application privacy report, these privacy manifest files are automatically aggregated into a single file. Synerise supports privacy manifests since SDK version **4.17.0**. When you use an SDK version older than **4.17.0**, refer to the Synerise API usage requirements defined below when creating an Apple privacy manifest. #### APIs usage | API | Reason | Description | | --- | --- | --- | | User defaults APIs | **CA92.1**
**1C8F.1** | Synerise uses User Defaults to persist the SDK data and share them between the application and extensions | #### Tracking Synerise does not track any data that is protected by the [App Tracking Transparency](https://developer.apple.com/documentation/apptrackingtransparency) framework. #### Collected Data | Data type | Value | Purpose | | --- | --- | --- | | User ID | **NSPrivacyCollectedDataTypeUserID** | Analytics, Product Personalization | | Other usage data | **NSPrivacyCollectedDataTypeOtherUsageData** | Analytics, Product Personalization, App Functionality | | Product interaction | **NSPrivacyCollectedDataTypeProductInteraction** | Analytics | | Advertising data | **NSPrivacyCollectedDataTypeAdvertisingData** | Other Purposes, App Functionality | | Crash data | **NSPrivacyCollectedDataTypeOtherUserContent** | Analytics | ## Warnings and limitations --- Be careful with keychain deletion operations due to the possibility of deleting Synerise data. All the SDK library data keys are named `snr.[KEY_NAME]`.