{"id":19870919,"url":"https://github.com/beaconstac/android-sdk","last_synced_at":"2025-05-02T08:32:46.770Z","repository":{"id":30811673,"uuid":"34368831","full_name":"Beaconstac/Android-SDK","owner":"Beaconstac","description":"Beaconstac ADVANCED SDK for Android devices","archived":false,"fork":false,"pushed_at":"2019-06-13T12:08:19.000Z","size":6574,"stargazers_count":16,"open_issues_count":6,"forks_count":18,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-07T00:27:35.391Z","etag":null,"topics":["android-sdk","beacon","bluetooth-beacons","ibeacon","proximity-advertising","proximity-marketing","ranging-beacons","sdk"],"latest_commit_sha":null,"homepage":"https://dashboard.beaconstac.com","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Beaconstac.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-22T04:36:33.000Z","updated_at":"2022-06-03T21:39:56.000Z","dependencies_parsed_at":"2022-08-23T07:31:14.406Z","dependency_job_id":null,"html_url":"https://github.com/Beaconstac/Android-SDK","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FAndroid-SDK","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FAndroid-SDK/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FAndroid-SDK/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FAndroid-SDK/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Beaconstac","download_url":"https://codeload.github.com/Beaconstac/Android-SDK/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252008957,"owners_count":21679670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android-sdk","beacon","bluetooth-beacons","ibeacon","proximity-advertising","proximity-marketing","ranging-beacons","sdk"],"created_at":"2024-11-12T16:10:35.902Z","updated_at":"2025-05-02T08:32:46.365Z","avatar_url":"https://github.com/Beaconstac.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Beaconstac Android-SDK\n\n## Introduction\n\nBeaconstac Advanced Android SDK is meant only for specialized use cases. Please check with the support team before deciding to integrate this SDK.\n\n## Integrate with your existing project in Android Studio\n\n### In the `build.gradle` file of the app, add the following in the dependencies section:\n```groovy\nimplementation 'com.android.support.constraint:constraint-layout:1.0.2'\nimplementation 'com.mobstac.beaconstac:proximity:3.3+'\n```\n\nIf you want to receive background updates as shown in the sample app [here](examples/BeaconstacExample/app/src/main/java/com/mobstac/beaconstacdemo/NearbyBeaconBroadcastReceiver.java), add this to your app gradle\n```groovy\nimplementation 'com.google.android.gms:play-services-nearby:16.0.0'\n```\n\n\nLatest version\n\n[ ![Download](https://api.bintray.com/packages/mobstac/maven/proximity/images/download.svg) ](https://bintray.com/mobstac/maven/proximity/_latestVersion)\n\n## Permissions\n\n__Beaconstac requires the following permissions__\n```xml\n\u003cuses-permission android:name=\"android.permission.BLUETOOTH\" /\u003e\n\u003cuses-permission android:name=\"android.permission.BLUETOOTH_ADMIN\" /\u003e\n\u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n\u003cuses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" /\u003e\n\u003cuses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"/\u003e\n\u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/\u003e\n```\n\nIt is not necessary to explicitly add these permissions to your app. They will be added automatically when you include the SDK.\n\n### Runtime permissions\n\nSince Android 6.0, Android has introduced the concept of runtime permissions. Beaconstac SDK requires one runtime permission:\n\n__Location__\n\nBeaconstac requires the location permission to scan for nearby beacons. Beaconstac SDK's initialize() will fail if location permission is denied.\n\n### Prerequisites\n\n1. Please extract your developer token from the Beaconstac dashboard under \"My Account\".\n2. Internet access is required to initialize the SDK.\n3. Bluetooth enabled for scanning beacons.\n\n## Usage\n\n### Use our one line integration\n\n__Note:__ If this is used, the Beaconstac SDK will automatically start scanning for beacons and trigger notifications based on rules defined on Beaconstac dashboard. You can also explicitly start or stop beacon scanning by calling `Beaconstac.getInstance(getApplicationContext()).startScanningBeacons()` and `Beaconstac.getInstance(getApplicationContext()).stopScanningBeacons()` respectively. Please refer [advanced](#3-start-scan) for more info.\n\n__For using the SDK while the app is in the background or terminated state, please refer [Handling background scanning and delivering notifications](#handling-background-scanning-and-delivering-notifications).__\n\n```java\nBeaconstac.initialize(getApplicationContext(), MY_DEVELOPER_TOKEN, new MSErrorListener() {\n    @Override\n    public void onError(MSException msException) {\n        Log.d(\"Beaconstac\", msException.getErrorMessage());\n    }\n});\n```\n\n### OR\n\n### Use our advanced integration\n\n__1. Initialise the SDK with your developer token (preferably in the Application class)__\n\n```java\n\nBeaconstac.initialize(getApplicationContext(), MY_DEVELOPER_TOKEN, new MSSyncListener() {\n    @Override\n    public void onSuccess() {\n        Log.d(\"Beaconstac\", \"Initialization successful\");\n        Beaconstac.getInstance(getApplicationContext()).startScanningBeacons(new MSErrorListener() {\n            @Override\n            public void onError(MSException msException) {\n\n            }\n        });\n    }\n\n    @Override\n    public void onFailure(MSException e) {\n        Log.d(\"Beaconstac\", \"Initialization failed\");\n    }\n\n});\n```\n\n__2. Get Beaconstac instance__\n```java\nBeaconstac beaconstac = Beaconstac.getInstance(getApplicationContext());\n```\n#### 3. Start scan\n\n```java\nBeaconstac.getInstance(getApplicationContext()).startScanningBeacons(getApplicationContext(), new MSErrorListener() {\n    @Override\n    public void onError(MSException msException) {\n\n    }\n});\n```\n__4. Stop scan__\n```java\nBeaconstac.getInstance(getApplicationContext()).stopScanningBeacons(getApplicationContext(), new MSErrorListener() {\n    @Override\n    public void onError(MSException msException) {\n\n    }\n});\n```\n\n__5. Get beacon event callbacks__\n\n__Note: You only need to implement this if you want to get callbacks for beacon events.__\n\n```java\nBeaconstac.getInstance(getApplicationContext()).setBeaconScannerCallbacks(new BeaconScannerCallbacks() {\n    @Override\n    public void onScannedBeacons(ArrayList\u003cMBeacon\u003e rangedBeacons) {\n    }\n\n    @Override\n    public void onCampedBeacon(MBeacon beacon) {\n    }\n\n    @Override\n    public void onExitedBeacon(MBeacon beacon) {\n    }\n\n    @Override\n    public void onRuleTriggered(MRule rule) {\n    }\n\n});\n```\n\n__6. Override Beaconstac SDK's notification__\n\n__Note: If you implement this method Beaconstac SDK will not trigger any notification. A `Notification.Builder` object will returned to the app and it will be the application's responsibility to modify and trigger the notifications.__\n\n```java\nBeaconstac.getInstance(getApplicationContext()).overrideBeaconstacNotification(new BeaconstacNotification() {\n    @Override\n    public void notificationTrigger(Notification.Builder notification) {\n\n    }\n});\n```\n\n\n__7. Add additional values to your webhooks__\n\n```java\nBeaconstac.getInstance(getApplicationContext()).addValuesToWebhook(MY_KEY, VALUE);\n```\n\nOR\n```java\nBeaconstac.getInstance(getApplicationContext()).addValuesToWebhook(MY_KEY_VALUE_HASHMAP);\n```\n\n__8. Set user's name__\n```java\nBeaconstac.getInstance(getApplicationContext()).setUserName(getApplicationContext(), USER_FIRST_NAME , USER_LAST_NAME);\n```\n\n__9. Set user's email__\n```java\nBeaconstac.getInstance(getApplicationContext()).setUserEmail(getApplicationContext(), USER_EMAIL);\n```\n\n__10. Set scan power mode__\n\nSet the power mode for bluetooth low energy scan callbacks. Set to HIGH for frequent scans with high power consumption.\nDefault value is set to BALANCED.\n```java\nBeaconstac.getInstance(getApplicationContext()).setPowerMode(POWER_MODE);\n```\n\n__11. Set latch latency__\n\nSet the device's willingness to camp-on to new beacons if it is already camped on to one. If set to LOW the device switches to the other beacons quickly and if set to HIGH the device's attachment will be steady.\nThe default value is set to MEDIUM.\n```java\nBeaconstac.getInstance(getApplicationContext()).setLatchLatency(LATCH_LATENCY);\n```\n\n## Handling background scanning and delivering notifications\n\n\n### App running in the background\n\n__For Android \u003c 8__\n\n_You can scan for beacons when the app is in the foreground or in the background._\n\n__For Android \u003e= 8__\n\n_You scan for beacons when the app is in the foreground.\nIf you need to scan for beacons while the app is running in the background, please start a [FOREGROUND SERVICE](https://developer.android.com/guide/components/services#Foreground) and start the scan inside the service._\n\n\n### App in terminated state\n\nYou can use the following method to register a `BroadcastReceiver` and get callbacks when the device enters the range of a new beacon or beacon goes out of range.\n\nThe `BroadcastReceiver` will receive callbacks as follows.\n\n_1. Periodically\u003cbr\u003e_\n_2. When device screen is turned on._\n\n*__Note: The `BroadcastReceiver` will be unregistered when the device reboots, please make sure you register the receiver again.__*\n\n__BroadcastReceiver example implementation__\n```java\npublic class MyBroadcastReceiver extends BroadcastReceiver {\n    @Override\n    public void onReceive(Context context, Intent intent) {\n        Nearby.getMessagesClient(context).handleIntent(intent, new MessageListener() {\n            @Override\n            public void onFound(Message message) {\n            }\n    \n            @Override\n            public void onLost(Message message) {\n            }\n        });\n    }\n}\n```\n\n__1. Subscribe for updates__\n\n```java\nBeaconstac.getInstance(getApplicationContext()).subscribeForBackgroundUpdates(getApplicationContext(), new MyBroadcastReceiver());\n```\n\nOnce a callback is received by the receiver you can choose to start scanning for beacons using the Beaconstac SDK and once done you *must* stop the scan. Please refer to the example receiver [here](https://github.com/Beaconstac/Android-SDK/blob/master/examples/BeaconstacExample/app/src/main/java/com/mobstac/beaconstacdemo/NearbyBeaconBroadcastReceiver.java).\n\n*__Note: Stopping the scan is required and should be a mandatory step. If not stopped, the Beaconstac SDK will keep scanning indefinitely. This will result in high power consumption and will keep on showing a persistent notification on devices running on Android 8 and above.__*\n\n\n__2. Unsubscribe from updates__\n\n```java\nBeaconstac.getInstance(getApplicationContext()).unSubscribeFromBackgroundUpdates(getApplicationContext(), new MyBroadcastReceiver());\n```\n\n__Due to the restriction added on Android 8 and above on running background tasks, a persistent notification will be shown when the SDK is running in the background. Please see [this](https://developer.android.com/about/versions/oreo/background) for more details.__\n\n```\nPlease add the following string resources to your app with suitable changes to the text value.\n\n\u003cstring name=\"background_notification_title\"\u003eNotification title\u003c/string\u003e\n\u003cstring name=\"background_notification_subtitle\"\u003eNotification subtitle\u003c/string\u003e\n\nPlease add a drawable resource named ic_launcher to override the default icon for the persistent notification shown when the scan runs in background.\n```\n\nYou can find more information and example usage in the `BeaconstacExample` app contained in the `examples` directory of this repo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeaconstac%2Fandroid-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeaconstac%2Fandroid-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeaconstac%2Fandroid-sdk/lists"}