{"__v":24,"_id":"55bb4450a8400c2d00873dd9","category":{"__v":7,"_id":"55bb441b54f9640d006e6cf2","pages":["55bb4450a8400c2d00873dd9","55bb46afa8400c2d00873de6","55bb46cca8400c2d00873dea","55bb4704a8400c2d00873ded","55bb47477313650d00c46e1e","568166af30018c0d006bf7fd","5685143fd96a760d00545d71"],"project":"559a61d2dbcfd20d00710b39","version":"559a61d2dbcfd20d00710b3c","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-31T09:47:07.862Z","from_sync":false,"order":6,"slug":"cordova-phonegap","title":"Cordova / PhoneGap SDK"},"parentDoc":null,"project":"559a61d2dbcfd20d00710b39","user":"559a618bdbcfd20d00710b38","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_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-07-31T09:48:00.282Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"This plugin supports **PhoneGap/Cordova** apps running on iOS and Android.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Version requirements\"\n}\n[/block]\nThis plugin is meant to work with Cordova 3.4.0+ and the latest versions of the MOCA SDK libraries.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Installation\"\n}\n[/block]\nAutomatic installation using PhoneGap/Cordova CLI (iOS and Android)\n\n1. For iOS, make sure you update your iOS project to Cordova iOS version 3.4.1 or newer before installing this plugin.\n\n  ````\n    cordova platform add ios\n  ````\n  \n2. For Android, make sure the Android SDK is up to date. Google Play Services 7.5+ is required (8.5+ for Remote Push Notifications through Google Cloud Messaging).\n\n  ````\n    cordova platform add android\n  ````\n   \n3. Install this plugin using PhoneGap/Cordova cli:\n\n   ````\n    cordova plugin add https://github.com/mocaplatform/moca-phonegap-sdk.git#:/MOCASDK\n   ````\n   \n4. Modify the config.xml directory to contain (replacing with your configuration settings):\n   \n   ````\n   <!-- MOCA SDK credentials -->\n   <preference name=\"moca_app_key\" value=\"YOUR_APP_KEY\" />\n   <preference name=\"moca_app_secret\" value=\"YOUR-APP-SECRET\" />\n   <preference name=\"gcm_sender\" value=\"\\ YOUR_GCM_SENDER\" />\n    <platform name=\"android\">\n    ...\n        <preference name=\"android-minSdkVersion\" value=\"14\" />\n        <preference name=\"android-targetSdkVersion\" value=\"23\" />\n    ...\n    </platform>\n   ````\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"NOTE\",\n  \"body\": \"There is a `space` after the backslash `\\\\` in the `\\\"gcm_sender\\\"` field. **Do not delete the space character**, otherwise key won't be read correctly.\\n\\nvalue=\\\"\\\\\\\\` `YOUR_GCM_SENDER\\\"\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Android - Caveats\"\n}\n[/block]\n##Permissions in Android 6+\n\nStarting with Android Marshmallow (6.0), some permissions must be requested at runtime, rather than at install time. For the MOCA SDK, this means that you need to ask to the user for the 'ACCESS_FINE_LOCATION' permission when the App is executed for the first time. Otherwise, neither beacons nor geofences will be detected.\n\nYou can use a 3rd party plugin to do this, such as [this one](https://www.npmjs.com/package/cordova-plugin-android-permissions).\n\nAfter the permission is granted, you can manually start the affected services by calling:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"MOCA.setGeoTrackingEnabled(true, callback);\\nMOCA.setProximityEnabled(true, callback);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nBelow you will find a working code sample of this integration, notice the `requestMocaPermissions` and `startProximityServices` methods. And how `requestMocaPermissions` is called in `onDeviceReady`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var app = {\\n    // Application Constructor\\n    initialize: function() {\\n        this.bindEvents();\\n    },\\n    // Bind Event Listeners\\n    //\\n    // Bind any events that are required on startup. Common events are:\\n    // 'load', 'deviceready', 'offline', and 'online'.\\n    bindEvents: function() {\\n        document.addEventListener('deviceready', this.onDeviceReady, false);\\n    },\\n    // deviceready Event Handler\\n    //\\n    // The scope of 'this' is the event. In order to call the 'receivedEvent'\\n    // function, we must explicitly call 'app.receivedEvent(...);'\\n    onDeviceReady: function() {\\n        app.receivedEvent('deviceready');\\n      \\n/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */\\n      \\n        /*Request permissions at RunTime*/\\n        app.requestMocaPermissions();\\n    },\\n    requestMocaPermissions: function(){\\n        var permissions = cordova.plugins.permissions;\\n        var onError = function(e) {\\n            console.error(error, e);\\n        };\\n        var onRequestPermissionResult = function(permStatus){\\n            permStatus.hasPermission? app.startProximityServices(): console.warn(\\\"Location Permission denied\\\");  \\n        };\\n        var onPermissionStatus = function(permStatus) {\\n            if(!permStatus.hasPermission){\\n                permissions.requestPermission(permissions.ACCESS_FINE_LOCATION, onRequestPermissionResult, onError);\\n            }\\n            else {\\n               app.startProximityServices();\\n            }\\n        };\\n        permissions.hasPermission(permissions.ACCESS_FINE_LOCATION, onPermissionStatus, onError);\\n    },\\n    startProximityServices: function() {\\n        MOCA.setProximityEnabled(true);\\n        MOCA.setGeoTrackingEnabled(true);\\n    },\\n  \\n/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */\\n\\n    // Update DOM on a Received Event\\n    receivedEvent: function(id) {\\n        var parentElement = document.getElementById(id);\\n        var listeningElement = parentElement.querySelector('.listening');\\n        var receivedElement = parentElement.querySelector('.received');\\n\\n        listeningElement.setAttribute('style', 'display:none;');\\n        receivedElement.setAttribute('style', 'display:block;');\\n\\n        console.log('Received Event: ' + id);\\n    }\\n};\",\n      \"language\": \"javascript\",\n      \"name\": \"Permissions Sample\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"iOS - Caveats\"\n}\n[/block]\n##App Transport Security\n\nIn order to receive experiences served through non-secured connections, [please configure *App Transport Security* ](http://developer.mocaplatform.com/docs/moca-ios-sdk-configuration#section-app-transport-security) properly within the Xcode project,\n\n##Customizing text when requesting Location Permission\n\nYou may want to modify the message shown to the user when prompting for location permission. In order to do so, open the `YourAppName-Info.plist` file and edit the `NSLocationAlwaysUsageDescription` key.","excerpt":"","slug":"installation","type":"basic","title":"Installation"}
This plugin supports **PhoneGap/Cordova** apps running on iOS and Android. [block:api-header] { "type": "basic", "title": "Version requirements" } [/block] This plugin is meant to work with Cordova 3.4.0+ and the latest versions of the MOCA SDK libraries. [block:api-header] { "type": "basic", "title": "Installation" } [/block] Automatic installation using PhoneGap/Cordova CLI (iOS and Android) 1. For iOS, make sure you update your iOS project to Cordova iOS version 3.4.1 or newer before installing this plugin. ```` cordova platform add ios ```` 2. For Android, make sure the Android SDK is up to date. Google Play Services 7.5+ is required (8.5+ for Remote Push Notifications through Google Cloud Messaging). ```` cordova platform add android ```` 3. Install this plugin using PhoneGap/Cordova cli: ```` cordova plugin add https://github.com/mocaplatform/moca-phonegap-sdk.git#:/MOCASDK ```` 4. Modify the config.xml directory to contain (replacing with your configuration settings): ```` <!-- MOCA SDK credentials --> <preference name="moca_app_key" value="YOUR_APP_KEY" /> <preference name="moca_app_secret" value="YOUR-APP-SECRET" /> <preference name="gcm_sender" value="\ YOUR_GCM_SENDER" /> <platform name="android"> ... <preference name="android-minSdkVersion" value="14" /> <preference name="android-targetSdkVersion" value="23" /> ... </platform> ```` [block:callout] { "type": "danger", "title": "NOTE", "body": "There is a `space` after the backslash `\\` in the `\"gcm_sender\"` field. **Do not delete the space character**, otherwise key won't be read correctly.\n\nvalue=\"\\\\` `YOUR_GCM_SENDER\"" } [/block] [block:api-header] { "type": "basic", "title": "Android - Caveats" } [/block] ##Permissions in Android 6+ Starting with Android Marshmallow (6.0), some permissions must be requested at runtime, rather than at install time. For the MOCA SDK, this means that you need to ask to the user for the 'ACCESS_FINE_LOCATION' permission when the App is executed for the first time. Otherwise, neither beacons nor geofences will be detected. You can use a 3rd party plugin to do this, such as [this one](https://www.npmjs.com/package/cordova-plugin-android-permissions). After the permission is granted, you can manually start the affected services by calling: [block:code] { "codes": [ { "code": "MOCA.setGeoTrackingEnabled(true, callback);\nMOCA.setProximityEnabled(true, callback);", "language": "javascript" } ] } [/block] Below you will find a working code sample of this integration, notice the `requestMocaPermissions` and `startProximityServices` methods. And how `requestMocaPermissions` is called in `onDeviceReady`. [block:code] { "codes": [ { "code": "var app = {\n // Application Constructor\n initialize: function() {\n this.bindEvents();\n },\n // Bind Event Listeners\n //\n // Bind any events that are required on startup. Common events are:\n // 'load', 'deviceready', 'offline', and 'online'.\n bindEvents: function() {\n document.addEventListener('deviceready', this.onDeviceReady, false);\n },\n // deviceready Event Handler\n //\n // The scope of 'this' is the event. In order to call the 'receivedEvent'\n // function, we must explicitly call 'app.receivedEvent(...);'\n onDeviceReady: function() {\n app.receivedEvent('deviceready');\n \n/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */\n \n /*Request permissions at RunTime*/\n app.requestMocaPermissions();\n },\n requestMocaPermissions: function(){\n var permissions = cordova.plugins.permissions;\n var onError = function(e) {\n console.error(error, e);\n };\n var onRequestPermissionResult = function(permStatus){\n permStatus.hasPermission? app.startProximityServices(): console.warn(\"Location Permission denied\"); \n };\n var onPermissionStatus = function(permStatus) {\n if(!permStatus.hasPermission){\n permissions.requestPermission(permissions.ACCESS_FINE_LOCATION, onRequestPermissionResult, onError);\n }\n else {\n app.startProximityServices();\n }\n };\n permissions.hasPermission(permissions.ACCESS_FINE_LOCATION, onPermissionStatus, onError);\n },\n startProximityServices: function() {\n MOCA.setProximityEnabled(true);\n MOCA.setGeoTrackingEnabled(true);\n },\n \n/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */\n\n // Update DOM on a Received Event\n receivedEvent: function(id) {\n var parentElement = document.getElementById(id);\n var listeningElement = parentElement.querySelector('.listening');\n var receivedElement = parentElement.querySelector('.received');\n\n listeningElement.setAttribute('style', 'display:none;');\n receivedElement.setAttribute('style', 'display:block;');\n\n console.log('Received Event: ' + id);\n }\n};", "language": "javascript", "name": "Permissions Sample" } ] } [/block] [block:api-header] { "type": "basic", "title": "iOS - Caveats" } [/block] ##App Transport Security In order to receive experiences served through non-secured connections, [please configure *App Transport Security* ](http://developer.mocaplatform.com/docs/moca-ios-sdk-configuration#section-app-transport-security) properly within the Xcode project, ##Customizing text when requesting Location Permission You may want to modify the message shown to the user when prompting for location permission. In order to do so, open the `YourAppName-Info.plist` file and edit the `NSLocationAlwaysUsageDescription` key.