{"_id":"58aad9df8f862f250076fa53","project":"54aa7f773b56130b0056c86e","category":{"_id":"58aad9dd8f862f250076f9f7","version":"58aad9dd8f862f250076f9f4","project":"54aa7f773b56130b0056c86e","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-01-05T12:43:51.897Z","from_sync":false,"order":3,"slug":"ios-sdk","title":"iOS SDK"},"parentDoc":null,"user":"54aa7f3f9bb00c0b00cb899b","__v":0,"version":{"_id":"58aad9dd8f862f250076f9f4","project":"54aa7f773b56130b0056c86e","__v":2,"createdAt":"2017-02-20T11:58:21.765Z","releaseDate":"2017-02-20T11:58:21.765Z","categories":["58aad9dd8f862f250076f9f5","58aad9dd8f862f250076f9f6","58aad9dd8f862f250076f9f7","58aad9dd8f862f250076f9f8","58aad9dd8f862f250076f9f9","58aad9dd8f862f250076f9fa","58aad9dd8f862f250076f9fb","58ac26b3d460ce2500185d26"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"Locate","version_clean":"6.0.0","version":"6.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-05-13T14:06:38.430Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"After you've successfully integrated the Locate SDK with your project you should import the library umbrella header: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#import <LOCLocate/LOCLocate.h>\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import LOCLocate\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\niOS enables CoreLocation to wake up a terminated apps so they can react to monitored regions actions. In order for that functionality to work you need to instantiate the Locate SDK in *application:didFinishLaunchingWithOptions* method of your *AppDelegate* and pass the *launchOptions* dictionary to Pulsate.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#import <LOCLocate/LOCLocate.h>\\n\\n:::at:::implementation AppDelegate\\n\\n- (BOOL)application:(UIApplication *)application\\n  didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\\n    NSError* error;\\n\\n\\t\\tLOCAuthorizationData* authData = [[LOCAuthorizationData alloc] initWithAppId:@\\\"YOUR_SDK_APP_ID\\\" andAppKey:@\\\"YOUR_SDK_APP_KEY\\\" validationError:&error];\\n    \\n    LOCLocateManager* locateManager = [LOCLocateFactory getInstanceWithAuthorizationData:authData withLocationEnabled:YES withPushEnabled:YES withLaunchOptions:launchOptions error:&error];\\n\\n\\t\\t[_locateManager startLocateSession];\\n   \\n    return YES;\\n}\\n\\n\\n@end\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"class AppDelegate {\\n\\n    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject : AnyObject]?) -> Bool {\\n        var error: NSError\\n        var authData: LOCAuthorizationData = LOCAuthorizationData(appId: \\\"YOUR_SDK_APP_ID\\\", andAppKey: \\\"YOUR_SDK_APP_KEY\\\")\\n        \\n        let locateManager = LOCLocateFactory.getInstanceWithAuthorizationData(authData, withLocationEnabled: true, withPushEnabled: true, withLaunchOptions: launchOptions, error: error)\\n        \\n        locateManager.startLocateSession()\\n        \\n        return true\\n    }\\n}\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Locate SDK sets a new delegate for *UIApplication* so it can do all the heavy lifting for you. \\nYou will receive all *UIApplicationDelegate* callbacks, as they are forwarded to the original AppDelegate. \\n\\nRemember to not to change the *delegate* property of *UIApplication* after instantiating Locate.\",\n  \"title\": \"\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authorization Keys\"\n}\n[/block]\nSDK App Key and SDK App ID are used to associate the Locate framework with your Pulsate application which was created using Pulsate web panel.\n\nSDK App ID and SDK App Key can be found in your app settings screen. To find them log into the Pulsate web interface and click the **CONFIGURE** icon on the main menu, your ID and KEY will be displayed here.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8d58099-SDK_Connect.png\",\n        \"SDK Connect.png\",\n        2380,\n        378,\n        \"#e3e3e3\"\n      ]\n    }\n  ]\n}\n[/block]\nYou need to instantiate the *LOCAuthorizationData* object with these keys: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"NSError* error;\\n\\nLOCAuthorizationData* authData = [[LOCAuthorizationData alloc] initWithAppId:@\\\"YOUR_SDK_APP_ID\\\" andAppKey:@\\\"YOUR_SDK_APP_KEY\\\" validationError:&error];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\nvar error: NSError\\nvar authData: LOCAuthorizationData = LOCAuthorizationData(appId: \\\"YOUR_SDK_APP_ID\\\", andAppKey: \\\"YOUR_SDK_APP_KEY\\\", validationError: error)\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Locate Factory\"\n}\n[/block]\nIn order to instantiate the Locate Manager you need to use the *LOCLocateFactory*. It creates and holds the Locate Manager instance, making sure there's only one per application.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"NSError* error;\\n\\nLOCAuthorizationData* authData = [[LOCAuthorizationData alloc] initWithAppId:@\\\"YOUR_SDK_APP_ID\\\" andAppKey:@\\\"YOUR_SDK_APP_KEY\\\" validationError:&error];\\n    \\nLOCLocateManageer* locateManager = [LOCLocateFactory getInstanceWithAuthorizationData:authData andLocationEnabled:YES withPushEnabled:YES withLaunchOptions:launchOptions error:&error];\\n\\n[locateManager startLocateSession];\\n    \",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var error: NSError\\nvar authData: LOCAuthorizationData = LOCAuthorizationData(appId: \\\"YOUR_SDK_APP_ID\\\", andAppKey: \\\"YOUR_SDK_APP_KEY\\\", validationError: error)\\n        \\nlet locateManager = LOCLocateFactory.getInstanceWithAuthorizationData(authData, withLocationEnabled: true, withPushEnabled: true, withLaunchOptions: launchOptions, error: error)\\n        \\nlocateManager.startLocateSession()\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n**Delaying startLocate Session**\n\nYou can delay the *startLocateSession* method call. For example, you can call it after the user successfully logins into your app so that only users that successfully log into your app are added to Locate and receive content from Locate. Here is an example of how to delay *startLocateSession* until after the user has logged in:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"-(void)userLoggedInSuccessfully\\n{\\n  LOCLocateManager* locateManager = [LOCLocateFactory getDefaultInstance];\\n  [locateManager startLocateSession];\\n}\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"func userLoggedInSuccessfully() {\\n    let locateManager: LOCLocateManager = LOCLocateFactory.getDefaultInstance()\\n    locateManager.startLocateSession()\\n}\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nThe *startLocateSession* method starts the session lifecycle and remote notifications, location if passed in parameters as *YES*. \n\nIf you delay the Locate Session make sure that *\"startLocateSession\"* is still called in your *application:didFinishLaunchingWithOptions* method after the first session delay. \n\nIn the example below we delay the first session until the user logs in, after the first log the \"*startLocateSession*\" will be called every time the *application:didFinishLaunchingWithOptions* method gets called by the system.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#import <LOCLocate/LOCLocate.h>\\n\\n@implementation AppDelegate\\n\\n- (BOOL)application:(UIApplication *)application\\n  didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\\n    NSError* error;\\n\\n\\t\\tLOCAuthorizationData* authData = [[LOCAuthorizationData alloc] initWithAppId:@\\\"YOUR_SDK_APP_ID\\\" andAppKey:@\\\"YOUR_SDK_APP_KEY\\\" validationError:&error];\\n    \\n    LOCLocateManager* locationManager = [LOCLocateFactory getInstanceWithAuthorizationData:authData withLocationEnabled:YES withPushEnabled:YES withLaunchOptions:launchOptions error:&error];\\n\\n    if (userLoggedIn == YES)\\n\\t\\t\\t[locateManager startLocateSession];\\n   \\n    return YES;\\n}\\n\\n\\n@end\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"class AppDelegate {\\n\\n    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject : AnyObject]?) -> Bool {\\n        var error: NSError\\n        var authData: LOCAuthorizationData = LOCAuthorizationData(appId: \\\"YOUR_SDK_APP_ID\\\", andAppKey: \\\"YOUR_SDK_APP_KEY\\\", validationError: error)\\n        \\n        let locateManager = LOCLocateFactory.getInstanceWithAuthorizationData(authData, withLocationEnabled: true, withPushEnabled: true, withLaunchOptions: launchOptions, error: error)\\n        \\n        if (userLoggedIn)\\n        \\tlocateManager.startLocateSession()\\n        \\n        return true\\n    }\\n}\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nThe factory will instantiate only one object per application. If a Locate Manger object already exists it will return it, instead of creating a new one.\n\nIn order to easily get the instantiated Locate Manager object you can use the *getDefaultInstance* method of the factory:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"LOCLocateManager* locateManager = [LOCLocateFactory getDefaultInstance];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"let locateManager = LOCLocateFactory.getDefaultInstance()\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authorization Prompts\"\n}\n[/block]\nDuring the Locate Manager instantiation you can declare if you want remote notifications or location authorization prompts to be shown when the *startLocateSession* method is called. You can delay these prompts by passing *NO* and using  *startLocation*, *startRemoteNotifications* at your convenience.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"LOCLocateManager* locateManager = [LOCLocateFactory getInstanceWithAuthorizationData:authData andLocationEnabled:NO withRemoteNotificationsEnabled:NO withLaunchOptions:launchOptions error:&error];\\n\\n[locateManager startLocateSession];\\n\\n\\t// The session lifecycle has started, but without remote notifications \\tand location\\n\\n\\t//... \\n\\n\\t// At the time of your convenience you can start the modules you want and present the authorization prompts to the user.\\n\\n[locateManager startLocation];\\n\\n// You can also use the startRemoteNotificationsWithSettings: method if you want to pass custom UIUserNotificationSettings settings \\n[locateManager startRemoteNotifications];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var locateManager: LOCLocateManager = LOCLocateFactory.getInstanceWithAuthorizationData(authData, andLocationEnabled: false, withRemoteNotificationsEnabled: false, withLaunchOptions: launchOptions, error: error)\\n\\nlocateManager.startLocateSession()\\n\\n// The session lifecycle has started, but without remote notifications \\tand location\\n//... \\n// At the time of your convenience you can start the modules you want and present the authorization prompts to the user.\\n\\nlocateManager.startLocation()\\n// You can also use the startRemoteNotificationsWithSettings: method if you want to pass custom UIUserNotificationSettings settings \\nlocateManager.startRemoteNotifications()\\n\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"running-the-pulsate-sdk","type":"basic","title":"Running the Locate SDK"}

Running the Locate SDK


After you've successfully integrated the Locate SDK with your project you should import the library umbrella header: [block:code] { "codes": [ { "code": "#import <LOCLocate/LOCLocate.h>", "language": "objectivec" } ] } [/block] [block:code] { "codes": [ { "code": "import LOCLocate", "language": "swift" } ] } [/block] iOS enables CoreLocation to wake up a terminated apps so they can react to monitored regions actions. In order for that functionality to work you need to instantiate the Locate SDK in *application:didFinishLaunchingWithOptions* method of your *AppDelegate* and pass the *launchOptions* dictionary to Pulsate. [block:code] { "codes": [ { "code": "#import <LOCLocate/LOCLocate.h>\n\n@implementation AppDelegate\n\n- (BOOL)application:(UIApplication *)application\n didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\n NSError* error;\n\n\t\tLOCAuthorizationData* authData = [[LOCAuthorizationData alloc] initWithAppId:@\"YOUR_SDK_APP_ID\" andAppKey:@\"YOUR_SDK_APP_KEY\" validationError:&error];\n \n LOCLocateManager* locateManager = [LOCLocateFactory getInstanceWithAuthorizationData:authData withLocationEnabled:YES withPushEnabled:YES withLaunchOptions:launchOptions error:&error];\n\n\t\t[_locateManager startLocateSession];\n \n return YES;\n}\n\n\n@end", "language": "objectivec" } ] } [/block] [block:code] { "codes": [ { "code": "class AppDelegate {\n\n func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject : AnyObject]?) -> Bool {\n var error: NSError\n var authData: LOCAuthorizationData = LOCAuthorizationData(appId: \"YOUR_SDK_APP_ID\", andAppKey: \"YOUR_SDK_APP_KEY\")\n \n let locateManager = LOCLocateFactory.getInstanceWithAuthorizationData(authData, withLocationEnabled: true, withPushEnabled: true, withLaunchOptions: launchOptions, error: error)\n \n locateManager.startLocateSession()\n \n return true\n }\n}", "language": "swift" } ] } [/block] [block:callout] { "type": "info", "body": "Locate SDK sets a new delegate for *UIApplication* so it can do all the heavy lifting for you. \nYou will receive all *UIApplicationDelegate* callbacks, as they are forwarded to the original AppDelegate. \n\nRemember to not to change the *delegate* property of *UIApplication* after instantiating Locate.", "title": "" } [/block] [block:api-header] { "type": "basic", "title": "Authorization Keys" } [/block] SDK App Key and SDK App ID are used to associate the Locate framework with your Pulsate application which was created using Pulsate web panel. SDK App ID and SDK App Key can be found in your app settings screen. To find them log into the Pulsate web interface and click the **CONFIGURE** icon on the main menu, your ID and KEY will be displayed here. [block:image] { "images": [ { "image": [ "https://files.readme.io/8d58099-SDK_Connect.png", "SDK Connect.png", 2380, 378, "#e3e3e3" ] } ] } [/block] You need to instantiate the *LOCAuthorizationData* object with these keys: [block:code] { "codes": [ { "code": "NSError* error;\n\nLOCAuthorizationData* authData = [[LOCAuthorizationData alloc] initWithAppId:@\"YOUR_SDK_APP_ID\" andAppKey:@\"YOUR_SDK_APP_KEY\" validationError:&error];", "language": "objectivec" } ] } [/block] [block:code] { "codes": [ { "code": "\nvar error: NSError\nvar authData: LOCAuthorizationData = LOCAuthorizationData(appId: \"YOUR_SDK_APP_ID\", andAppKey: \"YOUR_SDK_APP_KEY\", validationError: error)", "language": "swift" } ] } [/block] [block:api-header] { "type": "basic", "title": "Locate Factory" } [/block] In order to instantiate the Locate Manager you need to use the *LOCLocateFactory*. It creates and holds the Locate Manager instance, making sure there's only one per application. [block:code] { "codes": [ { "code": "NSError* error;\n\nLOCAuthorizationData* authData = [[LOCAuthorizationData alloc] initWithAppId:@\"YOUR_SDK_APP_ID\" andAppKey:@\"YOUR_SDK_APP_KEY\" validationError:&error];\n \nLOCLocateManageer* locateManager = [LOCLocateFactory getInstanceWithAuthorizationData:authData andLocationEnabled:YES withPushEnabled:YES withLaunchOptions:launchOptions error:&error];\n\n[locateManager startLocateSession];\n ", "language": "objectivec" } ] } [/block] [block:code] { "codes": [ { "code": "var error: NSError\nvar authData: LOCAuthorizationData = LOCAuthorizationData(appId: \"YOUR_SDK_APP_ID\", andAppKey: \"YOUR_SDK_APP_KEY\", validationError: error)\n \nlet locateManager = LOCLocateFactory.getInstanceWithAuthorizationData(authData, withLocationEnabled: true, withPushEnabled: true, withLaunchOptions: launchOptions, error: error)\n \nlocateManager.startLocateSession()", "language": "swift" } ] } [/block] **Delaying startLocate Session** You can delay the *startLocateSession* method call. For example, you can call it after the user successfully logins into your app so that only users that successfully log into your app are added to Locate and receive content from Locate. Here is an example of how to delay *startLocateSession* until after the user has logged in: [block:code] { "codes": [ { "code": "-(void)userLoggedInSuccessfully\n{\n LOCLocateManager* locateManager = [LOCLocateFactory getDefaultInstance];\n [locateManager startLocateSession];\n}", "language": "objectivec" } ] } [/block] [block:code] { "codes": [ { "code": "func userLoggedInSuccessfully() {\n let locateManager: LOCLocateManager = LOCLocateFactory.getDefaultInstance()\n locateManager.startLocateSession()\n}", "language": "swift" } ] } [/block] The *startLocateSession* method starts the session lifecycle and remote notifications, location if passed in parameters as *YES*. If you delay the Locate Session make sure that *"startLocateSession"* is still called in your *application:didFinishLaunchingWithOptions* method after the first session delay. In the example below we delay the first session until the user logs in, after the first log the "*startLocateSession*" will be called every time the *application:didFinishLaunchingWithOptions* method gets called by the system. [block:code] { "codes": [ { "code": "#import <LOCLocate/LOCLocate.h>\n\n@implementation AppDelegate\n\n- (BOOL)application:(UIApplication *)application\n didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\n NSError* error;\n\n\t\tLOCAuthorizationData* authData = [[LOCAuthorizationData alloc] initWithAppId:@\"YOUR_SDK_APP_ID\" andAppKey:@\"YOUR_SDK_APP_KEY\" validationError:&error];\n \n LOCLocateManager* locationManager = [LOCLocateFactory getInstanceWithAuthorizationData:authData withLocationEnabled:YES withPushEnabled:YES withLaunchOptions:launchOptions error:&error];\n\n if (userLoggedIn == YES)\n\t\t\t[locateManager startLocateSession];\n \n return YES;\n}\n\n\n@end", "language": "objectivec" } ] } [/block] [block:code] { "codes": [ { "code": "class AppDelegate {\n\n func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject : AnyObject]?) -> Bool {\n var error: NSError\n var authData: LOCAuthorizationData = LOCAuthorizationData(appId: \"YOUR_SDK_APP_ID\", andAppKey: \"YOUR_SDK_APP_KEY\", validationError: error)\n \n let locateManager = LOCLocateFactory.getInstanceWithAuthorizationData(authData, withLocationEnabled: true, withPushEnabled: true, withLaunchOptions: launchOptions, error: error)\n \n if (userLoggedIn)\n \tlocateManager.startLocateSession()\n \n return true\n }\n}", "language": "swift" } ] } [/block] The factory will instantiate only one object per application. If a Locate Manger object already exists it will return it, instead of creating a new one. In order to easily get the instantiated Locate Manager object you can use the *getDefaultInstance* method of the factory: [block:code] { "codes": [ { "code": "LOCLocateManager* locateManager = [LOCLocateFactory getDefaultInstance];", "language": "objectivec" } ] } [/block] [block:code] { "codes": [ { "code": "let locateManager = LOCLocateFactory.getDefaultInstance()", "language": "swift" } ] } [/block] [block:api-header] { "type": "basic", "title": "Authorization Prompts" } [/block] During the Locate Manager instantiation you can declare if you want remote notifications or location authorization prompts to be shown when the *startLocateSession* method is called. You can delay these prompts by passing *NO* and using *startLocation*, *startRemoteNotifications* at your convenience. [block:code] { "codes": [ { "code": "LOCLocateManager* locateManager = [LOCLocateFactory getInstanceWithAuthorizationData:authData andLocationEnabled:NO withRemoteNotificationsEnabled:NO withLaunchOptions:launchOptions error:&error];\n\n[locateManager startLocateSession];\n\n\t// The session lifecycle has started, but without remote notifications \tand location\n\n\t//... \n\n\t// At the time of your convenience you can start the modules you want and present the authorization prompts to the user.\n\n[locateManager startLocation];\n\n// You can also use the startRemoteNotificationsWithSettings: method if you want to pass custom UIUserNotificationSettings settings \n[locateManager startRemoteNotifications];", "language": "objectivec" } ] } [/block] [block:code] { "codes": [ { "code": "var locateManager: LOCLocateManager = LOCLocateFactory.getInstanceWithAuthorizationData(authData, andLocationEnabled: false, withRemoteNotificationsEnabled: false, withLaunchOptions: launchOptions, error: error)\n\nlocateManager.startLocateSession()\n\n// The session lifecycle has started, but without remote notifications \tand location\n//... \n// At the time of your convenience you can start the modules you want and present the authorization prompts to the user.\n\nlocateManager.startLocation()\n// You can also use the startRemoteNotificationsWithSettings: method if you want to pass custom UIUserNotificationSettings settings \nlocateManager.startRemoteNotifications()\n", "language": "swift" } ] } [/block]