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.

Important: The 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.

Requirements

You need:

Access to a workspace
A Profile API Key
When creating the API key, use allowlisting or denylisting to only allow the events you intend to use.
Installed CocoaPods - CocoaPods is a dependency manager for Cocoa projects.
Installed Carthage - Carthage is a simple, decentralized dependency manager for Cocoa projects.
Recommended environment:
- Xcode 15
- iOS SDK 17
Target deployment: iOS 9.0+

Frameworks

The Synerise SDK references the following frameworks:

Foundation.framework
UIKit.framework
CoreGraphics.framework
SystemConfiguration.framework
MobileCoreServices.framework
CoreTelephony.framework
Security.framework
CommonCrypto.framework
WebKit.framework
UserNotifications.framework

Installation

Add CocoaPods dependency to Synerise SDK into your Podfile:

    use_frameworks!

    target YOUR_PROJECT_TARGET do
      pod 'SyneriseSDK'
    end

Execute the following shell command in the directory depending on your project configuration:
```
    pod repo update  
    pod install
    
```
Add the Carthage dependency to Synerise SDK into your Cartfile:
```
    github "synerise/ios-sdk"
    
```
Execute the shell command in directory depending on your project configuration:
```
    carthage update
    
```
Go to Xcode project target’s General section.
In Finder, open <YOUR_XCODE_PROJECT_DIRECTORY>/Carthage/Build/iOS
Drag SyneriseSDK.framework to Embedded Binaries.
Make sure the Copy items if needed option is selected.
Click Finish.

Initialization

Setting up

Go to Xcode project target’s General section.
Find the Other Linker Flags property and add the -ObjC flag.
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>
    
```

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.

import SyneriseSDK

Note: 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.

You may initialize it wherever you want and when you need.

Synerise.initialize(clientApiKey: "YOUR_CLIENT_API_KEY") // 1
Synerise.setRequestValidationSalt("YOUR_REQUEST_VALIDATION_SALT") // 2
Synerise.setDebugModeEnabled(false) // 3
Synerise.setCrashHandlingEnabled(true) // 4
Synerise.setDelegate(self) // 5

Basic methods you need:

Synerise.initialize(clientApiKey:) - Initializes Synerise SDK.
Synerise.setRequestValidationSalt(string:) - Sets salt string for request validation.
Synerise.setDebugModeEnabled(_:) - Enables debug mode for Synerise SDK. See Debug logs section for more information.
Synerise.setCrashHandlingEnabled(_:) - Enables crash handling. Synerise SDK sends a crash event automatically when an uncaught exception occurs.
Synerise.setDelegate(_:) - Sets delegate to handle main actions from Synerise SDK. See SyneriseDelegate section for more information.

Initialization with custom API environment

To change API base URL for on-premise installations, use the following initialization method:

Synerise.initialize(clientApiKey: "YOUR_PROFILE_API_KEY", baseUrl: "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
client’s state delegate ClientStateDelegate

Important: We highly recommend to configure settings when Synerise SDK is initialized, before invoking the Synerise.initialize(clientApiKey:) method. See Settings section for more details about settings options.

Important: Secure sensitive keys (for example, clientApiKey and requestValidationSalt) with mechanisms like string obfuscation or encryption.

Note: You can find more information about all Synerise iOS SDK delegates here.

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(clientApiKey: "YOUR_CLIENT_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)

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.

// MARK: - SyneriseDelegate

// This function is called when Synerise is fully initialized and ready.
func snr_initialized() {
  //...
}

// This function is called when an error occurs during Synerise initialization.
func snr_initializationError(error: Error) {
  //...
}

Debug Mode

You can enable debug logs for Synerise SDK by method Synerise.setDebugModeEnabled(_:).

WARNING: Do not use Debug Mode in a release version of your application.

Synerise.setDebugModeEnabled(true) // 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

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].