{"_id":"55ecd69bb2714d2100f227c0","category":{"_id":"55e67b5556007d23005fee7d","__v":35,"pages":["55e67b91de6fef23009480cb","55e67c28de6fef23009480ce","55e67c3cde6fef23009480d1","55e680e185a9741900314e96","55e682b7de6fef23009480dc","55ecd69bb2714d2100f227c0","55ecd6c554a67b1700edcf40","55ecd6edae66a30d00446ce7","55ecd777b2714d2100f227c2","55ecda5a7659d21700a7ef9b","55ecdaf6ae66a30d00446cf3","55ed006a0d968e2100de831e","55ed0258c9d5b3350072ae7a","55ee66a073d3941700f760e5","55f5ef61a1dea80d00a5dec5","55f5f38618b39b0d00c27eb0","55f9f86417b9d00d00969e29","55f9fdc8aba81f0d00a1156d","561b10b4c89cc30d0082154f","561b110a03bce90d00c4bd11","561c6195ad272c0d00a892dd","561c6ca0be5fb20d00077754","564f3e66c133343500286ca0","565b955b922c9a0d00d1f124","566784d2919aaa0d008e32db","566e1ee5972a290d00552084","569c58d77c3e44170014114f","56a2692f6928550d006c8327","56ca6c868014e417002bfe54","56cfa5386c5d7a13005eec0f","56e73d86555c030e00a52a73","56e7460c9000b120000ffe2e","56e8c19e99c6400e003820cf","56e8c53fc88bf80e00f8bed8","56f06ff4d386ce0e008e9b21"],"project":"55e67aaa9cc7c62b00c4a1ea","version":"55e67aab9cc7c62b00c4a1ed","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"},"__v":41,"user":"55d2bd8e2463351700f67dd7","parentDoc":null,"project":"55e67aaa9cc7c62b00c4a1ea","version":{"_id":"55e67aab9cc7c62b00c4a1ed","project":"55e67aaa9cc7c62b00c4a1ea","__v":10,"createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z","categories":["55e67aac9cc7c62b00c4a1ee","55e67b5556007d23005fee7d","55e67b5dde6fef23009480ca","55e680efde6fef23009480db","55e6829485a9741900314e99","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","589b8e1fdbb7cd190026732c","58b8ca5e3265d70f001788d4"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":["5823c90c1ea7522f00e9b303"],"next":{"pages":[],"description":""},"createdAt":"2015-09-07T00:13:15.983Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":true,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The following steps assume you are targeting a minimum of iOS 8.0+. Carnival will not work on earlier versions of iOS. \\n\\nYou can also view our full Apple Doc style reference [here](http://cocoadocs.org/docsets/Carnival/3.7.0/).\",\n  \"title\": \"iOS minimum version\"\n}\n[/block]\n# Import the SDK into your project\nThere are two ways to integrate the Carnival 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  * Security.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](http://swiftalicio.us/2014/11/using-cocoapods-from-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\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 [Carnival](http://app.carnivalmobile.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 Carnival. 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 Carnivals 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+. Carnival will not work on earlier versions of iOS. \n\nYou can also view our full Apple Doc style reference [here](http://cocoadocs.org/docsets/Carnival/3.7.0/).", "title": "iOS minimum version" } [/block] # Import the SDK into your project There are two ways to integrate the Carnival 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 * Security.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](http://swiftalicio.us/2014/11/using-cocoapods-from-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] [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 [Carnival](http://app.carnivalmobile.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 Carnival. 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 Carnivals rich In-App Messages 3. [Collect user data](doc:collecting-user-data) to help in segmenting and targeting your users based on their activity.