{"_id":"5b720760c44b7600034b79b6","category":{"_id":"5b720760c44b7600034b79a8","__v":35,"pages":["5b720760c44b7600034b79b1","5b720760c44b7600034b79b3","5b720760c44b7600034b79b4","5b720760c44b7600034b79b5","55e682b7de6fef23009480dc","5b720760c44b7600034b79b6","5b720760c44b7600034b79b7","5b720760c44b7600034b79b8","5b720760c44b7600034b79b9","5b720760c44b7600034b79ba","5b720760c44b7600034b79bb","5b720760c44b7600034b79bc","5b720760c44b7600034b79bd","5b720760c44b7600034b79d1","5b720760c44b7600034b79d2","5b720760c44b7600034b79d3","5b720760c44b7600034b79d4","5b720760c44b7600034b79d5","5b720760c44b7600034b79d8","5b720760c44b7600034b79d9","5b720760c44b7600034b79db","561c6ca0be5fb20d00077754","5b720760c44b7600034b79e0","5b720760c44b7600034b79e1","5b720760c44b7600034b79e2","5b720760c44b7600034b79e3","5b720760c44b7600034b79e4","5b720760c44b7600034b79e5","5b720760c44b7600034b79e6","56cfa5386c5d7a13005eec0f","56e73d86555c030e00a52a73","56e7460c9000b120000ffe2e","56e8c19e99c6400e003820cf","56e8c53fc88bf80e00f8bed8","56f06ff4d386ce0e008e9b21"],"project":"55e67aaa9cc7c62b00c4a1ea","version":"5b720760c44b7600034b7a08","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-02T04:30:13.305Z","from_sync":false,"order":1,"slug":"install-in-your-app","title":"Install in your app"},"githubsync":"","__v":41,"user":"55d2bd8e2463351700f67dd7","parentDoc":null,"project":"55e67aaa9cc7c62b00c4a1ea","version":{"_id":"5b720760c44b7600034b7a08","project":"55e67aaa9cc7c62b00c4a1ea","__v":0,"forked_from":"5b1f2cbdfd653400031d8d9f","createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z","categories":["5b720760c44b7600034b79a7","5b720760c44b7600034b79a8","5b720760c44b7600034b79a9","5b720760c44b7600034b79aa","5b720760c44b7600034b79ab","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","5b720760c44b7600034b79ac","5b720760c44b7600034b79ad","5af0fe494ca2730003cbc98a","5af0fe55ec80af0003804ca2"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"API V6","version_clean":"1.4.0","version":"1.4"},"updates":["5823c90c1ea7522f00e9b303"],"next":{"pages":[],"description":""},"createdAt":"2015-09-07T00:13:15.983Z","link_external":false,"link_url":"","sync_unique":"","hidden":true,"api":{"results":{"codes":[]},"settings":"","apiSetting":null,"auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The following steps assume you are targeting a minimum of iOS 8.0+. Sailthru Mobile will not work on earlier versions of iOS.\",\n  \"title\": \"iOS minimum version\"\n}\n[/block]\n# Import the SDK into your project\nThere are two ways to integrate the Sailthru Mobile SDK into your Xcode project - via [CocoaPods](http://cocoapods.org) or manually.\n\n### CocoaPods Integration\n\n1. If you're using [CocoaPods](http://cocoapods.org), you can integrate the SDK simply by adding the following line to your Podfile:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"pod 'Carnival'\",\n      \"language\": \"ruby\",\n      \"name\": \"Podfile (Ruby)\"\n    }\n  ]\n}\n[/block]\n2. Run `pod install` to install.\n\n### Carthage Integration\n\n1. Install Carthage 0.17.0 or later.\n2. Add `github \"carnivalmobile/carnival-ios-sdk\"` to your Cartfile.\n3. Run `carthage update`\n4. Drag Carnival.framework from the appropriate platform directory in Carthage/Build/iOS to the “Linked Frameworks and Libraries” section of your Xcode project’s “General” settings.\n5. On your application targets’ “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script with the following contents:\n`/usr/local/bin/carthage copy-frameworks`\n6. Add the paths to the frameworks you want to use under “Input Files”, e.g.: `$(SRCROOT)/Carthage/Build/iOS/Carnival.framework`. This script works around an [App Store submission bug](http://www.openradar.me/radar?id=6409498411401216) triggered by universal binaries.\n\n\n### Manual Integration\n\nIf you can't use CocoaPods, you can integrate the SDK manually.\n\n1. Download the latest release of the SDK from [Github](https://github.com/carnivalmobile/carnival-ios-sdk/releases) and extract it.\n2. Select `Carnival.framework` in Finder and drag and drop it into your Xcode project.  Make sure “Copy items if needed” is selected, and click “Finish”\n3. Add `Carnival.framework` to embedded binaries\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/62573c3-addframework.gif\",\n        \"addframework.gif\",\n        1151,\n        685,\n        \"#2d2f3b\"\n      ]\n    }\n  ]\n}\n[/block]\n4. Add the required system Frameworks. You can do this by selecting the project reference within Xcode, then your app's target, *Build Phases*, *Link Binary With Libraries*, and then \"*+*\". Find and add the following libraries:\n  * CoreLocation.framework\n  * QuartzCore.framework\n  * UserNotifications.framework\n\n5. To work-around this [app store submission bug](http://www.openradar.me/radar?id=6409498411401216) download the file on our [Framework stripping](doc:framework-stripping) page and place it in the root of your project. \n6. In your target's build settings screen, build phases, add a new run script and enter `bash $SRCROOT/strip-frameworks.sh` in the text box. \n\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Upgrading the SDK\",\n  \"body\": \"To upgrade to the latest version of the SDK, simply repeat the steps above. If you're using Cocoapods, simply run `pod update Carnival` which will use the latest version (unless you've specified a version in your Podfile). If you're using Carthage, use the update commands. Alternatively, download and drag in the updated `Carnival.framework` to your project.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Integrate the initialization code\"\n}\n[/block]\nImport the Carnival header file `#import <Carnival/Carnival.h>` into Objective-C files where you wish to call Carnival. For Swift applications, you'll need to add `#import <Carnival/Carnival.h>` to your [bridging header](https://developer.apple.com/documentation/swift/imported_c_and_objective-c_apis/importing_objective-c_into_swift). \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#import <Carnival/Carnival.h>\\n\\n- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\\n\\t[Carnival startEngine:SDK_KEY]; // Obtain SDK key from your Carnival app settings\\n  return YES;\\n}\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"func application(application: UIApplication, \\ndidFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {\\n\\tCarnival.startEngine(SDK_KEY) // Obtain SDK key from your Carnival app settings\\n  return true\\n}\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"\",\n  \"body\": \"It is important that `startEngine` method is called at the earliest possible opportunity, calling it later in the app lifecycle can have unintended consequences.\"\n}\n[/block]\n## Push Authorization Options\nBy default, calling `startEngine:` will request push authorization to display Alerts, Badges and Sounds to the user. This will display a popup to the user requesting their permission to display these notification options. We recommend that you delay this popup and provide an introductory flow to display the value of your app's push notifications before prompting the user for permission. If you want to do that you can use another method that allows you to specify which push authorizations you would like to request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#import <Carnival/Carnival.h>\\n\\n- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\\n\\t[Carnival startEngine:SDK_KEY withAuthorizationOption:CarnivalPushAuthorizationOptionProvisional]; // Obtain SDK key from your Carnival app settings\\n  return YES;\\n}\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"func application(application: UIApplication, \\ndidFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {\\n\\tCarnival.startEngine(SDK_KEY, with: .provisional) // Obtain SDK key from your Carnival app settings\\n  return true\\n}\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nThe available authorization options are detailed below.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"CarnivalPushAuthorizationOptionNoRequest\",\n    \"0-1\": \"This option will not request any push authorization permissions for the device. Note that a push token will still be requested. No prompt is required.\",\n    \"1-1\": \"This option will request provisional push authorization, allowing push notifications to be sent to the notification center. No prompt is required. Available iOS 12+, defaults to CarnivalPushAuthorizationOptionNoRequest behaviour for earlier versions.\",\n    \"1-0\": \"CarnivalPushAuthorizationOptionProvisional\",\n    \"2-0\": \"CarnivalPushAuthorizationOptionFull\",\n    \"2-1\": \"This option will request full push authorization for alerts, sounds and badges. Note that this will prompt the user for permission.\",\n    \"h-0\": \"Option\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Test your integration\"\n}\n[/block]\nTo make sure it's working, launch your app in your simulator or on your iOS device.  Log in to [Sailthru Mobile](http://sailthru.mobile.com), click on your app, settings and then click on the Developer tab where you should see your device listed.  \n\nThis device log will also show if push notifications are enabled.  \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/eec02e8-device_log.png\",\n        \"device log.png\",\n        2560,\n        1306,\n        \"#152233\"\n      ],\n      \"caption\": \"Viewing the device logs in Sailthru Mobile. This may take a few moments.\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Next Steps\"\n}\n[/block]\n1.  [Setup Push Notifications for iOS](doc:push-notifications-for-ios) to ensure your users can receive push notifications when the app is closed. \n2. [Setup in-app messages](doc:setting-up-in-app-messaging) to enable Sailthru Mobile's rich In-App Messages\n3. [Collect user data](doc:collecting-user-data) to help in segmenting and targeting your users based on their activity.","excerpt":"Integration instructions for iOS Apps using Objective-C or Swift.","slug":"ios-integration","type":"basic","title":"iOS Integration"}

iOS Integration

Integration instructions for iOS Apps using Objective-C or Swift.

[block:callout] { "type": "info", "body": "The following steps assume you are targeting a minimum of iOS 8.0+. Sailthru Mobile will not work on earlier versions of iOS.", "title": "iOS minimum version" } [/block] # Import the SDK into your project There are two ways to integrate the Sailthru Mobile SDK into your Xcode project - via [CocoaPods](http://cocoapods.org) or manually. ### CocoaPods Integration 1. If you're using [CocoaPods](http://cocoapods.org), you can integrate the SDK simply by adding the following line to your Podfile: [block:code] { "codes": [ { "code": "pod 'Carnival'", "language": "ruby", "name": "Podfile (Ruby)" } ] } [/block] 2. Run `pod install` to install. ### Carthage Integration 1. Install Carthage 0.17.0 or later. 2. Add `github "carnivalmobile/carnival-ios-sdk"` to your Cartfile. 3. Run `carthage update` 4. Drag Carnival.framework from the appropriate platform directory in Carthage/Build/iOS to the “Linked Frameworks and Libraries” section of your Xcode project’s “General” settings. 5. On your application targets’ “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script with the following contents: `/usr/local/bin/carthage copy-frameworks` 6. Add the paths to the frameworks you want to use under “Input Files”, e.g.: `$(SRCROOT)/Carthage/Build/iOS/Carnival.framework`. This script works around an [App Store submission bug](http://www.openradar.me/radar?id=6409498411401216) triggered by universal binaries. ### Manual Integration If you can't use CocoaPods, you can integrate the SDK manually. 1. Download the latest release of the SDK from [Github](https://github.com/carnivalmobile/carnival-ios-sdk/releases) and extract it. 2. Select `Carnival.framework` in Finder and drag and drop it into your Xcode project. Make sure “Copy items if needed” is selected, and click “Finish” 3. Add `Carnival.framework` to embedded binaries [block:image] { "images": [ { "image": [ "https://files.readme.io/62573c3-addframework.gif", "addframework.gif", 1151, 685, "#2d2f3b" ] } ] } [/block] 4. Add the required system Frameworks. You can do this by selecting the project reference within Xcode, then your app's target, *Build Phases*, *Link Binary With Libraries*, and then "*+*". Find and add the following libraries: * CoreLocation.framework * QuartzCore.framework * UserNotifications.framework 5. To work-around this [app store submission bug](http://www.openradar.me/radar?id=6409498411401216) download the file on our [Framework stripping](doc:framework-stripping) page and place it in the root of your project. 6. In your target's build settings screen, build phases, add a new run script and enter `bash $SRCROOT/strip-frameworks.sh` in the text box. [block:callout] { "type": "info", "title": "Upgrading the SDK", "body": "To upgrade to the latest version of the SDK, simply repeat the steps above. If you're using Cocoapods, simply run `pod update Carnival` which will use the latest version (unless you've specified a version in your Podfile). If you're using Carthage, use the update commands. Alternatively, download and drag in the updated `Carnival.framework` to your project." } [/block] [block:api-header] { "type": "basic", "title": "Integrate the initialization code" } [/block] Import the Carnival header file `#import <Carnival/Carnival.h>` into Objective-C files where you wish to call Carnival. For Swift applications, you'll need to add `#import <Carnival/Carnival.h>` to your [bridging header](https://developer.apple.com/documentation/swift/imported_c_and_objective-c_apis/importing_objective-c_into_swift). [block:code] { "codes": [ { "code": "#import <Carnival/Carnival.h>\n\n- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\n\t[Carnival startEngine:SDK_KEY]; // Obtain SDK key from your Carnival app settings\n return YES;\n}", "language": "objectivec" }, { "code": "func application(application: UIApplication, \ndidFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {\n\tCarnival.startEngine(SDK_KEY) // Obtain SDK key from your Carnival app settings\n return true\n}", "language": "swift" } ] } [/block] [block:callout] { "type": "warning", "title": "", "body": "It is important that `startEngine` method is called at the earliest possible opportunity, calling it later in the app lifecycle can have unintended consequences." } [/block] ## Push Authorization Options By default, calling `startEngine:` will request push authorization to display Alerts, Badges and Sounds to the user. This will display a popup to the user requesting their permission to display these notification options. We recommend that you delay this popup and provide an introductory flow to display the value of your app's push notifications before prompting the user for permission. If you want to do that you can use another method that allows you to specify which push authorizations you would like to request. [block:code] { "codes": [ { "code": "#import <Carnival/Carnival.h>\n\n- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\n\t[Carnival startEngine:SDK_KEY withAuthorizationOption:CarnivalPushAuthorizationOptionProvisional]; // Obtain SDK key from your Carnival app settings\n return YES;\n}", "language": "objectivec" }, { "code": "func application(application: UIApplication, \ndidFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {\n\tCarnival.startEngine(SDK_KEY, with: .provisional) // Obtain SDK key from your Carnival app settings\n return true\n}", "language": "swift" } ] } [/block] The available authorization options are detailed below. [block:parameters] { "data": { "0-0": "CarnivalPushAuthorizationOptionNoRequest", "0-1": "This option will not request any push authorization permissions for the device. Note that a push token will still be requested. No prompt is required.", "1-1": "This option will request provisional push authorization, allowing push notifications to be sent to the notification center. No prompt is required. Available iOS 12+, defaults to CarnivalPushAuthorizationOptionNoRequest behaviour for earlier versions.", "1-0": "CarnivalPushAuthorizationOptionProvisional", "2-0": "CarnivalPushAuthorizationOptionFull", "2-1": "This option will request full push authorization for alerts, sounds and badges. Note that this will prompt the user for permission.", "h-0": "Option", "h-1": "Description" }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Test your integration" } [/block] To make sure it's working, launch your app in your simulator or on your iOS device. Log in to [Sailthru Mobile](http://sailthru.mobile.com), click on your app, settings and then click on the Developer tab where you should see your device listed. This device log will also show if push notifications are enabled. [block:image] { "images": [ { "image": [ "https://files.readme.io/eec02e8-device_log.png", "device log.png", 2560, 1306, "#152233" ], "caption": "Viewing the device logs in Sailthru Mobile. This may take a few moments." } ] } [/block] [block:api-header] { "type": "basic", "title": "Next Steps" } [/block] 1. [Setup Push Notifications for iOS](doc:push-notifications-for-ios) to ensure your users can receive push notifications when the app is closed. 2. [Setup in-app messages](doc:setting-up-in-app-messaging) to enable Sailthru Mobile's rich In-App Messages 3. [Collect user data](doc:collecting-user-data) to help in segmenting and targeting your users based on their activity.