{"_id":"59e70b9ee027ae002e7d2ee1","category":{"_id":"59e70b9ee027ae002e7d2ed3","version":"59e70b9ee027ae002e7d2ed2","project":"5496d393f52a630b00519cdd","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-12-21T14:05:08.721Z","from_sync":false,"order":0,"slug":"service-integration","title":"Service Integration"},"user":"5496d353f52a630b00519cdc","parentDoc":null,"project":"5496d393f52a630b00519cdd","version":{"_id":"59e70b9ee027ae002e7d2ed2","project":"5496d393f52a630b00519cdd","__v":2,"createdAt":"2017-10-18T08:06:54.462Z","releaseDate":"2017-10-18T08:06:54.462Z","categories":["59e70b9ee027ae002e7d2ed3","59e70b9ee027ae002e7d2ed4","59e70b9ee027ae002e7d2ed5","59e70b9ee027ae002e7d2ed6","59e70b9ee027ae002e7d2ed7","59e70b9ee027ae002e7d2ed8","59e70b9ee027ae002e7d2ed9","59e70b9ee027ae002e7d2eda","59e70b9ee027ae002e7d2edb","59e70b9ee027ae002e7d2edc","59e70b9ee027ae002e7d2edd","59e70b9ee027ae002e7d2ede","59e70b9ee027ae002e7d2edf","5b8661ccdd19310003a3fa0b"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"2.0.10","version":"2.0.10"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-12-21T15:41:19.714Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"##Requirements\n  * Requires iOS 8+, armv7+armv7s\n  * Requires Xcode 7 or later\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 1: Get CocoaPods\"\n}\n[/block]\nThe Placer SDK for iOS is available as a [CocoaPods](https://cocoapods.org/) pod. CocoaPods is an open source dependency manager for Swift and Objective-C Cocoa projects.\n\nIf you don't already have the CocoaPods tool, install it on OS X by running the following command from the terminal. For details, see the [CocoaPods Getting Started guide](http://google.com).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ sudo gem install cocoapods\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 2: Install the API using CocoaPods\"\n}\n[/block]\nCreate a **Podfile** for the Placer SDK for iOS and use it to install the API and its dependencies:\n1. If you don't have an Xcode project yet, create one now and save it to your local machine. \n2. Go to your project folder using the terminal and run the pod init command:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ pod init\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n3. A file named **Podfile** should have been created in your project directory. If it wasn't, please create a new file named \"Podfile\". This file defines your project's dependencies, and is commonly referred to as a Podspec.\n\n4. Edit the Podfile and add the Placer Source (https://placer-integration:::at:::bitbucket.org/placer-io/Specs.git) and Pod as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"source 'https://placer-integration@bitbucket.org/placer-io/Specs.git'\\nsource 'https://github.com/CocoaPods/Specs.git'\\n\\ntarget 'YourApp' do\\n  \\n  pod 'Placer', '~> 1.5.0'\\n\\t\\n  # Other pods\\n\\nend\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note\",\n  \"body\": \"The Placer SDK is not publicly available and the first source link ('https://placer-integration@bitbucket.org/placer-io/Specs.git') is used to pull the Pod from Placer's private repository.\\nThe second source link ('https://github.com/CocoaPods/Specs.git') is used in order to use the CocoaPods public repository.\"\n}\n[/block]\n5. Save the Podfile.\n\n6. Go to your project folder using the terminal and run the pod install command. This will install the APIs specified in the Podspec, along with any dependencies they may have.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ pod install\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"When prompted to enter a password, use the one provided by your account manager. The Password is also available in the dashboard in the[ \\\"download SDK\\\" section.](https://dashboard.placer.io/#/download)\",\n  \"title\": \"Important\"\n}\n[/block]\n7. Close Xcode, and then open (double-click) your project's **.xcworkspace** file to launch Xcode. From this time onwards, you must use the **.xcworkspace** file to open the project.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 3: Add location permissions to your plist file\"\n}\n[/block]\nLocation tracking in iOS requires adding descriptions for collecting location data. Set them by adding new rows in the app’s info plist named:\n  * **“NSLocationAlwaysUsageDescription”**\n  * **“NSLocationAlwaysAndWhenInUseUsageDescription ”**\n  * **“NSLocationWhenInUseUsageDescription”**\n\nBased on your application’s use case, write a description that best fits your location usage and set it as the attribute value.. This description will be presented to the user in the relevant location permission approval dialog alerts.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/86f2473-permissions.png\",\n        \"permissions.png\",\n        1535,\n        737,\n        \"#dedddc\"\n      ],\n      \"sizing\": \"smart\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Important\",\n  \"body\": \"- As of iOS 11, in order to get the \\\"Always\\\" location permission, the user must be presented with the \\\"When-in-use\\\" permission as well. **Therefore, you must include all of the 3 plist attributes mentioned above**.\\n\\n- The Placer SDK default behavior is presenting the \\\"When-in-use\\\" permission alert followed by the \\\"Always\\\". If you wish to manage the permissions alerts yourself (highly recommended), activate Placer with the \\\"disableLocationPermissionAlerts\\\" parameter set to Yes. See [iOS Customization](doc:customization) for further details.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Activate The SDK\"\n}\n[/block]\n1. If you are using Objective-C, Include the Placer library in your **AppDelegate.m**. If you are using Swift, include it in your **Objective-C Bridging Header** file; If you don't have one, please follow Apple's instructions [here](https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"//In your AppDelegate.m file\\n#import <Placer/Placer.h>\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"//In your Objective-C Bridging Header file\\n#import <Placer/Placer.h>\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n2. Activate Placer with one line of code in the beginning of your application **delegates application**: **didFinishLaunchingWithOptions**: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#import \\\"AppDelegate.h\\\"\\n#import <Placer/Placer.h>\\n\\n@implementation AppDelegate\\n\\n- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions\\n{\\n  //Activate Placer SDK\\n    [Placer activateWithAppKey:@\\\"APP KEY GOES HERE\\\" \\t\\n     \\t\\t\\t\\t\\tandLaunchOptions:launchOptions];\\n  \\n    return YES;\\n}\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"@UIApplicationMain\\nclass AppDelegate: UIResponder, UIApplicationDelegate {\\n        func application(application: UIApplication,didFinishLaunchingWithOptions\\n        \\t\\t\\t\\t\\t\\t\\t launchOptions: [NSObject: AnyObject]?) -> Bool {\\n        \\n        [Placer .activateWithAppKey(\\\"APP KEY GOES HERE\\\",\\n            andLaunchOptions: launchOptions)];\\n\\n        \\n        // The rest of your code\\n        return true\\n    }\\n\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"App Key\",\n  \"body\": \"Make sure you set your App Key at the relevant place.Your app key is shown in the placer's [Dashboard](https://dashboard.placer.io/#/applications/settings), under the \\\"settings\\\" tab.\"\n}\n[/block]\n3. By setting the **PLUserInfoAppUserId** with your User ID you can query insights from Placer's server using your own custom IDs (*Note:* User ID cannot be longer than 100 characters).\nSetting the user gender (**PLUserInfoGender**) and date-of-birth (**PLUserInfoBirthday**) will improve location tracking and venue detection (*Note: These attributes are optional*). \nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"NSDictionary *customData = @{PLUserInfoAppUserId : @\\\"Your_User_ID\\\",\\n                                 PLUserInfoGender:@\\\"male\\\",\\n                               PLUserInfoBirthday:@\\\"1980-12-30\\\"};\\n[Placer setUserInfo:customData];\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"[Placer .setUserInfo([PLUserInfoAppUserId:\\\"YOUR USER ID\\\"])];\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n**All Done!**\n\nPlacer will collect device signals and generate accurate user insights. \nFor advanced usage options, see [iOS SDK Customization](doc:customization).\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Placer collects location in background mode, which, according to Apple guidelines, requires a special disclaimer when submitting to the App Store. Here are a couple of examples that fit the guidelines:\\n\\\"Continued use of GPS running in the background can dramatically decrease battery life.\\\"\\n“Continued use of location data can reduce battery life, though this app minimizes battery consumption by selectively collecting locations.”\",\n  \"title\": \"Important Note\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Integration Test\"\n}\n[/block]\nAfter completing the SDK integration process and running your application at least once, you can test Placer integration with the [Admin Dashboard](https://dashboard.placer.io/).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Uploading a location based version to iTunes for the first time\"\n}\n[/block]\nWhen uploading a version with a new location based feature to Apple's app store, the store's guidelines require the following to be added to the app's description:\n  * A description of the background location tracking feature and its benefits to the user\n  * A battery disclaimer, such as this: \"Note: this app makes use of iOS location based services. Continued use of location data can reduce battery life, though we minimize battery consumption by selectively collecting locations.\" (consider replacing 'this app' with your app's name).","excerpt":"","slug":"ios","type":"basic","title":"iOS - Quick Start"}
##Requirements * Requires iOS 8+, armv7+armv7s * Requires Xcode 7 or later [block:api-header] { "type": "basic", "title": "Step 1: Get CocoaPods" } [/block] The Placer SDK for iOS is available as a [CocoaPods](https://cocoapods.org/) pod. CocoaPods is an open source dependency manager for Swift and Objective-C Cocoa projects. If you don't already have the CocoaPods tool, install it on OS X by running the following command from the terminal. For details, see the [CocoaPods Getting Started guide](http://google.com). [block:code] { "codes": [ { "code": "$ sudo gem install cocoapods", "language": "shell" } ] } [/block] [block:api-header] { "type": "basic", "title": "Step 2: Install the API using CocoaPods" } [/block] Create a **Podfile** for the Placer SDK for iOS and use it to install the API and its dependencies: 1. If you don't have an Xcode project yet, create one now and save it to your local machine. 2. Go to your project folder using the terminal and run the pod init command: [block:code] { "codes": [ { "code": "$ pod init", "language": "shell" } ] } [/block] 3. A file named **Podfile** should have been created in your project directory. If it wasn't, please create a new file named "Podfile". This file defines your project's dependencies, and is commonly referred to as a Podspec. 4. Edit the Podfile and add the Placer Source (https://placer-integration@bitbucket.org/placer-io/Specs.git) and Pod as follows: [block:code] { "codes": [ { "code": "source 'https://placer-integration@bitbucket.org/placer-io/Specs.git'\nsource 'https://github.com/CocoaPods/Specs.git'\n\ntarget 'YourApp' do\n \n pod 'Placer', '~> 1.5.0'\n\t\n # Other pods\n\nend", "language": "text" } ] } [/block] [block:callout] { "type": "info", "title": "Note", "body": "The Placer SDK is not publicly available and the first source link ('https://placer-integration@bitbucket.org/placer-io/Specs.git') is used to pull the Pod from Placer's private repository.\nThe second source link ('https://github.com/CocoaPods/Specs.git') is used in order to use the CocoaPods public repository." } [/block] 5. Save the Podfile. 6. Go to your project folder using the terminal and run the pod install command. This will install the APIs specified in the Podspec, along with any dependencies they may have. [block:code] { "codes": [ { "code": "$ pod install", "language": "shell" } ] } [/block] [block:callout] { "type": "warning", "body": "When prompted to enter a password, use the one provided by your account manager. The Password is also available in the dashboard in the[ \"download SDK\" section.](https://dashboard.placer.io/#/download)", "title": "Important" } [/block] 7. Close Xcode, and then open (double-click) your project's **.xcworkspace** file to launch Xcode. From this time onwards, you must use the **.xcworkspace** file to open the project. [block:api-header] { "type": "basic", "title": "Step 3: Add location permissions to your plist file" } [/block] Location tracking in iOS requires adding descriptions for collecting location data. Set them by adding new rows in the app’s info plist named: * **“NSLocationAlwaysUsageDescription”** * **“NSLocationAlwaysAndWhenInUseUsageDescription ”** * **“NSLocationWhenInUseUsageDescription”** Based on your application’s use case, write a description that best fits your location usage and set it as the attribute value.. This description will be presented to the user in the relevant location permission approval dialog alerts. [block:image] { "images": [ { "image": [ "https://files.readme.io/86f2473-permissions.png", "permissions.png", 1535, 737, "#dedddc" ], "sizing": "smart" } ] } [/block] [block:callout] { "type": "warning", "title": "Important", "body": "- As of iOS 11, in order to get the \"Always\" location permission, the user must be presented with the \"When-in-use\" permission as well. **Therefore, you must include all of the 3 plist attributes mentioned above**.\n\n- The Placer SDK default behavior is presenting the \"When-in-use\" permission alert followed by the \"Always\". If you wish to manage the permissions alerts yourself (highly recommended), activate Placer with the \"disableLocationPermissionAlerts\" parameter set to Yes. See [iOS Customization](doc:customization) for further details." } [/block] [block:api-header] { "type": "basic", "title": "Activate The SDK" } [/block] 1. If you are using Objective-C, Include the Placer library in your **AppDelegate.m**. If you are using Swift, include it in your **Objective-C Bridging Header** file; If you don't have one, please follow Apple's instructions [here](https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html). [block:code] { "codes": [ { "code": "//In your AppDelegate.m file\n#import <Placer/Placer.h>", "language": "objectivec" }, { "code": "//In your Objective-C Bridging Header file\n#import <Placer/Placer.h>", "language": "swift" } ] } [/block] 2. Activate Placer with one line of code in the beginning of your application **delegates application**: **didFinishLaunchingWithOptions**: [block:code] { "codes": [ { "code": "#import \"AppDelegate.h\"\n#import <Placer/Placer.h>\n\n@implementation AppDelegate\n\n- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions\n{\n //Activate Placer SDK\n [Placer activateWithAppKey:@\"APP KEY GOES HERE\" \t\n \t\t\t\t\tandLaunchOptions:launchOptions];\n \n return YES;\n}", "language": "objectivec" }, { "code": "@UIApplicationMain\nclass AppDelegate: UIResponder, UIApplicationDelegate {\n func application(application: UIApplication,didFinishLaunchingWithOptions\n \t\t\t\t\t\t\t launchOptions: [NSObject: AnyObject]?) -> Bool {\n \n [Placer .activateWithAppKey(\"APP KEY GOES HERE\",\n andLaunchOptions: launchOptions)];\n\n \n // The rest of your code\n return true\n }\n", "language": "swift" } ] } [/block] [block:callout] { "type": "success", "title": "App Key", "body": "Make sure you set your App Key at the relevant place.Your app key is shown in the placer's [Dashboard](https://dashboard.placer.io/#/applications/settings), under the \"settings\" tab." } [/block] 3. By setting the **PLUserInfoAppUserId** with your User ID you can query insights from Placer's server using your own custom IDs (*Note:* User ID cannot be longer than 100 characters). Setting the user gender (**PLUserInfoGender**) and date-of-birth (**PLUserInfoBirthday**) will improve location tracking and venue detection (*Note: These attributes are optional*). Example: [block:code] { "codes": [ { "code": "NSDictionary *customData = @{PLUserInfoAppUserId : @\"Your_User_ID\",\n PLUserInfoGender:@\"male\",\n PLUserInfoBirthday:@\"1980-12-30\"};\n[Placer setUserInfo:customData];", "language": "objectivec" }, { "code": "[Placer .setUserInfo([PLUserInfoAppUserId:\"YOUR USER ID\"])];", "language": "swift" } ] } [/block] **All Done!** Placer will collect device signals and generate accurate user insights. For advanced usage options, see [iOS SDK Customization](doc:customization). [block:callout] { "type": "warning", "body": "Placer collects location in background mode, which, according to Apple guidelines, requires a special disclaimer when submitting to the App Store. Here are a couple of examples that fit the guidelines:\n\"Continued use of GPS running in the background can dramatically decrease battery life.\"\n“Continued use of location data can reduce battery life, though this app minimizes battery consumption by selectively collecting locations.”", "title": "Important Note" } [/block] [block:api-header] { "type": "basic", "title": "Integration Test" } [/block] After completing the SDK integration process and running your application at least once, you can test Placer integration with the [Admin Dashboard](https://dashboard.placer.io/). [block:api-header] { "type": "basic", "title": "Uploading a location based version to iTunes for the first time" } [/block] When uploading a version with a new location based feature to Apple's app store, the store's guidelines require the following to be added to the app's description: * A description of the background location tracking feature and its benefits to the user * A battery disclaimer, such as this: "Note: this app makes use of iOS location based services. Continued use of location data can reduce battery life, though we minimize battery consumption by selectively collecting locations." (consider replacing 'this app' with your app's name).