{"_id":"59e70b9ee027ae002e7d2ee2","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","project":"5496d393f52a630b00519cdd","parentDoc":null,"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-21T14:35:30.200Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"##  Requirements\n  * Latest Android development environment.\n  * Android 4.0 - Ice Cream Sandwich (API level 14) or later.\n \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Installation\"\n}\n[/block]\nThis section describes how to integrate Placer with an existing Android project. Please create a new one if you don't have one yet.\n\n##Android Studio\nAdd the following lines to your build.gradle file:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"repositories {\\n    mavenCentral()\\n    maven { url 'https://maven.google.com/' }\\n    maven { url 'PLACER-SDK-MAVEN-URL' }\\n}\\n\\ndependencies {\\n    compile 'com.placer:placer:2.7.+:::at:::aar'\\n    compile 'com.google.android.gms:play-services-location:X' // Replace X with the latest Play services version\\n}\",\n      \"language\": \"java\",\n      \"name\": \"build.gradle\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Important Notes\",\n  \"body\": \"1. Placer SDK is not publicly available. Therefore, in your maven you must replace the **\\\"PLACER-SDK-MAVEN-URL\\\"** with the SDK path provided in your dashboard under the [\\\"download\\\"](https://dashboard.placer.io/#/download) section. \\n \\n2. Placer SDK is not dependant on the Google Play Services API, but adding it will improve Placer's accuracy and reduce battery drain in relevant devices. Therefore, it is highly recommended to add the latest Google Play Services to your app (version 8.4.0 or later). To add it, include the dependency in your app's gradle file (as shown above). If you receive an error saying \\\"Missing an expected resource: 'R.string.google_app_id'...\\\", please solve it by adding to **[project_dir]/res/values/strings.xml** the following: **<string name=\\\"google_app_id\\\">your_google_app_id</string>**\"\n}\n[/block]\n##Eclipse\n1- Download the Placer's Android SDK [here](http://placer-dashboard.herokuapp.com/#/download).\n\n2 - Place the **placer.jar** file in your projects /libs directory. Create the directory if needed.\n\n3 - After placing the jar file, right click it and select **\"add as library\"**.\n\n4 - Rebuild project to allow usage in code.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Activation\"\n}\n[/block]\n1 - Create a new file named **placer.properties** under the \\assets (Android Studio path: src/main/assets/) directory of your project. If the directory does not exist then create it (Right click on your app name -> new -> Folder -> Assets Folder). Edit the file so that it contains the following text:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"placer_application_key=YOUR_APP_KEY\",\n      \"language\": \"text\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\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/#/download), under the \\\"settings\\\" tab.\",\n  \"title\": \"App Key\"\n}\n[/block]\n2 - Add the following **permissions** to the AndroidManifest.xml:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<manifest>\\n...\\n<!-- Basic permissions -\\nRequired for running the Placer SDK -->\\n<uses-permission android:name=\\\"android.permission.INTERNET\\\" />\\n<uses-permission android:name=\\\"android.permission.ACCESS_NETWORK_STATE\\\" />\\n<uses-permission android:name=\\\"android.permission.RECEIVE_BOOT_COMPLETED\\\" />\\n\\n<!-- Location Permissions - \\nRequired for collecting location signals -->\\n<uses-permission android:name=\\\"android.permission.ACCESS_FINE_LOCATION\\\" />\\n<uses-permission android:name=\\\"android.permission.ACCESS_WIFI_STATE\\\" />\\n\\n<!-- Beacons Permissions - Required for improving accuracy -->\\n<uses-permission android:name=\\\"android.permission.BLUETOOTH_ADMIN\\\" />\\n<uses-permission android:name=\\\"android.permission.BLUETOOTH\\\" />\\n \\n...\\n</manifest>\",\n      \"language\": \"xml\",\n      \"name\": \"AndroidManifest.xml\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Not collecting location or app usage signals will have an affect on the quality of the user profiles generated by Placer. \\nIf you decide not to declare the location or app usage permissions described above, you will need to disable the relevant signal monitors at the properties file. Please see the “Disabling Signals” section in the [Android Customization Page](doc:customization-1#disabling-signals), for further instructions.\",\n  \"title\": \"Important Note\"\n}\n[/block]\n3 - Add the following application elements to the AndroidManifest.xml: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<application>\\n\\t...\\n\\t<service\\n        android:name=\\\"com.placer.client.PlacerScheduler\\\"\\n        android:exported=\\\"false\\\"\\n        android:permission=\\\"android.permission.BIND_JOB_SERVICE\\\"\\n        android:process=\\\":background\\\" />\\n  \\n    <receiver\\n        android:name=\\\"com.placer.client.PlacerReceiver\\\"\\n        android:enabled=\\\"true\\\"\\n        android:exported=\\\"false\\\"\\n        android:process=\\\":background\\\">\\n        <intent-filter>\\n            <action android:name=\\\"android.intent.action.BOOT_COMPLETED\\\" />\\n            <action android:name=\\\"android.intent.action.USER_PRESENT\\\" />\\n            <action android:name=\\\"com.placer.action.ENABLE_PLACER\\\" />\\n            <action android:name=\\\"com.placer.action.DISABLE_PLACER\\\" />\\n        </intent-filter>\\n    </receiver>\\n  \\n\\t  <provider\\n\\t\\t\\t\\tandroid:name=\\\"com.placer.library.tray.provider.TrayContentProvider\\\"\\n        android:authorities=\\\"${applicationId}.tray\\\"\\n        android:exported=\\\"false\\\"\\n        android:multiprocess=\\\"false\\\" />\\n\\t...\\n</application>\",\n      \"language\": \"xml\",\n      \"name\": \"AndroidManifest.xml\"\n    }\n  ]\n}\n[/block]\n4 - If your project doesn't have the Google Play Services SDK, please add it by following these instructions:\nhttps://developers.google.com/android/guides/setup\n\n\n5 - Activate the Placer service\nAdd a call to the Placer.activate() method in your applications first activity. This call receives the application context. Here is a simple example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\nimport com.placer.client.Placer;\\n\\npublic class SplashScreenActivity extends Activity {\\n\\t@Override\\n\\tprotected void onCreate(Bundle savedInstanceState) {\\n    \\tsuper.onCreate(savedInstanceState);\\n    \\tPlacer.activate(getApplicationContext());\\n    \\t// here comes the rest of your Activity code\\n\\t}\\n}\\n\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n6 - Set User ID\nDefines custom User ID to be used for querying insights from Placer's server API for a specific user.\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Placer.setUserId(\\\"YOUR_USER_ID\\\");\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n*Note: User ID cannot be longer than 100 characters.*\n\n7 - Add Android 6 support\nBeginning in Android 6.0 (API level 23), users grant location permissions while the app is running using a Dialog. Call **Placer.showRuntimePermissionsDialog() **with the relevant activity, to show the location permission dialog. If the SDK is running on an older Android version, this method will not do anything.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"public class MainActivity extends Activity {\\n    @Override\\n    protected void onCreate(Bundle savedInstanceState) {\\n        super.onCreate(savedInstanceState);\\n        setContentView(R.layout.activity_main);\\n\\n        Placer.activate(getApplicationContext());\\n        Placer.setUserId(\\\"YOUR_USER_ID\\\");\\n\\n        Placer.showRuntimePermissionsDialog(this);\\n    }\\n}\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n8 - Set user gender and date-of-birth to improve location tracking and venue detection (optional):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HashMap<String, String> placerParams = new HashMap<>();\\n\\nplacerParams.put(\\\"gender\\\", \\\"male\\\"); \\nplacerParams.put(\\\"year_of_birth\\\", \\\"1985\\\" );\\n\\nPlacer.sendUserInfo(placerParams);\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n## All Done! \nPlacer will collect device signals and generate accurate user insights. \nFor advanced usage options, see:\n  * [Android SDK Customization](doc:customization-1)\n  * [Geofencing](doc:geofencing-1) \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/).","excerpt":"","slug":"android","type":"basic","title":"Android - Quick Start"}

Android - Quick Start


## Requirements * Latest Android development environment. * Android 4.0 - Ice Cream Sandwich (API level 14) or later. [block:api-header] { "type": "basic", "title": "Installation" } [/block] This section describes how to integrate Placer with an existing Android project. Please create a new one if you don't have one yet. ##Android Studio Add the following lines to your build.gradle file: [block:code] { "codes": [ { "code": "repositories {\n mavenCentral()\n maven { url 'https://maven.google.com/' }\n maven { url 'PLACER-SDK-MAVEN-URL' }\n}\n\ndependencies {\n compile 'com.placer:placer:2.7.+@aar'\n compile 'com.google.android.gms:play-services-location:X' // Replace X with the latest Play services version\n}", "language": "java", "name": "build.gradle" } ] } [/block] [block:callout] { "type": "warning", "title": "Important Notes", "body": "1. Placer SDK is not publicly available. Therefore, in your maven you must replace the **\"PLACER-SDK-MAVEN-URL\"** with the SDK path provided in your dashboard under the [\"download\"](https://dashboard.placer.io/#/download) section. \n \n2. Placer SDK is not dependant on the Google Play Services API, but adding it will improve Placer's accuracy and reduce battery drain in relevant devices. Therefore, it is highly recommended to add the latest Google Play Services to your app (version 8.4.0 or later). To add it, include the dependency in your app's gradle file (as shown above). If you receive an error saying \"Missing an expected resource: 'R.string.google_app_id'...\", please solve it by adding to **[project_dir]/res/values/strings.xml** the following: **<string name=\"google_app_id\">your_google_app_id</string>**" } [/block] ##Eclipse 1- Download the Placer's Android SDK [here](http://placer-dashboard.herokuapp.com/#/download). 2 - Place the **placer.jar** file in your projects /libs directory. Create the directory if needed. 3 - After placing the jar file, right click it and select **"add as library"**. 4 - Rebuild project to allow usage in code. [block:api-header] { "type": "basic", "title": "Activation" } [/block] 1 - Create a new file named **placer.properties** under the \assets (Android Studio path: src/main/assets/) directory of your project. If the directory does not exist then create it (Right click on your app name -> new -> Folder -> Assets Folder). Edit the file so that it contains the following text: [block:code] { "codes": [ { "code": "placer_application_key=YOUR_APP_KEY", "language": "text", "name": null } ] } [/block] [block:callout] { "type": "success", "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/#/download), under the \"settings\" tab.", "title": "App Key" } [/block] 2 - Add the following **permissions** to the AndroidManifest.xml: [block:code] { "codes": [ { "code": "<manifest>\n...\n<!-- Basic permissions -\nRequired for running the Placer SDK -->\n<uses-permission android:name=\"android.permission.INTERNET\" />\n<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" />\n<uses-permission android:name=\"android.permission.RECEIVE_BOOT_COMPLETED\" />\n\n<!-- Location Permissions - \nRequired for collecting location signals -->\n<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" />\n<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\" />\n\n<!-- Beacons Permissions - Required for improving accuracy -->\n<uses-permission android:name=\"android.permission.BLUETOOTH_ADMIN\" />\n<uses-permission android:name=\"android.permission.BLUETOOTH\" />\n \n...\n</manifest>", "language": "xml", "name": "AndroidManifest.xml" } ] } [/block] [block:callout] { "type": "warning", "body": "Not collecting location or app usage signals will have an affect on the quality of the user profiles generated by Placer. \nIf you decide not to declare the location or app usage permissions described above, you will need to disable the relevant signal monitors at the properties file. Please see the “Disabling Signals” section in the [Android Customization Page](doc:customization-1#disabling-signals), for further instructions.", "title": "Important Note" } [/block] 3 - Add the following application elements to the AndroidManifest.xml: [block:code] { "codes": [ { "code": "<application>\n\t...\n\t<service\n android:name=\"com.placer.client.PlacerScheduler\"\n android:exported=\"false\"\n android:permission=\"android.permission.BIND_JOB_SERVICE\"\n android:process=\":background\" />\n \n <receiver\n android:name=\"com.placer.client.PlacerReceiver\"\n android:enabled=\"true\"\n android:exported=\"false\"\n android:process=\":background\">\n <intent-filter>\n <action android:name=\"android.intent.action.BOOT_COMPLETED\" />\n <action android:name=\"android.intent.action.USER_PRESENT\" />\n <action android:name=\"com.placer.action.ENABLE_PLACER\" />\n <action android:name=\"com.placer.action.DISABLE_PLACER\" />\n </intent-filter>\n </receiver>\n \n\t <provider\n\t\t\t\tandroid:name=\"com.placer.library.tray.provider.TrayContentProvider\"\n android:authorities=\"${applicationId}.tray\"\n android:exported=\"false\"\n android:multiprocess=\"false\" />\n\t...\n</application>", "language": "xml", "name": "AndroidManifest.xml" } ] } [/block] 4 - If your project doesn't have the Google Play Services SDK, please add it by following these instructions: https://developers.google.com/android/guides/setup 5 - Activate the Placer service Add a call to the Placer.activate() method in your applications first activity. This call receives the application context. Here is a simple example: [block:code] { "codes": [ { "code": "\nimport com.placer.client.Placer;\n\npublic class SplashScreenActivity extends Activity {\n\t@Override\n\tprotected void onCreate(Bundle savedInstanceState) {\n \tsuper.onCreate(savedInstanceState);\n \tPlacer.activate(getApplicationContext());\n \t// here comes the rest of your Activity code\n\t}\n}\n", "language": "java" } ] } [/block] 6 - Set User ID Defines custom User ID to be used for querying insights from Placer's server API for a specific user. Example: [block:code] { "codes": [ { "code": "Placer.setUserId(\"YOUR_USER_ID\");", "language": "java" } ] } [/block] *Note: User ID cannot be longer than 100 characters.* 7 - Add Android 6 support Beginning in Android 6.0 (API level 23), users grant location permissions while the app is running using a Dialog. Call **Placer.showRuntimePermissionsDialog() **with the relevant activity, to show the location permission dialog. If the SDK is running on an older Android version, this method will not do anything. [block:code] { "codes": [ { "code": "public class MainActivity extends Activity {\n @Override\n protected void onCreate(Bundle savedInstanceState) {\n super.onCreate(savedInstanceState);\n setContentView(R.layout.activity_main);\n\n Placer.activate(getApplicationContext());\n Placer.setUserId(\"YOUR_USER_ID\");\n\n Placer.showRuntimePermissionsDialog(this);\n }\n}", "language": "java" } ] } [/block] 8 - Set user gender and date-of-birth to improve location tracking and venue detection (optional): [block:code] { "codes": [ { "code": "HashMap<String, String> placerParams = new HashMap<>();\n\nplacerParams.put(\"gender\", \"male\"); \nplacerParams.put(\"year_of_birth\", \"1985\" );\n\nPlacer.sendUserInfo(placerParams);", "language": "java" } ] } [/block] ## All Done! Placer will collect device signals and generate accurate user insights. For advanced usage options, see: * [Android SDK Customization](doc:customization-1) * [Geofencing](doc:geofencing-1) [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/).