{"__v":38,"_id":"55a5b03880c8a30d00b32458","category":{"__v":11,"_id":"55a589ddaaf9cf1900114dd0","pages":["55a590d580c8a30d00b32404","55a5915680c8a30d00b3240a","55a5917a0f354f0d00fd0345","55a5921d80c8a30d00b32413","55a5a5cb80c8a30d00b32448","55a5b03880c8a30d00b32458","55a611a0249a40190051d928","55a611ec80c8a30d00b32502","55a612ae249a40190051d92d","55a612faaaf9cf1900114f1f","55a911aa27a17d210052523f"],"project":"559a61d2dbcfd20d00710b39","version":"559a61d2dbcfd20d00710b3c","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-14T22:14:53.033Z","from_sync":false,"order":1,"slug":"ios-sdk","title":"iOS SDK"},"parentDoc":null,"project":"559a61d2dbcfd20d00710b39","user":"55a575ebaaf9cf1900114d73","version":{"__v":23,"_id":"559a61d2dbcfd20d00710b3c","project":"559a61d2dbcfd20d00710b39","createdAt":"2015-07-06T11:09:06.510Z","releaseDate":"2015-07-06T11:09:06.510Z","categories":["559a61d3dbcfd20d00710b3d","55a589ddaaf9cf1900114dd0","55a589e30f354f0d00fd0312","55a589ea80c8a30d00b323cc","55a589f6aaf9cf1900114dd1","55a58d4e80c8a30d00b323e6","55a8e7a227a17d21005251a2","55a93098cf45e1390093f351","55afb085f202b12100cd9e83","55afb22e902fd51700f5f8bf","55afb260902fd51700f5f8c2","55afb28ec8a85321007a5462","55afb294f202b12100cd9e95","55afb29b902fd51700f5f8c5","55afb2a1c8a85321007a5463","55afb2a7902fd51700f5f8c7","55afb2ad902fd51700f5f8c8","55afb2b5902fd51700f5f8ca","55b74b2131bccb190081bedc","55bb441b54f9640d006e6cf2","565711085cb2420d00d70071","5681681330018c0d006bf7ff","588f38b5923d610f00c72dad"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"Version 1.0","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-07-15T00:58:32.707Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"To start using MOCA SDK in your app, you’ll need to configure it first.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Location Services\"\n}\n[/block]\nTo detect beacons, geofences and track significant changes in user location, the SDK uses *iOS Location Services*. For iOS 8, enable the app to always use location services by adding *NSLocationAlwaysUsageDescription* key to your `Info.plist file`. For example:\u000b \n\n| Key                              | Type   |                                                                                                                                 |\n|----------------------------------|--------|---------------------------------------------------------------------------------------------------------------------------------|\n| NSLocationAlwaysUsageDescription | String | This app will use your location information to identify ,nearby places and to notify you about available proximity experiences. |\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"If this key is not present in your `info.plist`, iOS Location Services **won't start**, preventing the App to detect Bluetooth Beacons, Geofences and to receive Location updates.\",\n  \"title\": \"Important\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This message will be prompted to the user when asked for location services permission. Please bear in mind that if this key is not present in your info.plist, location services** won’t work at all.**\",\n  \"sidebar\": true\n}\n[/block]\n###App Transport Security\n\niOS 9 blocks all non-HTTPS requests, as you probably may want to show content hosted in non-HTTPS servers, please add the following keys to your `info.plist`:\nBear in mind you can use the key description (see image) instead of the key (NS...).\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/W02ZcgadS36yvqYZi01v_ios%209%20app%20transport.png\",\n        \"ios 9 app transport.png\",\n        \"438\",\n        \"75\",\n        \"#114b9a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nUsing key's descriptions.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2Ch7Pe6vRneAKw4igre9_infoplist2.png\",\n        \"infoplist2.png\",\n        \"500\",\n        \"49\",\n        \"#764f40\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n###Bluetooth Usage Description\n\nStarting with **iOS 10**, Apple requires this mode to be added to all applications that use the `CoreBluetooth` framework.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/02648cb-BTUsage.png\",\n        \"BTUsage.png\",\n        706,\n        21,\n        \"#5e3d2b\"\n      ]\n    }\n  ]\n}\n[/block]\nEquivalent version using raw key / values:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/d05e962-BTUsageKeyValue.png\",\n        \"BTUsageKeyValue.png\",\n        700,\n        22,\n        \"#5b3728\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"App Capabilities\"\n}\n[/block]\nMOCA SDK requires the app to enable selected *Capabilities*. Open XCode with your app project, go to Target, and select *Capabilities* configuration page. \n\nFirst, within *Background Modes* section, ensure the following entitlements are enabled:\n   - Background Fetch\n   - Optionally, you may want to enable Remote notifications in your app.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/mU6VBI2JSBW2sgCVaBak_background-capabilities.png\",\n        \"background-capabilities.png\",\n        \"817\",\n        \"282\",\n        \"\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"**Do not** select *Location updates* (unless you need it for another App feature). MOCA SDK **does not require this mode**. If you enable it and do not use it for any purpose, **your App will be rejected** by Apple.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"App Keys\"\n}\n[/block]\nTo link you app to your MOCA account, you must register the app in the MOCA Console and add corresponding **AppKey** and **AppSecret**. \n\n* Goto [https://console.mocaplatform.com](https://console.mocaplatform.com) and sign in to your MOCA account.\n* If you don't have your account, you are invited to [Sign Up Free] (http://mocaplatform.com/signup). \n* Select Apps item at left sidebar, and then click <i>+ New App</i> in the content panel. Fill in the form and complete the app creation.\n* Select if your app is *In Development* or *In Production* mode.\n* Open newly created app and navigate to <i>Settings</i> item. Select <i>API keys</i> tab.\n* Get `App Key` and `App Secret`.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/FFeK1tqTwCqIjweq7aP9_moca-keys.png\",\n        \"moca-keys.png\",\n        \"704\",\n        \"458\",\n        \"#573033\",\n        \"\"\n      ],\n      \"caption\": \"App keys in MOCA Console\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"SDK Configuration File\"\n}\n[/block]\nNow, you’ll need to prepare SDK configuration file:\n\n* Go back to your Xcode project.\n* `CocoaPods` only: You will find the MOCAConfig.plist in the following path: `Pods/MOCA/Resources` there is no need to add it manually\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6Q8t5NjZSICU3QYn0TeF_MOCAConfig-cocoapods.png\",\n        \"MOCAConfig-cocoapods.png\",\n        \"261\",\n        \"168\",\n        \"#97571e\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n* Add <i>New file / Property List</i> resource to your project. Save it as *MOCAConfig.plist* file. (optional,  [download sample MOCAConfig.plist file](https://s3-eu-west-1.amazonaws.com/files.mocaplatform.com/releases/MOCAConfig.plist))\n* Add configuration settings as shown below.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Default Value\",\n    \"h-3\": \"Description\",\n    \"h-4\": \"\",\n    \"0-0\": \"APP_KEY\",\n    \"0-1\": \"String\",\n    \"0-3\": \"App key from MOCA Console\",\n    \"1-0\": \"APP_SECRET\",\n    \"1-1\": \"String\",\n    \"1-3\": \"App secret from MOCA Console\",\n    \"2-0\": \"LOG_LEVEL\",\n    \"2-1\": \"String\",\n    \"2-3\": \"MOCA SDK logging level:\\n* trace\\n* debug\\n* info\\n* warn\\n* error\",\n    \"2-2\": \"\\\"info\\\"\",\n    \"3-0\": \"CACHE_DISK_SIZE_IN_MB\",\n    \"3-1\": \"Integer\",\n    \"3-3\": \"Maximum local disk space available for SDK cache.\",\n    \"3-2\": \"100\",\n    \"4-0\": \"AUTOMATIC_PUSH_SETUP_ENABLED\",\n    \"4-3\": \"If enabled, the SDK will automatically subscribe the app to APNS (Apple push notification service) and obtain push token.\",\n    \"4-1\": \"BOOL\",\n    \"4-2\": \"YES\",\n    \"5-0\": \"PROXIMITY_SERVICE_ENABLED\",\n    \"5-1\": \"BOOL\",\n    \"5-2\": \"YES\",\n    \"5-3\": \"Enables or disables Bluetooth Beacon monitoring and ranging & geofence detection using *iOS Location Services*\",\n    \"6-0\": \"GEOLOCATION_SERVICE_ENABLED\",\n    \"6-1\": \"BOOL\",\n    \"6-2\": \"YES\",\n    \"6-3\": \"Enables/disables tracking of significant changes in user location by GPS/Cellular Trilateration/Wifi.\\n\\nWhen enabled (YES), user location will be tracked when the app is in foreground. Additionally, background tracking is controlled by BACKGROUND_LOCATION_ENABLED flag. This is the default.\\n\\nWhen disabled (NO), user location will not be tracked at all (neither in foreground nor on background). However, Bluetooth beacons and geofences will still be detected if this flag is set to NO.\",\n    \"7-0\": \"BACKGROUND_LOCATION_ENABLED\",\n    \"7-1\": \"BOOL\",\n    \"7-2\": \"YES\",\n    \"7-3\": \"Enables/disables location tracking when the app is in background or suspended mode.\\n\\nThis flag has no effect if GEOLOCATION_SERVICE_ENABLED is set to NO.\\n\\nBy default background location tracking is enabled.\"\n  },\n  \"cols\": 4,\n  \"rows\": 8\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"MOCA performs location tracking using low battery usage modes to save battery life. For example, when the app is in background GPS-quality tracking is never used.\",\n  \"sidebar\": true\n}\n[/block]\n* Be sure to replace `APP_KEY` and `APP_SECRET` values with the real values for your app which you found in the MOCA console.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ncAD6MeQJy2CCfiVWjtm_moca-config-ios.png\",\n        \"moca-config-ios.png\",\n        \"949\",\n        \"369\",\n        \"#884c39\",\n        \"\"\n      ],\n      \"caption\": \"Sample MOCAConfig.plist file.\"\n    }\n  ]\n}\n[/block]","excerpt":"This section describes how to configure MOCA iOS SDK in your app.","slug":"moca-ios-sdk-configuration","type":"basic","title":"Configuration"}

Configuration

This section describes how to configure MOCA iOS SDK in your app.

To start using MOCA SDK in your app, you’ll need to configure it first. [block:api-header] { "type": "basic", "title": "Location Services" } [/block] To detect beacons, geofences and track significant changes in user location, the SDK uses *iOS Location Services*. For iOS 8, enable the app to always use location services by adding *NSLocationAlwaysUsageDescription* key to your `Info.plist file`. For example: | Key | Type | | |----------------------------------|--------|---------------------------------------------------------------------------------------------------------------------------------| | NSLocationAlwaysUsageDescription | String | This app will use your location information to identify ,nearby places and to notify you about available proximity experiences. | [block:callout] { "type": "danger", "body": "If this key is not present in your `info.plist`, iOS Location Services **won't start**, preventing the App to detect Bluetooth Beacons, Geofences and to receive Location updates.", "title": "Important" } [/block] [block:callout] { "type": "warning", "body": "This message will be prompted to the user when asked for location services permission. Please bear in mind that if this key is not present in your info.plist, location services** won’t work at all.**", "sidebar": true } [/block] ###App Transport Security iOS 9 blocks all non-HTTPS requests, as you probably may want to show content hosted in non-HTTPS servers, please add the following keys to your `info.plist`: Bear in mind you can use the key description (see image) instead of the key (NS...). [block:image] { "images": [ { "image": [ "https://files.readme.io/W02ZcgadS36yvqYZi01v_ios%209%20app%20transport.png", "ios 9 app transport.png", "438", "75", "#114b9a", "" ] } ] } [/block] Using key's descriptions. [block:image] { "images": [ { "image": [ "https://files.readme.io/2Ch7Pe6vRneAKw4igre9_infoplist2.png", "infoplist2.png", "500", "49", "#764f40", "" ] } ] } [/block] ###Bluetooth Usage Description Starting with **iOS 10**, Apple requires this mode to be added to all applications that use the `CoreBluetooth` framework. [block:image] { "images": [ { "image": [ "https://files.readme.io/02648cb-BTUsage.png", "BTUsage.png", 706, 21, "#5e3d2b" ] } ] } [/block] Equivalent version using raw key / values: [block:image] { "images": [ { "image": [ "https://files.readme.io/d05e962-BTUsageKeyValue.png", "BTUsageKeyValue.png", 700, 22, "#5b3728" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "App Capabilities" } [/block] MOCA SDK requires the app to enable selected *Capabilities*. Open XCode with your app project, go to Target, and select *Capabilities* configuration page. First, within *Background Modes* section, ensure the following entitlements are enabled: - Background Fetch - Optionally, you may want to enable Remote notifications in your app. [block:image] { "images": [ { "image": [ "https://files.readme.io/mU6VBI2JSBW2sgCVaBak_background-capabilities.png", "background-capabilities.png", "817", "282", "", "" ] } ] } [/block] [block:callout] { "type": "danger", "body": "**Do not** select *Location updates* (unless you need it for another App feature). MOCA SDK **does not require this mode**. If you enable it and do not use it for any purpose, **your App will be rejected** by Apple." } [/block] [block:api-header] { "type": "basic", "title": "App Keys" } [/block] To link you app to your MOCA account, you must register the app in the MOCA Console and add corresponding **AppKey** and **AppSecret**. * Goto [https://console.mocaplatform.com](https://console.mocaplatform.com) and sign in to your MOCA account. * If you don't have your account, you are invited to [Sign Up Free] (http://mocaplatform.com/signup). * Select Apps item at left sidebar, and then click <i>+ New App</i> in the content panel. Fill in the form and complete the app creation. * Select if your app is *In Development* or *In Production* mode. * Open newly created app and navigate to <i>Settings</i> item. Select <i>API keys</i> tab. * Get `App Key` and `App Secret`. [block:image] { "images": [ { "image": [ "https://files.readme.io/FFeK1tqTwCqIjweq7aP9_moca-keys.png", "moca-keys.png", "704", "458", "#573033", "" ], "caption": "App keys in MOCA Console" } ] } [/block] [block:api-header] { "type": "basic", "title": "SDK Configuration File" } [/block] Now, you’ll need to prepare SDK configuration file: * Go back to your Xcode project. * `CocoaPods` only: You will find the MOCAConfig.plist in the following path: `Pods/MOCA/Resources` there is no need to add it manually [block:image] { "images": [ { "image": [ "https://files.readme.io/6Q8t5NjZSICU3QYn0TeF_MOCAConfig-cocoapods.png", "MOCAConfig-cocoapods.png", "261", "168", "#97571e", "" ] } ] } [/block] * Add <i>New file / Property List</i> resource to your project. Save it as *MOCAConfig.plist* file. (optional, [download sample MOCAConfig.plist file](https://s3-eu-west-1.amazonaws.com/files.mocaplatform.com/releases/MOCAConfig.plist)) * Add configuration settings as shown below. [block:parameters] { "data": { "h-0": "Key", "h-1": "Type", "h-2": "Default Value", "h-3": "Description", "h-4": "", "0-0": "APP_KEY", "0-1": "String", "0-3": "App key from MOCA Console", "1-0": "APP_SECRET", "1-1": "String", "1-3": "App secret from MOCA Console", "2-0": "LOG_LEVEL", "2-1": "String", "2-3": "MOCA SDK logging level:\n* trace\n* debug\n* info\n* warn\n* error", "2-2": "\"info\"", "3-0": "CACHE_DISK_SIZE_IN_MB", "3-1": "Integer", "3-3": "Maximum local disk space available for SDK cache.", "3-2": "100", "4-0": "AUTOMATIC_PUSH_SETUP_ENABLED", "4-3": "If enabled, the SDK will automatically subscribe the app to APNS (Apple push notification service) and obtain push token.", "4-1": "BOOL", "4-2": "YES", "5-0": "PROXIMITY_SERVICE_ENABLED", "5-1": "BOOL", "5-2": "YES", "5-3": "Enables or disables Bluetooth Beacon monitoring and ranging & geofence detection using *iOS Location Services*", "6-0": "GEOLOCATION_SERVICE_ENABLED", "6-1": "BOOL", "6-2": "YES", "6-3": "Enables/disables tracking of significant changes in user location by GPS/Cellular Trilateration/Wifi.\n\nWhen enabled (YES), user location will be tracked when the app is in foreground. Additionally, background tracking is controlled by BACKGROUND_LOCATION_ENABLED flag. This is the default.\n\nWhen disabled (NO), user location will not be tracked at all (neither in foreground nor on background). However, Bluetooth beacons and geofences will still be detected if this flag is set to NO.", "7-0": "BACKGROUND_LOCATION_ENABLED", "7-1": "BOOL", "7-2": "YES", "7-3": "Enables/disables location tracking when the app is in background or suspended mode.\n\nThis flag has no effect if GEOLOCATION_SERVICE_ENABLED is set to NO.\n\nBy default background location tracking is enabled." }, "cols": 4, "rows": 8 } [/block] [block:callout] { "type": "info", "body": "MOCA performs location tracking using low battery usage modes to save battery life. For example, when the app is in background GPS-quality tracking is never used.", "sidebar": true } [/block] * Be sure to replace `APP_KEY` and `APP_SECRET` values with the real values for your app which you found in the MOCA console. [block:image] { "images": [ { "image": [ "https://files.readme.io/ncAD6MeQJy2CCfiVWjtm_moca-config-ios.png", "moca-config-ios.png", "949", "369", "#884c39", "" ], "caption": "Sample MOCAConfig.plist file." } ] } [/block]