Getting Started

Requirements

---

• Access to a Business Profile
• Created Client API Key
• Recommended Environment:
  • Xcode 12
  • iOS SDK 14
• 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

---

CocoaPods

CocoaPods is a dependency manager for Cocoa projects.

If you don’t have CocoaPods installed yet and don’t know it, please start with CocoaPods - Getting Started.

1. Once you have CocoaPods installed you should add dependency to Synerise SDK into your Podfile:

   use_frameworks!
   
   target YOUR_PROJECT_TARGET do
     pod 'SyneriseSDK'
   end
   

2. After that, execute the following shell command in directory depending on your project configuration:

   pod repo update
   pod install
   

Carthage

Carthage is simple, decentralized dependency manager for Cocoa projects.

If you don’t have Carthage installed yet and don’t know it, please start with Carthage project on GitHub.

1. Once you have Carthage installed you should add dependency to Synerise SDK into your Cartfile:

   github "synerise/ios-sdk"
   

2. Then, you should execute shell command in directory depending on your project configuration:

   carthage update
   

3. Go to Xcode project target’s General section.

4. Open <YOUR_XCODE_PROJECT_DIRECTORY>/Carthage/Build/iOS in Finder and drag SyneriseSDK.framework to Embedded Binaries.

5. Make sure Copy items if needed is selected and click Finish.

Initialization

---

Setting up

1. Go to Xcode project target’s General section, find Other Linker Flags property and add -ObjC flag.

2. If you are going to use Push Notifications:

   • Go to Info.plist.
   • Add a row for Required background mode of type Array with App downloads content in response to push notifications or add code below directly:

   <key>UIBackgroundModes</key>
   <array>
       <string>remote-notification</string>
   </array>
   

3. If you are going to use HTTP addresses (instead only HTTPS), you will need to change whitelist domains in your app by adding appropriate configuration to Info.plist.

   • You can add configured domain/domains that you need.
   • Give permission for all domains.

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

   <key>NSAppTransportSecurity</key>
   <dict>
       <key>NSAllowsArbitraryLoads</key><true/>
   </dict>
   

Import Synerise SDK

You will need to import Synerise SDK header into the files that contain code relating to SDK.

SwiftObjective-C

import SyneriseSDK

#import <SyneriseSDK/SyneriseSDK.h>

Note: In Objective-C, you can either include it in your Prefix Header (PCH) and Synerise SDK will be imported to all files automatically.

Basic Initialization

First of all, you need to initialize Synerise SDK and provide Client API Key.

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

SwiftObjective-C

let clientApiKey = "YOUR_CLIENT_API_KEY"

Synerise.initialize(clientApiKey: clientApiKey) // 1
Synerise.setDebugModeEnabled(true) // 2
Synerise.setCrashHandlingEnabled(true) // 3
Synerise.setDelegate(self) // 3

static NSString *clientApiKey = @"YOUR_CLIENT_API_KEY";

[SNRSynerise initializeWithClientApiKey:clientApiKey]; // 1
[SNRSynerise setDebugModeEnabled:YES]; // 2
[SNRSynerise setCrashHandlingEnabled:YES]; // 3
[SNRSynerise setDelegate:self]; // 4

Let’s dive into some configurable functionalities:

1. Synerise.initialize(clientApiKey:) - initializes Synerise SDK.
2. Synerise.setDebugModeEnabled(_:) - enables debug mode for Synerise SDK. See Debug logs section for more information.
3. Synerise.setCrashHandlingEnabled(_:) - enables crash handling. Synerise SDK sends a crash event automatically when an uncaught exception occurs.
4. Synerise.setDelegate(_:) - sets delegate to handle actions from Synerise SDK. See SyneriseDelegate section for more information.

Initialization with custom API environment

There is option to change API base URL for on-premise installations.

One thing you have to do for that is using different initialization method:

SwiftObjective-C

Synerise.initialize(clientApiKey: "YOUR_CLIENT_API_KEY", baseUrl: "YOUR_API_BASE_URL")

static NSString *clientApiKey = @"YOUR_CLIENT_API_KEY";
static NSString *apiBaseUrl = @"YOUR_API_BASE_URL";

[SNRSynerise initializeWithClientApiKey:clientApiKey andBaseUrl:apiBaseUrl];

Advanced Initialization

This is an example of advanced initialization with:

• custom API base URL for on-premise installations
• debug mode enabled
• crash handling enabled
• most of settings options available
• main delegate SNRSyneriseDelegate
• Client’s state delegate SNRClientStateDelegate

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

SwiftObjective-C

Synerise.setDebugModeEnabled(true)
Synerise.setCrashHandlingEnabled(true)

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.setDelegate(self)

Client.setClientStateDelegate(self)

[SNRSynerise setDebugModeEnabled:YES];
[SNRSynerise setCrashHandlingEnabled:YES];

Synerise.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 initializeWithClientApiKey:@"YOUR_CLIENT_API_KEY" andBaseUrl:@"YOUR_API_BASE_URL"];
[SNRSynerise setDelegate:self];

[SNRClient setClientStateDelegate:self];

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.

SwiftObjective-C

Synerise.setDebugModeEnabled(true) // 1
Tracker.setLoggingEnabled(true) // 2

[SNRSynerise setDebugModeEnabled:YES]; // 1
[SNRTracker setLoggingEnabled:YES]; // 2

1. It enables logging for all modules.
2. It enables/disables for concrete module, in this case - Tracker.

You can receive some logs about:

• Core: push notifications
• Tracker: autotracking events, declarative events, sending process
• Client: customer state, authorization
• Injector: campaigns, UI
• Promotions: promotions, vouchers
• Content: content widget, documents, recommendations

Synerise SDK Delegate

---

You can handle Synerise SDK initialization result by two methods:

• snr_initialized() - This method is called when Synerise is initialized.
• snr_initializationError(error:) - This method is called when an error occurs while Synerise initialization.

You can specify your custom action when a customer clicks on simple push, banner or walkthrough. Synerise SDK implements two main actions that customer may invoke - open URL and Deeplink:

• snr_handledAction(url:) - This method is called when Synerise handles URL action from campaign activities.
• snr_handledAction(deepLink:) - This method is called when Synerise handles deeplink action from campaign activities.
• snr_handledAction(url:activity:completionHandler:) - This method is called when Synerise handles URL action from campaign activities.
• snr_handledAction(deepLink:activity:completionHandler:) - This method is called when Synerise handles deeplink action from campaign activities.

Note: For more information about handling actions from Synerise SDK, see Campaigns section.

There is also another method, that invokes when Synerise SDK needs re-registration for push notifications:

• snr_registerForPushNotificationsIsNeeded() - This method is called when Synerise needs registration for Push Notifications.

Note: For more information about notifications, see Push Notifications section.

---