├── lib ├── radius.jar └── NOTICE ├── .gitignore ├── dist ├── com.liferay.beacons-android-2.0.0.zip └── com.liferay.beacons-android-4.0.1.zip ├── NOTICE ├── .project ├── hooks ├── README ├── uninstall.py ├── install.py ├── add.py └── remove.py ├── assets └── README ├── example └── app.js ├── manifest ├── platform └── README ├── timodule.xml ├── README.md ├── LICENSE ├── src └── com │ └── liferay │ └── beacons │ └── LiferayBeaconsModule.java └── documentation └── index.md /lib/radius.jar: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jamesfalkner/liferay-android-beacons/HEAD/lib/radius.jar -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | tmp 2 | bin 3 | build 4 | *.zip 5 | !dist/*.zip 6 | .apt_generated 7 | *.iml 8 | .idea/ 9 | dist/liferay.beacons.jar 10 | libs/ -------------------------------------------------------------------------------- /dist/com.liferay.beacons-android-2.0.0.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jamesfalkner/liferay-android-beacons/HEAD/dist/com.liferay.beacons-android-2.0.0.zip -------------------------------------------------------------------------------- /dist/com.liferay.beacons-android-4.0.1.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jamesfalkner/liferay-android-beacons/HEAD/dist/com.liferay.beacons-android-4.0.1.zip -------------------------------------------------------------------------------- /NOTICE: -------------------------------------------------------------------------------- 1 | Titanium Appcelerator module for Android iBeacons 2 | Copyright 2014 Liferay, Inc. All Rights Reserved. 3 | 4 | Android IBeacon Service 5 | Copyright 2013 Radius Networks 6 | 7 | This product includes software developed at 8 | The Radius Networks (http://www.radiusnetworks.com/). 9 | -------------------------------------------------------------------------------- /lib/NOTICE: -------------------------------------------------------------------------------- 1 | Titanium Appcelerator module for Android iBeacons 2 | Copyright 2014 Liferay, Inc. All Rights Reserved. 3 | 4 | Android IBeacon Service 5 | Copyright 2013 Radius Networks 6 | 7 | This product includes software developed at 8 | The Radius Networks (http://www.radiusnetworks.com/). 9 | -------------------------------------------------------------------------------- /.project: -------------------------------------------------------------------------------- 1 | 2 | 3 | liferay-android-beacons 4 | 5 | 6 | 7 | 8 | 9 | 10 | com.appcelerator.titanium.mobile.module.nature 11 | com.aptana.projects.webnature 12 | 13 | 14 | -------------------------------------------------------------------------------- /hooks/README: -------------------------------------------------------------------------------- 1 | Copyright 2014 Liferay, Inc. All rights reserved. 2 | http://www.liferay.com 3 | 4 | Licensed under the Apache License, Version 2.0 (the "License"); 5 | you may not use this file except in compliance with the License. 6 | You may obtain a copy of the License at 7 | 8 | http://www.apache.org/licenses/LICENSE-2.0 9 | 10 | Unless required by applicable law or agreed to in writing, software 11 | distributed under the License is distributed on an "AS IS" BASIS, 12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | See the License for the specific language governing permissions and 14 | limitations under the License. 15 | 16 | 17 | These files are not yet supported as of 1.4.0 but will be in a near future release. 18 | -------------------------------------------------------------------------------- /assets/README: -------------------------------------------------------------------------------- 1 | Copyright 2014 Liferay, Inc. All rights reserved. 2 | http://www.liferay.com 3 | 4 | Licensed under the Apache License, Version 2.0 (the "License"); 5 | you may not use this file except in compliance with the License. 6 | You may obtain a copy of the License at 7 | 8 | http://www.apache.org/licenses/LICENSE-2.0 9 | 10 | Unless required by applicable law or agreed to in writing, software 11 | distributed under the License is distributed on an "AS IS" BASIS, 12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | See the License for the specific language governing permissions and 14 | limitations under the License. 15 | 16 | Place your assets like PNG files in this directory and they will be packaged with your module. 17 | 18 | If you create a file named com.liferay.beacons.js in this directory, it will be 19 | compiled and used as your module. This allows you to run pure Javascript 20 | modules that are pre-compiled. 21 | 22 | -------------------------------------------------------------------------------- /hooks/uninstall.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | # Copyright 2014 Liferay, Inc. All rights reserved. 4 | # http://www.liferay.com 5 | # 6 | # Licensed under the Apache License, Version 2.0 (the "License"); 7 | # you may not use this file except in compliance with the License. 8 | # You may obtain a copy of the License at 9 | # 10 | # http://www.apache.org/licenses/LICENSE-2.0 11 | # 12 | # Unless required by applicable law or agreed to in writing, software 13 | # distributed under the License is distributed on an "AS IS" BASIS, 14 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 | # See the License for the specific language governing permissions and 16 | # limitations under the License. 17 | # 18 | # 19 | # This is the module uninstall hook that will be 20 | # called when your module is uninstalled 21 | # 22 | import os, sys 23 | 24 | def main(args,argc): 25 | 26 | # TODO: write your uninstall hook here (optional) 27 | 28 | # exit 29 | sys.exit(0) 30 | 31 | 32 | if __name__ == '__main__': 33 | main(sys.argv,len(sys.argv)) 34 | 35 | -------------------------------------------------------------------------------- /hooks/install.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | # Copyright 2014 Liferay, Inc. All rights reserved. 4 | # http://www.liferay.com 5 | # 6 | # Licensed under the Apache License, Version 2.0 (the "License"); 7 | # you may not use this file except in compliance with the License. 8 | # You may obtain a copy of the License at 9 | # 10 | # http://www.apache.org/licenses/LICENSE-2.0 11 | # 12 | # Unless required by applicable law or agreed to in writing, software 13 | # distributed under the License is distributed on an "AS IS" BASIS, 14 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 | # See the License for the specific language governing permissions and 16 | # limitations under the License. 17 | # 18 | # 19 | # This is the module install hook that will be 20 | # called when your module is first installed 21 | # 22 | import os, sys 23 | 24 | def main(args,argc): 25 | 26 | # TODO: write your install hook here (optional) 27 | 28 | # exit 29 | sys.exit(0) 30 | 31 | 32 | 33 | if __name__ == '__main__': 34 | main(sys.argv,len(sys.argv)) 35 | 36 | -------------------------------------------------------------------------------- /example/app.js: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright 2014 Liferay, Inc. All rights reserved. 3 | // http://www.liferay.com 4 | // 5 | // Licensed under the Apache License, Version 2.0 (the "License"); 6 | // you may not use this file except in compliance with the License. 7 | // You may obtain a copy of the License at 8 | // 9 | // http://www.apache.org/licenses/LICENSE-2.0 10 | // 11 | // Unless required by applicable law or agreed to in writing, software 12 | // distributed under the License is distributed on an "AS IS" BASIS, 13 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | // See the License for the specific language governing permissions and 15 | // limitations under the License. 16 | // 17 | 18 | var win = Ti.UI.createWindow({ 19 | backgroundColor:'white' 20 | }); 21 | var label = Ti.UI.createLabel(); 22 | win.add(label); 23 | win.open(); 24 | 25 | if (Ti.Platform.name == "android") { 26 | var mod = require('com.liferay.beacons'); 27 | label.text = "module is => " + mod + "and checkAvailability says: " + mod.checkAvailability(); 28 | } else { 29 | label.text = "liferay.beacons not supported on " + Ti.Platform.name; 30 | } -------------------------------------------------------------------------------- /manifest: -------------------------------------------------------------------------------- 1 | # 2 | # Copyright 2014 Liferay, Inc. All rights reserved. 3 | # http://www.liferay.com 4 | # 5 | # Licensed under the Apache License, Version 2.0 (the "License"); 6 | # you may not use this file except in compliance with the License. 7 | # You may obtain a copy of the License at 8 | # 9 | # http://www.apache.org/licenses/LICENSE-2.0 10 | # 11 | # Unless required by applicable law or agreed to in writing, software 12 | # distributed under the License is distributed on an "AS IS" BASIS, 13 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | # See the License for the specific language governing permissions and 15 | # limitations under the License. 16 | # 17 | 18 | version: 4.0.1 19 | apiversion: 4 20 | architectures: arm64-v8a armeabi-v7a x86 x86_64 21 | description: Enables Titanium apps supporting android to interact with iBeacons 22 | author: James Falkner 23 | license: Apache Software License 2.0 24 | copyright: Copyright 2014 Liferay, Inc. All Rights Reserved. 25 | 26 | # these should not be edited 27 | name: liferay.beacons 28 | moduleid: com.liferay.beacons 29 | guid: 57bcb713-b5cd-4bb1-95d5-9141b6074802 30 | platform: android 31 | minsdk: 9.0.0 32 | -------------------------------------------------------------------------------- /platform/README: -------------------------------------------------------------------------------- 1 | # 2 | # Copyright 2014 Liferay, Inc. All rights reserved. 3 | # http://www.liferay.com 4 | # 5 | # Licensed under the Apache License, Version 2.0 (the "License"); 6 | # you may not use this file except in compliance with the License. 7 | # You may obtain a copy of the License at 8 | # 9 | # http://www.apache.org/licenses/LICENSE-2.0 10 | # 11 | # Unless required by applicable law or agreed to in writing, software 12 | # distributed under the License is distributed on an "AS IS" BASIS, 13 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | # See the License for the specific language governing permissions and 15 | # limitations under the License. 16 | # 17 | 18 | You can place platform-specific files here in sub-folders named "android" and/or "iphone", 19 | just as you can with normal Titanium Mobile SDK projects. Any folders and files you place 20 | here will be merged with the platform-specific files in a Titanium Mobile project that uses this module. 21 | 22 | When a Titanium Mobile project that uses this module is built, the files from this platform/ 23 | folder will be treated the same as files (if any) from the Titanium Mobile project's platform/ folder. 24 | -------------------------------------------------------------------------------- /timodule.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 20 | 21 | 22 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | -------------------------------------------------------------------------------- /hooks/add.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | # Copyright 2014 Liferay, Inc. All rights reserved. 4 | # http://www.liferay.com 5 | # 6 | # Licensed under the Apache License, Version 2.0 (the "License"); 7 | # you may not use this file except in compliance with the License. 8 | # You may obtain a copy of the License at 9 | # 10 | # http://www.apache.org/licenses/LICENSE-2.0 11 | # 12 | # Unless required by applicable law or agreed to in writing, software 13 | # distributed under the License is distributed on an "AS IS" BASIS, 14 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 | # See the License for the specific language governing permissions and 16 | # limitations under the License. 17 | # 18 | # 19 | # This is the module project add hook that will be 20 | # called when your module is added to a project 21 | # 22 | import os, sys 23 | 24 | def dequote(s): 25 | if s[0:1] == '"': 26 | return s[1:-1] 27 | return s 28 | 29 | def main(args,argc): 30 | # You will get the following command line arguments 31 | # in the following order: 32 | # 33 | # project_dir = the full path to the project root directory 34 | # project_type = the type of project (desktop, mobile, ipad) 35 | # project_name = the name of the project 36 | # 37 | project_dir = dequote(os.path.expanduser(args[1])) 38 | project_type = dequote(args[2]) 39 | project_name = dequote(args[3]) 40 | 41 | # TODO: write your add hook here (optional) 42 | 43 | 44 | # exit 45 | sys.exit(0) 46 | 47 | 48 | 49 | if __name__ == '__main__': 50 | main(sys.argv,len(sys.argv)) 51 | 52 | -------------------------------------------------------------------------------- /hooks/remove.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | # Copyright 2014 Liferay, Inc. All rights reserved. 4 | # http://www.liferay.com 5 | # 6 | # Licensed under the Apache License, Version 2.0 (the "License"); 7 | # you may not use this file except in compliance with the License. 8 | # You may obtain a copy of the License at 9 | # 10 | # http://www.apache.org/licenses/LICENSE-2.0 11 | # 12 | # Unless required by applicable law or agreed to in writing, software 13 | # distributed under the License is distributed on an "AS IS" BASIS, 14 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 | # See the License for the specific language governing permissions and 16 | # limitations under the License. 17 | # 18 | # 19 | # This is the module project remove hook that will be 20 | # called when your module is remove from a project 21 | # 22 | import os, sys 23 | 24 | def dequote(s): 25 | if s[0:1] == '"': 26 | return s[1:-1] 27 | return s 28 | 29 | def main(args,argc): 30 | # You will get the following command line arguments 31 | # in the following order: 32 | # 33 | # project_dir = the full path to the project root directory 34 | # project_type = the type of project (desktop, mobile, ipad) 35 | # project_name = the name of the project 36 | # 37 | project_dir = dequote(os.path.expanduser(args[1])) 38 | project_type = dequote(args[2]) 39 | project_name = dequote(args[3]) 40 | 41 | # TODO: write your remove hook here (optional) 42 | 43 | # exit 44 | sys.exit(0) 45 | 46 | 47 | 48 | if __name__ == '__main__': 49 | main(sys.argv,len(sys.argv)) 50 | 51 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Android iBeacon Library for Titanium Appcelerator 2 | 3 | This project is a module for Titanium Appcelerator, which allows Titanium apps that support Android to 4 | interact with iBeacons via an easy to use Java API. 5 | 6 | Apps can be notified of entering/exiting iBeacon regions, and can enable ranging to receive periodic beacon 7 | proximity reports. 8 | 9 | ## Getting and using the module 10 | 11 | This module can be installed and used in Titanium projects like any other module. To download the latest 12 | binary module, check out the `dist/` directory in this project. 13 | 14 | Once installed, [read the documentation](https://github.com/jamesfalkner/liferay-android-beacons/blob/master/documentation/index.md) (it lives in the `documentation/` directory) to learn how to interact with your iBeacons. 15 | 16 | ## Requires for building 17 | 18 | If you wish to build this module yourself, you will need a Titanium+Android build environment consisting of: 19 | 20 | * [Titanium CLI](http://docs.appcelerator.com/titanium/3.0/#!/guide/Titanium_Command-Line_Interface_Reference) to create module projects (since Release 3.3.0). 21 | * [Titanium Mobile SDK 3.2.0 or later](http://www.appcelerator.com/titanium/titanium-sdk/) 22 | * All of the [prerequisites for developing Android applications](https://developer.android.com/sdk/index.html). 23 | * [Android NDK Release 9.d or later](https://developer.android.com/tools/sdk/ndk/index.html) 24 | * [Ant 1.7.1](http://ant.apache.org) or above must be installed and in your system PATH to build from the command line. 25 | * [gperf must be installed](http://docs.appcelerator.com/titanium/3.0/#!/guide/Installing_gperf) and in your system PATH. 26 | 27 | ## How to build 28 | 29 | To build this project: 30 | 31 | * Fork a copy 32 | * Edit the `build.properties` file and change each setting therein to point to your local copy of Titanium, Android SDK, and Android NDK. Here is an example of the paths this author uses on a Mac OS X system: 33 | 34 | ``` 35 | titanium.platform=/Users/jhf/Library/Application Support/Titanium/mobilesdk/osx/3.2.2.GA/android 36 | android.platform=/Users/jhf/androidsdk/platforms/android-10 37 | android.ndk=/Users/jhf/androidndk 38 | google.apis=/Users/jhf/androidsdk/add-ons/addon-google_apis-google-10 39 | ``` 40 | 41 | * Run `ant dist`. This creates the distribution in the `dist/` directory of the project. 42 | 43 | Other targets supported by Titanium include: 44 | 45 | * `ant clean` Removes all generated zips and binaries from previous builds. 46 | * `ant install` Runs the *dist* build target, generates a test project using `example/` as the *Resources*, and then installs it to a connected Android device. 47 | * `ant run.emulator` Launches an Android emulator for the *run* build target. 48 | * `ant run` Runs the *dist* build target, generates a test project using `example/` as the *Resources*, and then installs it to a running emulator (hint: use the *run.emulator* target to start up an emulator!). 49 | 50 | ## Author 51 | 52 | ![James Falkner Logo](https://cdn.lfrs.sl/www.liferay.com/image/user_male_portrait?img_id=6182018&t=1402762276765) 53 | 54 | * James Falkner (Liferay Community Manager) 55 | * `james.falkner@liferay.com` 56 | * [`@schtool`](http://twitter.com/schtool) 57 | 58 | 59 | ## License 60 | 61 | Copyright (c) 2015, Liferay Inc. All rights reserved. 62 | 63 | Licensed under the Apache License, Version 2.0 (the "License"); 64 | you may not use this file except in compliance with the License. 65 | You may obtain a copy of the License at 66 | 67 | http://www.apache.org/licenses/LICENSE-2.0 68 | 69 | Unless required by applicable law or agreed to in writing, software 70 | distributed under the License is distributed on an "AS IS" BASIS, 71 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 72 | See the License for the specific language governing permissions and 73 | limitations under the License. 74 | 75 | ## Notice 76 | 77 | This product includes software developed at 78 | [The Radius Networks](http://www.radiusnetworks.com) (http://www.radiusnetworks.com/). 79 | 80 | Android IBeacon Service 81 | 82 | Copyright 2013 Radius Networks 83 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | # Software License Agreement (Apache License 2.0) 2 | # Copyright (c) 2014, Liferay Inc. All rights reserved. 3 | 4 | Licensed under the Apache License, Version 2.0 (the "License"); 5 | you may not use this file except in compliance with the License. 6 | You may obtain a copy of the License at 7 | 8 | http://www.apache.org/licenses/LICENSE-2.0 9 | 10 | Unless required by applicable law or agreed to in writing, software 11 | distributed under the License is distributed on an "AS IS" BASIS, 12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | See the License for the specific language governing permissions and 14 | limitations under the License. 15 | 16 | 17 | Apache License 18 | Version 2.0, January 2004 19 | http://www.apache.org/licenses/ 20 | 21 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 22 | 23 | 1. Definitions. 24 | 25 | "License" shall mean the terms and conditions for use, reproduction, 26 | and distribution as defined by Sections 1 through 9 of this document. 27 | 28 | "Licensor" shall mean the copyright owner or entity authorized by 29 | the copyright owner that is granting the License. 30 | 31 | "Legal Entity" shall mean the union of the acting entity and all 32 | other entities that control, are controlled by, or are under common 33 | control with that entity. For the purposes of this definition, 34 | "control" means (i) the power, direct or indirect, to cause the 35 | direction or management of such entity, whether by contract or 36 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 37 | outstanding shares, or (iii) beneficial ownership of such entity. 38 | 39 | "You" (or "Your") shall mean an individual or Legal Entity 40 | exercising permissions granted by this License. 41 | 42 | "Source" form shall mean the preferred form for making modifications, 43 | including but not limited to software source code, documentation 44 | source, and configuration files. 45 | 46 | "Object" form shall mean any form resulting from mechanical 47 | transformation or translation of a Source form, including but 48 | not limited to compiled object code, generated documentation, 49 | and conversions to other media types. 50 | 51 | "Work" shall mean the work of authorship, whether in Source or 52 | Object form, made available under the License, as indicated by a 53 | copyright notice that is included in or attached to the work 54 | (an example is provided in the Appendix below). 55 | 56 | "Derivative Works" shall mean any work, whether in Source or Object 57 | form, that is based on (or derived from) the Work and for which the 58 | editorial revisions, annotations, elaborations, or other modifications 59 | represent, as a whole, an original work of authorship. For the purposes 60 | of this License, Derivative Works shall not include works that remain 61 | separable from, or merely link (or bind by name) to the interfaces of, 62 | the Work and Derivative Works thereof. 63 | 64 | "Contribution" shall mean any work of authorship, including 65 | the original version of the Work and any modifications or additions 66 | to that Work or Derivative Works thereof, that is intentionally 67 | submitted to Licensor for inclusion in the Work by the copyright owner 68 | or by an individual or Legal Entity authorized to submit on behalf of 69 | the copyright owner. For the purposes of this definition, "submitted" 70 | means any form of electronic, verbal, or written communication sent 71 | to the Licensor or its representatives, including but not limited to 72 | communication on electronic mailing lists, source code control systems, 73 | and issue tracking systems that are managed by, or on behalf of, the 74 | Licensor for the purpose of discussing and improving the Work, but 75 | excluding communication that is conspicuously marked or otherwise 76 | designated in writing by the copyright owner as "Not a Contribution." 77 | 78 | "Contributor" shall mean Licensor and any individual or Legal Entity 79 | on behalf of whom a Contribution has been received by Licensor and 80 | subsequently incorporated within the Work. 81 | 82 | 2. Grant of Copyright License. Subject to the terms and conditions of 83 | this License, each Contributor hereby grants to You a perpetual, 84 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 85 | copyright license to reproduce, prepare Derivative Works of, 86 | publicly display, publicly perform, sublicense, and distribute the 87 | Work and such Derivative Works in Source or Object form. 88 | 89 | 3. Grant of Patent License. Subject to the terms and conditions of 90 | this License, each Contributor hereby grants to You a perpetual, 91 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 92 | (except as stated in this section) patent license to make, have made, 93 | use, offer to sell, sell, import, and otherwise transfer the Work, 94 | where such license applies only to those patent claims licensable 95 | by such Contributor that are necessarily infringed by their 96 | Contribution(s) alone or by combination of their Contribution(s) 97 | with the Work to which such Contribution(s) was submitted. If You 98 | institute patent litigation against any entity (including a 99 | cross-claim or counterclaim in a lawsuit) alleging that the Work 100 | or a Contribution incorporated within the Work constitutes direct 101 | or contributory patent infringement, then any patent licenses 102 | granted to You under this License for that Work shall terminate 103 | as of the date such litigation is filed. 104 | 105 | 4. Redistribution. You may reproduce and distribute copies of the 106 | Work or Derivative Works thereof in any medium, with or without 107 | modifications, and in Source or Object form, provided that You 108 | meet the following conditions: 109 | 110 | (a) You must give any other recipients of the Work or 111 | Derivative Works a copy of this License; and 112 | 113 | (b) You must cause any modified files to carry prominent notices 114 | stating that You changed the files; and 115 | 116 | (c) You must retain, in the Source form of any Derivative Works 117 | that You distribute, all copyright, patent, trademark, and 118 | attribution notices from the Source form of the Work, 119 | excluding those notices that do not pertain to any part of 120 | the Derivative Works; and 121 | 122 | (d) If the Work includes a "NOTICE" text file as part of its 123 | distribution, then any Derivative Works that You distribute must 124 | include a readable copy of the attribution notices contained 125 | within such NOTICE file, excluding those notices that do not 126 | pertain to any part of the Derivative Works, in at least one 127 | of the following places: within a NOTICE text file distributed 128 | as part of the Derivative Works; within the Source form or 129 | documentation, if provided along with the Derivative Works; or, 130 | within a display generated by the Derivative Works, if and 131 | wherever such third-party notices normally appear. The contents 132 | of the NOTICE file are for informational purposes only and 133 | do not modify the License. You may add Your own attribution 134 | notices within Derivative Works that You distribute, alongside 135 | or as an addendum to the NOTICE text from the Work, provided 136 | that such additional attribution notices cannot be construed 137 | as modifying the License. 138 | 139 | You may add Your own copyright statement to Your modifications and 140 | may provide additional or different license terms and conditions 141 | for use, reproduction, or distribution of Your modifications, or 142 | for any such Derivative Works as a whole, provided Your use, 143 | reproduction, and distribution of the Work otherwise complies with 144 | the conditions stated in this License. 145 | 146 | 5. Submission of Contributions. Unless You explicitly state otherwise, 147 | any Contribution intentionally submitted for inclusion in the Work 148 | by You to the Licensor shall be under the terms and conditions of 149 | this License, without any additional terms or conditions. 150 | Notwithstanding the above, nothing herein shall supersede or modify 151 | the terms of any separate license agreement you may have executed 152 | with Licensor regarding such Contributions. 153 | 154 | 6. Trademarks. This License does not grant permission to use the trade 155 | names, trademarks, service marks, or product names of the Licensor, 156 | except as required for reasonable and customary use in describing the 157 | origin of the Work and reproducing the content of the NOTICE file. 158 | 159 | 7. Disclaimer of Warranty. Unless required by applicable law or 160 | agreed to in writing, Licensor provides the Work (and each 161 | Contributor provides its Contributions) on an "AS IS" BASIS, 162 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 163 | implied, including, without limitation, any warranties or conditions 164 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 165 | PARTICULAR PURPOSE. You are solely responsible for determining the 166 | appropriateness of using or redistributing the Work and assume any 167 | risks associated with Your exercise of permissions under this License. 168 | 169 | 8. Limitation of Liability. In no event and under no legal theory, 170 | whether in tort (including negligence), contract, or otherwise, 171 | unless required by applicable law (such as deliberate and grossly 172 | negligent acts) or agreed to in writing, shall any Contributor be 173 | liable to You for damages, including any direct, indirect, special, 174 | incidental, or consequential damages of any character arising as a 175 | result of this License or out of the use or inability to use the 176 | Work (including but not limited to damages for loss of goodwill, 177 | work stoppage, computer failure or malfunction, or any and all 178 | other commercial damages or losses), even if such Contributor 179 | has been advised of the possibility of such damages. 180 | 181 | 9. Accepting Warranty or Additional Liability. While redistributing 182 | the Work or Derivative Works thereof, You may choose to offer, 183 | and charge a fee for, acceptance of support, warranty, indemnity, 184 | or other liability obligations and/or rights consistent with this 185 | License. However, in accepting such obligations, You may act only 186 | on Your own behalf and on Your sole responsibility, not on behalf 187 | of any other Contributor, and only if You agree to indemnify, 188 | defend, and hold each Contributor harmless for any liability 189 | incurred by, or claims asserted against, such Contributor by reason 190 | of your accepting any such warranty or additional liability. 191 | 192 | END OF TERMS AND CONDITIONS 193 | 194 | APPENDIX: How to apply the Apache License to your work. 195 | 196 | To apply the Apache License to your work, attach the following 197 | boilerplate notice, with the fields enclosed by brackets "[]" 198 | replaced with your own identifying information. (Don't include 199 | the brackets!) The text should be enclosed in the appropriate 200 | comment syntax for the file format. We also recommend that a 201 | file or class name and description of purpose be included on the 202 | same "printed page" as the copyright notice for easier 203 | identification within third-party archives. 204 | 205 | Copyright [yyyy] [name of copyright owner] 206 | 207 | Licensed under the Apache License, Version 2.0 (the "License"); 208 | you may not use this file except in compliance with the License. 209 | You may obtain a copy of the License at 210 | 211 | http://www.apache.org/licenses/LICENSE-2.0 212 | 213 | Unless required by applicable law or agreed to in writing, software 214 | distributed under the License is distributed on an "AS IS" BASIS, 215 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 216 | See the License for the specific language governing permissions and 217 | limitations under the License. -------------------------------------------------------------------------------- /src/com/liferay/beacons/LiferayBeaconsModule.java: -------------------------------------------------------------------------------- 1 | /** 2 | * Copyright 2015 Liferay, Inc. All rights reserved. 3 | * http://www.liferay.com 4 | * 5 | * Licensed under the Apache License, Version 2.0 (the "License"); 6 | * you may not use this file except in compliance with the License. 7 | * You may obtain a copy of the License at 8 | * 9 | * http://www.apache.org/licenses/LICENSE-2.0 10 | * 11 | * Unless required by applicable law or agreed to in writing, software 12 | * distributed under the License is distributed on an "AS IS" BASIS, 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | * See the License for the specific language governing permissions and 15 | * limitations under the License. 16 | * 17 | * @author James Falkner 18 | */ 19 | 20 | package com.liferay.beacons; 21 | 22 | import android.app.Activity; 23 | import android.content.Context; 24 | import android.content.Intent; 25 | import android.content.ServiceConnection; 26 | import android.os.RemoteException; 27 | import com.radiusnetworks.ibeacon.*; 28 | import org.appcelerator.kroll.KrollDict; 29 | import org.appcelerator.kroll.KrollModule; 30 | import org.appcelerator.kroll.annotations.Kroll; 31 | import org.appcelerator.kroll.common.Log; 32 | import org.appcelerator.titanium.TiApplication; 33 | import org.appcelerator.titanium.util.TiConvert; 34 | 35 | import java.util.ArrayList; 36 | import java.util.Collection; 37 | import java.util.HashMap; 38 | import java.util.List; 39 | 40 | /** 41 | * Events: enteredRegion, exitedRegion, determinedRegionState, beaconProximity 42 | */ 43 | @Kroll.module(name="LiferayBeacons", id="com.liferay.beacons") 44 | public class LiferayBeaconsModule extends KrollModule implements IBeaconConsumer 45 | { 46 | 47 | private static IBeaconManager iBeaconManager; 48 | 49 | // Standard Debugging variables 50 | private static final String TAG = "LiferayBeaconsModule"; 51 | 52 | private boolean autoRange = true; 53 | private boolean ready = false; 54 | 55 | public LiferayBeaconsModule() { 56 | super(); 57 | } 58 | 59 | @Kroll.onAppCreate 60 | public static void onAppCreate(TiApplication app) 61 | { 62 | Log.d(TAG, "onAppCreate: Liferay Android Beacons 0.4"); 63 | 64 | iBeaconManager = IBeaconManager.getInstanceForApplication(app); 65 | 66 | // set some less battery-intensive settings compared to the defaults 67 | iBeaconManager.setForegroundScanPeriod(1200); 68 | iBeaconManager.setForegroundBetweenScanPeriod(2300); 69 | iBeaconManager.setBackgroundScanPeriod(10000); 70 | iBeaconManager.setBackgroundBetweenScanPeriod(60 * 1000); 71 | 72 | // to see debugging from the Radius networks lib, set this to true 73 | IBeaconManager.LOG_DEBUG = false; 74 | } 75 | 76 | /** 77 | * See if Bluetooth 4.0 & LE is available on device 78 | * 79 | * @return true if iBeacons can be used, false otherwise 80 | */ 81 | @Kroll.method 82 | public boolean checkAvailability() { 83 | try { 84 | return iBeaconManager.checkAvailability(); 85 | } catch (Exception ex) { 86 | return false; 87 | } 88 | } 89 | 90 | /** 91 | * See if Module is Ready 92 | * 93 | * @return true/false 94 | */ 95 | @Kroll.method 96 | public boolean isReady() { 97 | return this.ready; 98 | } 99 | 100 | /** 101 | * Binds the activity to the Beacon Service 102 | */ 103 | @Kroll.method 104 | public void bindBeaconService() { 105 | Log.d(TAG, "bindService"); 106 | iBeaconManager.bind(this); 107 | } 108 | 109 | /** 110 | * Unbinds the activity to the Beacon Service 111 | */ 112 | @Kroll.method 113 | public void unbindBeaconService() { 114 | Log.d(TAG, "unbindService"); 115 | iBeaconManager.unBind(this); 116 | } 117 | 118 | /** 119 | * Throttles down iBeacon library when app placed in background (but you have to 120 | * detect this yourself, this module does not know when apps are put in background). 121 | * 122 | * @param flag Whether to enable background mode or not. 123 | */ 124 | @Kroll.method 125 | public void setBackgroundMode(boolean flag) 126 | { 127 | Log.d(TAG, "setBackgroundMode: " + flag); 128 | 129 | if (!checkAvailability()) { 130 | Log.d(TAG, "Bluetooth LE not available or no permissions on this device"); 131 | return; 132 | } 133 | iBeaconManager.setBackgroundMode(this, flag); 134 | 135 | 136 | } 137 | 138 | /** 139 | * Turns on auto ranging. When auto ranging is on, upon entering a region, this 140 | * module will automatically begin ranging for beacons within that region, and 141 | * stop ranging for beacons when the region is exited. Note ranging requires more 142 | * battery power so care should be taken with this setting. 143 | */ 144 | @Kroll.method 145 | public void enableAutoRanging() 146 | { 147 | setAutoRange(true); 148 | } 149 | 150 | /** 151 | * Turns off auto ranging. See description of enableAutoRanging for more details. 152 | * 153 | * @see #enableAutoRanging() 154 | */ 155 | @Kroll.method 156 | public void disableAutoRanging() 157 | { 158 | setAutoRange(false); 159 | } 160 | 161 | /** 162 | * Turns auto ranging on or off. See description of enableAutoRanging for more details. 163 | * 164 | * @param autoRange if true, turns on auto ranging. Otherwise, turns it off. 165 | * 166 | * @see #enableAutoRanging() 167 | * 168 | */ 169 | @Kroll.method 170 | public void setAutoRange(boolean autoRange) 171 | { 172 | Log.d(TAG, "setAutoRange: " + autoRange); 173 | this.autoRange = autoRange; 174 | 175 | } 176 | 177 | /** 178 | * Set the scan periods for the bluetooth scanner. 179 | * 180 | * @param scanPeriods the scan periods. 181 | */ 182 | @Kroll.method 183 | public void setScanPeriods(Object scanPeriods) 184 | { 185 | 186 | Log.d(TAG, "setScanPeriods: " + scanPeriods); 187 | 188 | HashMap dict = (HashMap)scanPeriods; 189 | 190 | int foregroundScanPeriod = TiConvert.toInt(dict, "foregroundScanPeriod"); 191 | int foregroundBetweenScanPeriod = TiConvert.toInt(dict, "foregroundBetweenScanPeriod"); 192 | int backgroundScanPeriod = TiConvert.toInt(dict, "backgroundScanPeriod"); 193 | int backgroundBetweenScanPeriod = TiConvert.toInt(dict, "backgroundBetweenScanPeriod"); 194 | 195 | iBeaconManager.setForegroundScanPeriod(foregroundScanPeriod); 196 | iBeaconManager.setForegroundBetweenScanPeriod(foregroundBetweenScanPeriod); 197 | iBeaconManager.setBackgroundScanPeriod(backgroundScanPeriod); 198 | iBeaconManager.setBackgroundBetweenScanPeriod(backgroundBetweenScanPeriod); 199 | } 200 | 201 | /** 202 | * Start monitoring a region. 203 | * @param region the region to monitor, expected to be a property dictionary from javascript code. 204 | */ 205 | @Kroll.method 206 | public void startMonitoringForRegion(Object region) 207 | { 208 | Log.d(TAG, "startMonitoringForRegion: " + region); 209 | 210 | if (!checkAvailability()) { 211 | Log.d(TAG, "Bluetooth LE not available or no permissions on this device"); 212 | return; 213 | } 214 | try { 215 | HashMap dict = (HashMap)region; 216 | 217 | String identifier = TiConvert.toString(dict, "identifier"); 218 | String uuid = TiConvert.toString(dict, "uuid").toLowerCase(); 219 | Integer major = (dict.get("major") != null) ? TiConvert.toInt(dict, "major") : null; 220 | Integer minor = (dict.get("minor") != null) ? TiConvert.toInt(dict, "minor") : null; 221 | 222 | Region r = new Region(identifier, uuid, major, minor); 223 | 224 | Log.d(TAG, "Beginning to monitor region " + r); 225 | iBeaconManager.startMonitoringBeaconsInRegion(r); 226 | } catch (RemoteException ex) { 227 | Log.e(TAG, "Cannot start monitoring region " + TiConvert.toString(region, "identifier"), ex); 228 | } 229 | } 230 | 231 | 232 | /** 233 | * Compatibility method for popular iOS FOSS iBeacon library. 234 | * 235 | * @see #startRangingForRegion(Object) 236 | * 237 | * @param region the region to range, expected to be a property dictionary from javascript code. 238 | */ 239 | @Kroll.method 240 | public void startRangingForBeacons(Object region) { 241 | startRangingForRegion(region); 242 | } 243 | 244 | /** 245 | * Start ranging a region. You can only range regions into which you have entered. 246 | * 247 | * @param region the region to range, expected to be a property dictionary from javascript code. 248 | */ 249 | @Kroll.method 250 | public void startRangingForRegion(Object region) 251 | { 252 | Log.d(TAG, "startRangingForRegion: " + region); 253 | 254 | if (!checkAvailability()) { 255 | Log.d(TAG, "Bluetooth LE not available or no permissions on this device"); 256 | return; 257 | } 258 | try { 259 | HashMap dict = (HashMap)region; 260 | 261 | String identifier = TiConvert.toString(dict, "identifier"); 262 | String uuid = TiConvert.toString(dict, "uuid").toLowerCase(); 263 | Integer major = (dict.get("major") != null) ? TiConvert.toInt(dict, "major") : null; 264 | Integer minor = (dict.get("minor") != null) ? TiConvert.toInt(dict, "minor") : null; 265 | 266 | Region r = new Region(identifier, uuid, major, minor); 267 | 268 | Log.d(TAG, "Beginning to monitor region " + r); 269 | iBeaconManager.startRangingBeaconsInRegion(r); 270 | } catch (RemoteException ex) { 271 | Log.e(TAG, "Cannot start ranging region " + TiConvert.toString(region, "identifier"), ex); 272 | } 273 | } 274 | 275 | 276 | /** 277 | * Stop monitoring everything. 278 | */ 279 | @Kroll.method 280 | public void stopMonitoringAllRegions() 281 | { 282 | 283 | Log.d(TAG, "stopMonitoringAllRegions"); 284 | 285 | for (Region r : iBeaconManager.getMonitoredRegions()) { 286 | try { 287 | iBeaconManager.stopMonitoringBeaconsInRegion(r); 288 | Log.d(TAG, "Stopped monitoring region " + r); 289 | } catch (RemoteException ex) { 290 | Log.e(TAG, "Cannot stop monitoring region " + r.getUniqueId(), ex); 291 | } 292 | } 293 | 294 | } 295 | 296 | /** 297 | * Stop ranging for everything. 298 | */ 299 | @Kroll.method 300 | public void stopRangingForAllBeacons() 301 | { 302 | 303 | Log.d(TAG, "stopRangingForAllBeacons"); 304 | 305 | for (Region r : iBeaconManager.getRangedRegions()) { 306 | try { 307 | iBeaconManager.stopRangingBeaconsInRegion(r); 308 | Log.d(TAG, "Stopped ranging region " + r); 309 | } catch (RemoteException ex) { 310 | Log.e(TAG, "Cannot stop ranging region " + r.getUniqueId(), ex); 311 | } 312 | } 313 | } 314 | 315 | 316 | @Override 317 | public void onStart(Activity activity) 318 | { 319 | // This method is called when the module is loaded and the root context is started 320 | 321 | Log.d(TAG, "[MODULE LIFECYCLE EVENT] start"); 322 | iBeaconManager.bind(this); 323 | 324 | super.onStart(activity); 325 | } 326 | 327 | @Override 328 | public void onStop(Activity activity) 329 | { 330 | // This method is called when the root context is stopped 331 | 332 | Log.d(TAG, "[MODULE LIFECYCLE EVENT] stop"); 333 | 334 | if (!iBeaconManager.isBound(this)) { 335 | iBeaconManager.bind(this); 336 | } 337 | super.onStop(activity); 338 | } 339 | 340 | @Override 341 | public void onPause(Activity activity) 342 | { 343 | // This method is called when the root context is being suspended 344 | 345 | Log.d(TAG, "[MODULE LIFECYCLE EVENT] pause"); 346 | if (!iBeaconManager.isBound(this)) { 347 | iBeaconManager.bind(this); 348 | } 349 | 350 | super.onPause(activity); 351 | } 352 | 353 | @Override 354 | public void onResume(Activity activity) 355 | { 356 | // This method is called when the root context is being resumed 357 | 358 | Log.d(TAG, "[MODULE LIFECYCLE EVENT] resume"); 359 | if (!iBeaconManager.isBound(this)) { 360 | iBeaconManager.bind(this); 361 | } 362 | 363 | super.onResume(activity); 364 | } 365 | 366 | @Override 367 | public void onDestroy(Activity activity) 368 | { 369 | // This method is called when the root context is being destroyed 370 | 371 | Log.d(TAG, "[MODULE LIFECYCLE EVENT] destroy"); 372 | iBeaconManager.unBind(this); 373 | 374 | super.onDestroy(activity); 375 | } 376 | 377 | public void onIBeaconServiceConnect() { 378 | KrollDict e = new KrollDict(); 379 | e.put("message", "success"); 380 | fireEvent("serviceBound", e); 381 | 382 | Log.d(TAG, "onIBeaconServiceConnect"); 383 | this.ready = true; //so we know the module is ready to setup event listeners 384 | iBeaconManager.setMonitorNotifier(new MonitorNotifier() { 385 | 386 | public void didEnterRegion(Region region) { 387 | 388 | Log.d(TAG, "Entered region: " + region); 389 | 390 | try { 391 | if (autoRange) { 392 | Log.d(TAG, "Beginning to autoRange region " + region); 393 | iBeaconManager.startRangingBeaconsInRegion(region); 394 | } 395 | KrollDict e = new KrollDict(); 396 | e.put("identifier", region.getUniqueId()); 397 | fireEvent("enteredRegion", e); 398 | } catch (RemoteException ex) { 399 | Log.e(TAG, "Cannot turn on ranging for region " + region.getUniqueId(), ex); 400 | } 401 | } 402 | 403 | public void didExitRegion(Region region) { 404 | 405 | Log.d(TAG, "Exited region: " + region); 406 | 407 | try { 408 | iBeaconManager.stopRangingBeaconsInRegion(region); 409 | KrollDict e = new KrollDict(); 410 | e.put("identifier", region.getUniqueId()); 411 | fireEvent("exitedRegion", e); 412 | } catch (RemoteException ex) { 413 | Log.e(TAG, "Cannot turn off ranging for region " + region.getUniqueId(), ex); 414 | } 415 | } 416 | 417 | public void didDetermineStateForRegion(int state, Region region) { 418 | if (state == INSIDE) { 419 | try { 420 | if (autoRange) { 421 | Log.d(TAG, "Beginning to autoRange region " + region); 422 | iBeaconManager.startRangingBeaconsInRegion(region); 423 | } 424 | KrollDict e = new KrollDict(); 425 | e.put("identifier", region.getUniqueId()); 426 | e.put("regionState", "inside"); 427 | fireEvent("determinedRegionState", e); 428 | } catch (RemoteException e) { 429 | Log.e(TAG, "Cannot turn on ranging for region during didDetermineState" + region); 430 | } 431 | } else if (state == OUTSIDE) { 432 | try { 433 | iBeaconManager.stopRangingBeaconsInRegion(region); 434 | KrollDict e = new KrollDict(); 435 | e.put("identifier", region.getUniqueId()); 436 | e.put("regionState", "outside"); 437 | fireEvent("determinedRegionState", e); 438 | } catch (RemoteException e) { 439 | Log.e(TAG, "Cannot turn off ranging for region during didDetermineState" + region); 440 | } 441 | } else { 442 | Log.d(TAG, "Unknown region state: " + state + " for region: " + region); 443 | } 444 | 445 | } 446 | }); 447 | 448 | iBeaconManager.setRangeNotifier(new RangeNotifier() { 449 | public void didRangeBeaconsInRegion(Collection iBeacons, Region region) { 450 | 451 | List finalBeacons = new ArrayList(iBeacons.size()); 452 | 453 | for (IBeacon beacon : iBeacons) { 454 | KrollDict beaconDict = new KrollDict(); 455 | beaconDict.put("identifier", region.getUniqueId()); 456 | beaconDict.put("uuid", beacon.getProximityUuid()); 457 | beaconDict.put("major", beacon.getMajor()); 458 | beaconDict.put("minor", beacon.getMinor()); 459 | beaconDict.put("proximity", getProximityName(beacon.getProximity())); 460 | beaconDict.put("accuracy", beacon.getAccuracy()); 461 | beaconDict.put("rssi", beacon.getRssi()); 462 | beaconDict.put("power", beacon.getTxPower()); 463 | finalBeacons.add(beaconDict); 464 | 465 | fireEvent("beaconProximity", beaconDict); 466 | } 467 | 468 | KrollDict e = new KrollDict(); 469 | e.put("identifier", region.getUniqueId()); 470 | e.put("beacons", finalBeacons.toArray()); 471 | fireEvent("beaconRanges", e); 472 | } 473 | 474 | }); 475 | 476 | } 477 | 478 | public static String getProximityName(int p) { 479 | switch (p) { 480 | case IBeacon.PROXIMITY_FAR: 481 | return "far"; 482 | case IBeacon.PROXIMITY_IMMEDIATE: 483 | return "immediate"; 484 | case IBeacon.PROXIMITY_NEAR: 485 | return "near"; 486 | default: 487 | return "unknown"; 488 | } 489 | } 490 | 491 | 492 | // methods to bind and unbind 493 | 494 | public Context getApplicationContext() { 495 | return super.getActivity().getApplicationContext(); 496 | } 497 | 498 | public void unbindService(ServiceConnection serviceConnection) { 499 | Log.d(TAG, "unbindService"); 500 | super.getActivity().unbindService(serviceConnection); 501 | } 502 | 503 | public boolean bindService(Intent intent, ServiceConnection serviceConnection, int i) { 504 | Log.d(TAG, "bindService"); 505 | return super.getActivity().bindService(intent, serviceConnection, i); 506 | } 507 | } 508 | 509 | -------------------------------------------------------------------------------- /documentation/index.md: -------------------------------------------------------------------------------- 1 | # liferay.beacons Module 2 | 3 | ## Description 4 | 5 | A Titanium module to interact with iBeacons in Titanium projects that support Android. 6 | 7 | ## Accessing the liferay.beacons Module 8 | 9 | Place the ZIP file into your project's root directory, and declare the module and required android permissions in your `tiapp.xml` file (or in your custom `platform/android/AndroidManifest.xml` file if you are using that): 10 | 11 | ``` 12 | 13 | ... 14 | 15 | 16 | 18 | 20 | 22 | 24 | 25 | 30 | 31 | 33 | 34 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | ... 44 | 45 | com.liferay.beacons 46 | 47 | ... 48 | 49 | ``` 50 | 51 | Don't forget to replace the `[YOUR_APP_PACKAGE_NAME]` with your app's package name, e.g. *com.companyname.app*, and you can read [Radius Networks' docs](http://altbeacon.github.io/android-beacon-library/configure.html) on this topic as well. 52 | 53 | Next, to access this module from JavaScript, you would do the following: 54 | 55 | ``` 56 | var TiBeacons = null; 57 | if (Ti.Platform.name === "android") { 58 | TiBeacons = require("com.liferay.beacons"); 59 | } else { 60 | console.log("liferay.beacons not supported on " + Ti.Platform.name); 61 | } 62 | ``` 63 | 64 | As of Android 6.0, your app will need to request permission after launch in the form of a popup. This will need to be accepted by the user or else the service will fail. You can request permisison using an approach simialr to the below. 65 | 66 | ``` 67 | var permissions = ['android.permission.ACCESS_FINE_LOCATION']; 68 | Ti.Android.requestPermissions(permissions, function(e) { 69 | if (e.success) { 70 | Ti.API.info("SUCCESS"); 71 | } else { 72 | Ti.API.info("ERROR: " + e.error); 73 | } 74 | }); 75 | ``` 76 | 77 | Note that this library is only available for the Android platform. Attempting to use it on other platforms 78 | will fail in different ways and *people will point and laugh at you*. 79 | 80 | ## Using the iBeacons API 81 | 82 | This module enables Titanium projects to start/stop monitoring for beacon region events (enter/exit/determineState), 83 | as well as ranging events (proximity). You can configure the beacon scan periods (to adjust battery usage), 84 | and can enable or disable auto-ranging (when auto-ranging is enabled, then ranging will be turned on when a 85 | region is entered, and turned off when the region is exited). 86 | 87 | Note there are *two* ranging events that are produced from this module: `beaconProximity` and `beaconRanges`. In most cases 88 | you will only attach listeners for one of these, because they tell you almost the same information. Read below to find out more. 89 | 90 | ### Setting up and starting to monitor and/or range 91 | 92 | A typical workflow for beacons, and the corresponding JavaScript APIs for this module: 93 | 94 | 1. Get a reference to the module via 95 | 96 | ``` 97 | var TiBeacons = require('com.liferay.beacons'); 98 | ``` 99 | 100 | **Note** that when Titanium evaluates the `require()` statement, it will immediately return from it while the module sets up the native BLE binding asynchronously. This means, for example, that you should not attempt to call `startMonitoringForRegion()` or `startRangingForRegion()` immediately after the call to `require()`. Instead, call them in a UI callback (e.g. when a button is clicked as part of an event handler, or when a specific window is opened). If you attempt to begin ranging or monitoring immediately after `require()`ing the module, you'll likely get an error such as 101 | 102 | ``` 103 | android.os.RemoteException: The IBeaconManager is not bound to the service. Call iBeaconManager.bind(IBeaconConsumer consumer) and wait for a callback to onIBeaconServiceConnect() 104 | ``` 105 | 106 | Instead of guessing when the service is ready, we can check using the following method adn force the bind: 107 | 108 | ``` 109 | var handle; 110 | TiBeacons.bindBeaconService(); // This will force the bind to prevent TiBeacons.isReady() from always remaining false 111 | handle = setInterval(function(){ 112 | if(!TiBeacons.isReady()) 113 | return; 114 | 115 | Ti.API.info("Okay! Module is ready!"); 116 | clearInterval(handle); 117 | handle = null; 118 | 119 | //setup your event listeners here 120 | }, 1000); 121 | ``` 122 | 123 | 2. See if it's supported on the device via `TiBeacons.checkAvailability()` - If it is not, you should not attempt to call any other APIs, and somehow indicate that it's not supported in your app to the end user. The module 124 | 125 | 3. Decide whether you want auto-ranging, and turn it on via `TiBeacons.setAutoRange(true)` if you want it, or `TiBeacons.setAutoRange(false)` if not. The default is `true` (that is, auto-ranging is enabled). 126 | 127 | 4. Attach listeners for region and range events 128 | 129 | ``` 130 | TiBeacons.addEventListener("enteredRegion", handleRegionEnter); 131 | TiBeacons.addEventListener("exitedRegion", handleRegionExit); 132 | TiBeacons.addEventListener("determinedRegionState", handleRegionDeterminedState); 133 | 134 | /* You probably only want one of these */ 135 | TiBeacons.addEventListener("beaconProximity", handleProximityEvent); 136 | TiBeacons.addEventListener("beaconRanges", handleRanges); 137 | ``` 138 | 139 | You can also remove event listeners using the `TiBeacons.removeEventListener()`, for example: 140 | 141 | ``` 142 | TiBeacons.removeEventListener("enteredRegion", handleRegionEnter); 143 | ``` 144 | 145 | 5. Begin monitoring one or more regions 146 | 147 | ``` 148 | TiBeacons.startMonitoringForRegion({ 149 | identifier: 'Region by UUID only', 150 | uuid: '11111111-2222-3333-4444-555555555555' 151 | }); 152 | 153 | TiBeacons.startMonitoringForRegion({ 154 | identifier: 'Region by UUID and major', 155 | uuid: '11111111-2222-3333-4444-555555555555', 156 | major: 2112 157 | }); 158 | 159 | TiBeacons.startMonitoringForRegion({ 160 | identifier: 'Region by UUID and major and minor', 161 | uuid: '11111111-2222-3333-4444-555555555555', 162 | major: 2112, 163 | minor: 73 164 | }); 165 | 166 | ``` 167 | 168 | Once this is called, when the device enters or exits a region, the corresponding listener's callback will be called. 169 | 170 | If autoranging is enabled, then the moment a region is entered, ranging (which is more expensive in terms of power) begins, and listener callbacks will be called for those as well. 171 | 172 | If autoranging is NOT enabled, you must manually begin ranging (if you are interested in proximity/range events) like this: 173 | 174 | ``` 175 | TiBeacons.startRangingForBeacons({ 176 | identifier: 'Region by UUID only', 177 | uuid: '11111111-2222-3333-4444-555555555555' 178 | }); 179 | ``` 180 | 181 | ### Stopping monitoring/ranging 182 | 183 | To turn everything off: 184 | 185 | ``` 186 | TiBeacons.stopRangingForAllBeacons(); 187 | TiBeacons.stopMonitoringAllRegions(); 188 | TiBeacons.unbindBeaconService(); // to force unbind 189 | ``` 190 | 191 | ### Objects passed to the callbacks 192 | 193 | When one of your registered listeners' callbacks is called, they will receive different kinds of objects. Here are examples that print out all of the values received by each of your callbacks: 194 | 195 | #### enteredRegion 196 | 197 | ``` 198 | function enteredRegionCallback(e) { 199 | console.log("identifer: " + e.identifier); 200 | } 201 | ``` 202 | 203 | #### exitedRegion 204 | 205 | ``` 206 | function exitedRegionCallback(e) { 207 | console.log("identifer: " + e.identifier); 208 | } 209 | ``` 210 | 211 | #### determinedRegionState 212 | 213 | State can be either `inside` or `outside`. If the state is determined to be *unknown* then the callback will not be called. 214 | 215 | ``` 216 | function determinedRegionStateCallback(e) { 217 | console.log("identifer: " + e.identifier); 218 | 219 | // it's either 'inside' or 'outside' 220 | console.log("regionState: " + e.regionState); 221 | } 222 | ``` 223 | 224 | #### beaconProximity 225 | 226 | ``` 227 | function beaconProximityCallback(e) { 228 | console.log("identifer: " + e.identifier); 229 | console.log("uuid: " + e.uuid); 230 | console.log("major: " + e.major); 231 | console.log("minor: " + e.minor); 232 | console.log("proximity: " + e.proximity); 233 | console.log("accuracy: " + e.accuracy); 234 | console.log("rssi: " + e.rssi); 235 | console.log("power: " + e.power); 236 | } 237 | ``` 238 | 239 | Note that the proximity could be one of `immediate`, `near`, `far`, or `unknown`. See the [Radius Networks' docs](http://altbeacon.github.io/android-beacon-library/distance-calculations.html) for more detail about accuracy, rssi, and power values given in the callback object. 240 | 241 | #### beaconRanges 242 | 243 | This event payload contains the same data as the `beaconProximity` payload, except this event is only fired once 244 | per hardware scan cycle, and the event contains an *array* of beacons in its payload, so that you can know how many beacons were scanned 245 | during the scan period. 246 | 247 | For example, if during a scan period, 7 beacons were ranged, then the `beaconProximity` event will be fired 7 times in a row, once for each ranged beacon, 248 | and then the `beaconRanges` event will be fired *once*, with an array of the 7 beacons as part of its payload. 249 | 250 | You normally only need to listen for `beaconProximity` *or* `beaconRanges`. You can listen for both if you like! 251 | 252 | Also note that the order of the beacons in the array of the `beaconRanges` event is not guaranteed to be in any particular order across callbacks. 253 | 254 | ``` 255 | function beaconRangingCallback(e) { 256 | 257 | console.log("I am in the " + e.identifier + " region"); 258 | console.log("I see " + e.beacons.length + " beacons in this region:"); 259 | console.log("----------------"); 260 | 261 | e.beacons.forEach(function(beacon, index) { 262 | console.log("Beacon number: " + index); 263 | console.log("uuid: " + beacon.uuid); 264 | console.log("major: " + beacon.major); 265 | console.log("minor: " + beacon.minor); 266 | console.log("proximity: " + beacon.proximity); 267 | console.log("accuracy: " + beacon.accuracy); 268 | console.log("rssi: " + beacon.rssi); 269 | console.log("power: " + beacon.power); 270 | console.log("----------------"); 271 | } 272 | } 273 | ``` 274 | 275 | ### Foreground vs. Background 276 | 277 | It is is a good idea for apps to reduce their power consumption when placed in the background by 278 | a user of an android device (e.g. when they press the Home button to send an app to the background, but 279 | do not hard-close the app). 280 | 281 | To that end, this module can be configured with different scan periods for foreground vs. background modes, 282 | however **this module DOES NOT DETECT when your app is sent to the background or brought back to the foreground**. 283 | You must manually detect foreground/background events and call the appropriate APIs on this module to tell it 284 | that it is now in the background and should use the background scan periods. Check out [Ben Bahrenburg's excellent 285 | Android Tools](https://github.com/benbahrenburg/benCoding.Android.Tools) for a super-easy way to auto-detect this. Here's an example: 286 | ``` 287 | var androidPlatformTools = require('bencoding.android.tools').createPlatform(); 288 | var isForeground = androidPlatformTools.isInForeground(); 289 | console.log("Am I currently in the foreground? " + isForeground); 290 | ``` 291 | You can call this repeatedly (e.g. every 5 seconds) using `setInterval()` and when foreground vs. background is detected, call `TiBeacons.setBackgroundMode()`. At least that's what I do. 292 | 293 | To configure the scan periods for foreground and background: 294 | ``` 295 | var TiBeacons = require('com.liferay.beacons'); 296 | TiBeacons.setScanPeriods({ 297 | foregroundScanPeriod: 1000, 298 | foregroundBetweenScanPeriod: 2000, 299 | backgroundScanPeriod: 5000, 300 | backgroundBetweenScanPeriod: 60000 301 | }); 302 | ``` 303 | This says that when the module is in "foreground mode" (set via `TiBeacons.setBackgroundMode(false);` when foreground 304 | is detected), then the device will scan for iBeacons for 1000ms, then wait 2000ms, then repeat. When in background mode (set via 305 | `TiBeacons.setBackgroundMode(true);` when the app is sent to the background), it will scan for iBeacons for 5000ms, 306 | followed by a 60000ms wait, and repeat. 307 | 308 | Check out [the source code to the underlying Radius Networks module](https://github.com/AltBeacon/android-beacon-library/blob/master/src/main/java/org/altbeacon/beacon/service/BeaconService.java) for a longer discussion on the best values to use, 309 | and the defaults. 310 | 311 | ## Example `app.js` for testing 312 | 313 | Here is a simple `app.js` application that you can use to see if things are working. You may need to modify it a bit to align with your specific beacon UUID. 314 | 315 | ``` 316 | // sample Titanium app.js app to test that things are working, 317 | // this assumes your hardware supports BLE and it's switched on. 318 | // you can use checkAvailability() to see if it's supported, but 319 | // we don't do that here just because we're lazy. 320 | 321 | var TiBeacons = require('com.liferay.beacons'); 322 | 323 | // make a window with two buttons to start and stop monitoring 324 | var win = Titanium.UI.createWindow({ 325 | title:'iBeacon Test', 326 | backgroundColor:'#fff' 327 | }); 328 | 329 | var b1 = Titanium.UI.createButton({ 330 | title: "Start Monitoring" 331 | }); 332 | var b2 = Titanium.UI.createButton({ 333 | title: "Stop Monitoring" 334 | }); 335 | 336 | var entered = function(reg) { 337 | alert("entered region: " + reg.identifier); 338 | }; 339 | 340 | var exited = function(reg) { 341 | alert("exited region: " + reg.identifier); 342 | }; 343 | 344 | b1.addEventListener('click', function(e) { 345 | 346 | // add the listeners for beacon region monitoring 347 | TiBeacons.addEventListener("enteredRegion", entered); 348 | TiBeacons.addEventListener("exitedRegion", exited); 349 | 350 | // start monitoring in the button click callback 351 | TiBeacons.startMonitoringForRegion({ 352 | identifier: 'FOO', 353 | uuid: '5AFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF' 354 | }); 355 | }); 356 | 357 | b2.addEventListener('click', function(e) { 358 | 359 | // stop everything 360 | TiBeacons.stopMonitoringAllRegions(); 361 | TiBeacons.removeEventListener("enteredRegion", entered); 362 | TiBeacons.removeEventListener("exitedRegion", exited); 363 | 364 | }); 365 | 366 | win.setLayout('vertical'); 367 | win.add(b1); 368 | win.add(b2); 369 | 370 | win.open(); 371 | ``` 372 | 373 | ## Author 374 | 375 | ![James Falkner Logo](https://cdn.lfrs.sl/www.liferay.com/image/user_male_portrait?img_id=6182018&t=1402762276765) 376 | 377 | * James Falkner (Liferay Community Manager) 378 | * `james.falkner@liferay.com` 379 | * [`@schtool`](http://twitter.com/schtool) 380 | 381 | ## License 382 | 383 | Copyright (c) 2015, Liferay Inc. All rights reserved. 384 | 385 | Licensed under the Apache License, Version 2.0 (the "License"); 386 | you may not use this file except in compliance with the License. 387 | You may obtain a copy of the License at 388 | 389 | http://www.apache.org/licenses/LICENSE-2.0 390 | 391 | Unless required by applicable law or agreed to in writing, software 392 | distributed under the License is distributed on an "AS IS" BASIS, 393 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 394 | See the License for the specific language governing permissions and 395 | limitations under the License. 396 | 397 | ## Notice 398 | 399 | This product includes software developed at 400 | [The Radius Networks](http://www.radiusnetworks.com/) (http://www.radiusnetworks.com/). 401 | 402 | Android IBeacon Service 403 | 404 | Copyright 2013 Radius Networks 405 | --------------------------------------------------------------------------------