{"id":19870915,"url":"https://github.com/beaconstac/nearbee-android-sdk","last_synced_at":"2025-05-02T08:32:44.475Z","repository":{"id":45052267,"uuid":"155868573","full_name":"Beaconstac/NearBee-Android-SDK","owner":"Beaconstac","description":"Beaconstac NearBee SDK for Android","archived":false,"fork":false,"pushed_at":"2022-01-12T10:31:09.000Z","size":149,"stargazers_count":6,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-07T00:27:31.221Z","etag":null,"topics":["android","beacon","beacon-notifications","nearbee-sdk","sdk"],"latest_commit_sha":null,"homepage":"https://www.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":"2018-11-02T13:18:06.000Z","updated_at":"2025-02-25T02:35:26.000Z","dependencies_parsed_at":"2022-08-29T21:50:56.817Z","dependency_job_id":null,"html_url":"https://github.com/Beaconstac/NearBee-Android-SDK","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FNearBee-Android-SDK","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FNearBee-Android-SDK/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FNearBee-Android-SDK/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Beaconstac%2FNearBee-Android-SDK/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Beaconstac","download_url":"https://codeload.github.com/Beaconstac/NearBee-Android-SDK/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252008952,"owners_count":21679669,"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","beacon","beacon-notifications","nearbee-sdk","sdk"],"created_at":"2024-11-12T16:10:35.582Z","updated_at":"2025-05-02T08:32:44.128Z","avatar_url":"https://github.com/Beaconstac.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NearBee SDK for Android\n\nYou will need an API key for the NearBee SDK service to work.\n\n## Integration with your existing project in Android Studio\n\n### Add this to your project level build.gradle\n```groovy\nallprojects {\n    repositories {\n        …\n        maven {\n            url  \"https://mobstac.jfrog.io/artifactory/beaconstacandroidsdk-gradle-release/\"\n        }\n        …\n    }\n}\n```\n\n### In the `build.gradle` file of the app, add the following in the dependencies section:\n\n```groovy\ndependencies {\n    …\n    implementation 'co.nearbee:nearbeesdk:2.1.30'\n}\n```\n\n## Permissions\n#### NearBee requires the following permissions.\n```xml\n    \u003cuses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.BLUETOOTH\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.RECEIVE_BOOT_COMPLETED\" /\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\n### Runtime permissions\n\n##### Location\nNearBee requires the location permission to scan for Beacons.\n\n\n## Usage\n\n#### 1. Add your API key and Orgnization ID to the `AndroidManifest.xml` as follows\n\n```xml\n\u003capplication\u003e\n…\n…\n    \u003cmeta-data\n        android:name=\"co.nearbee.api_key\"\n        android:value=\"MY_DEV_TOKEN\" /\u003e\n\n    \u003cmeta-data\n        android:name=\"co.nearbee.organization_id\"\n        android:value=\"123\" /\u003e\n…\n…\n\u003c/application\u003e\n```\n\n#### 2. Initialize SDK\n```java\nNearBee.Builder builder = new NearBee.Builder(context)\n                .setBackgroundNotificationsEnabled(true)\n                .setCallBackInterval(5);\nnearBee = builder.build();\n```\n\n##### Builder options\n```java\nsetBackgroundNotificationsEnabled(true);\n```\nEnables notifications from Nearby beacons in the Background. If any requirements are not met an error will be logged by the Background service. To change the behaviour (enabled to disabled and vice-versa) you need to re-initialize the SDK via the Builder as mentioned above.\n\n```java\nsetCallBackInterval(timeInSeconds);\n```\nSets the time between callbacks for displaying beacon notifications in the foreground. This has no effect on the background notification behaviour.\n\n#### 3. Displaying available beacon notifications in Application UI\n```java\n// Start scanning and get updates\nnearBee.startScanning(new NearBeaconListener() {\n\n    @Override\n    public void onUpdate(ArrayList\u003cNearBeacon\u003e beaconsInRange) {\n        // An updated list of beacons currently in range\n    }\n\n    @Override\n    public void onBeaconLost(ArrayList\u003cNearBeacon\u003e lostBeacons) {\n        // List of beacons that went out of range\n    }\n\n    @Override\n    public void onBeaconFound(ArrayList\u003cNearBeacon\u003e foundBeacons) {\n        // List of beacons that appeared after last update\n    }\n\n    @Override\n    public void onError(NearBeeException exception) {\n        // Any error preventing Nearbee from scanning for beacons.\n        // This error must be resolved and nearBee.startScanning should be called again.\n    }\n});\n```\n\n```java\n// Stop scanning \nnearBee.stopScanning();\n// Should ideally be done when the app goes to the background\n```\n\n#### 4. Changing background notification state\n```java\n// Change background notification state after initialization\nnearBee.enableBackgroundNotifications(true);\n```\n\n#### 5. Clear local beacon cache\n```java\n// This clears the cache and forces the server to re-fetch beacon notifications\nnearBee.clearNotificationCache();\n```\n\n### Getting attachment data from the Beacon object\n\nThere are two types of attachments -\n\n#### PhysicalWeb\nThese are extracted from the physical web url of the beacon\n```java\nbeacon.getAttachments().getPhysicalWebAttachment();\n```\nPhysicalWeb properties\n\n```java\n// Title\nphysicalWeb.getTitle();\n// Description\nphysicalWeb.getDescription();\n// Url for the icon\nphysicalWeb.getIconURL();\n// Physical web url\nphysicalWeb.getUrl();\n// Returns if the url is currexntly active\nphysicalWeb.isActive();\n```\n\n#### ProximityAttachment\nThis comes from Google Nearby attachment for a specific beacon\n```java\n// returns a list of ProximityAttachment objects\nbeacon.getAttachments().getProximityApiAttachments();\n```\nProximityAttachment properties\n\nIn addition to all the properties from physical web, ProximityAttachment has extra properties\n```java\n// Url for banner image\nproximityAttachment.getBannerImageURL();\n// Banner type, portrait = 1 or landscape = 2\nproximityAttachment.getBannerType();\n// ISO code for the language\nproximityAttachment.getLanguage();\n```\n\n### Convenience methods for getting attachments\nGet the `ProximityAttachment` for the current device locale language.\n##### getAttachmentForCurrentLanguage()\nWill return `null` if ProximityAttachment is not available for that language\n```java\nbeacon.getAttachmentForCurrentLanguage(context);\n```\n##### getBestAvailableAttachment()\nReturns a `BeaconAttachment` object, which will be a `ProximityAttachment` if an attachment is found for the current language, or a `PhysicalWeb` otherwise\n\nWill return `null` if no attachments are present for this beacon\n```java\nbeacon.getBestAvailableAttachment(context);\n```\n\n### Launch the url associated with the beacon\n```java\n// BeaconAttachment is the base class for both ProximityAttachment and PhysicalWeb\nbeacon.launchUrl(context, beaconAttachment);\n```\n\n### Getting business data from the Beacon object\nBeacons may contain a Business object which is the `Place` associated with the beacon\n```java\nBusiness business = beacon.getBusiness();\n```\nThey have following properties\n```java\n// Color associated with the place (int)\nbusiness.getColor();\n// Color code associated with the place (Hex code)\nbusiness.getColorCode();\n// Cover image url\nbusiness.getCoverURL();\n// Google place id\nbusiness.getGooglePlaceID();\n// Place name\nbusiness.getName();\n// Icon image url\nbusiness.getIconURL();\n```\n\n\n### Overriding beacon notification on-click behaviour\n\n##### 1. Add a class which extends NotificationManager\n\n```java\npackage com.your_app_package;\n\nimport android.content.Context;\nimport android.content.Intent;\n\nimport co.nearbee.NotificationManager;\nimport co.nearbee.models.BeaconAttachment;\nimport co.nearbee.models.NearBeacon;\n\n\npublic class MyNotificationManager extends NotificationManager {\n\n    public MyNotificationManager(Context context) {\n        super(context);\n    }\n\n    @Override\n    public Intent getAppIntent(Context context) {\n        // This intent is for handling grouped notification click\n        return new Intent(context, MainActivity.class);\n    }\n\n    @Override\n    public Intent getBeaconIntent(Context context, NearBeacon nearBeacon) {\n        // This intent is for handling individual notification click\n        // Pass the intent of the activity that you want to be opened on click\n        if (nearBeacon.getBusiness() != null) {\n            BeaconAttachment attachment = nearBeacon.getBestAvailableAttachment(context);\n            if (attachment != null) {\n                final Intent intent = new Intent(context, MainActivity.class);\n                // pass the url from the beacon, so that it can be opened from your activity\n                intent.putExtra(\"url\", attachment.getUrl());\n                return intent;\n            }\n        }\n        return null;\n    }\n\n}\n\n```\n\n##### 2. Add this metadata to your `AndroidManifest.xml`\n\n```xml\n\u003cmeta-data\n    android:name=\"co.nearbee.notification_util\"\n    android:value=\".MyNotificationManager\" /\u003e\n```\n\n## Geofencing\n\n\n#### Start monitoring\n\n```java\nnearBee.startGeoFenceMonitoring().setSuccessListener(new SuccessListener\u003cVoid\u003e() {\n    @Override\n    public void onSuccess(Void aVoid) {\n        Log.d(\"NearBee GeoFence\", \"Setup success\");\n    }\n}).setErrorListener(new ErrorListener() {\n    @Override\n    public void onError(Exception e) {\n        Log.d(\"NearBee GeoFence\", \"Setup failed\");\n    }\n});\n```\n\n#### Stop monitoring\n```java\nnearBee.stopGeoFenceMonitoring().setSuccessListener(new SuccessListener\u003cVoid\u003e() {\n    @Override\n    public void onSuccess(Void aVoid) {\n        Log.d(\"NearBee GeoFence\", \"Removal success\");\n    }\n}).setErrorListener(new ErrorListener() {\n    @Override\n    public void onError(Exception e) {\n        Log.d(\"NearBee GeoFence\", \"Removal failed\");\n    }\n});\n```\n\n#### Check monitoring state\n```java\nboolean enabled = nearBee.isGeoFenceMonitoringEnabled();\n```\n\n### Overriding GeoFence notification on-click behaviour\n\n##### 1. Add a class which extends NotificationManager\n\n```java\npackage com.your_app_package;\n\nimport android.content.Context;\nimport android.content.Intent;\nimport android.support.annotation.Nullable;\n\nimport co.nearbee.geofence.GeoAttachment;\nimport co.nearbee.geofence.GeoNotificationManager;\nimport co.nearbee.geofence.repository.models.GeoFence;\n\npublic class MyGeoNotificationManager extends GeoNotificationManager {\n\n    public MyGeoNotificationManager(Context context) {\n        super(context);\n    }\n\n    @Nullable\n    @Override\n    public Intent getGeoFenceIntent(Context context, GeoFence geoFence) {\n        GeoAttachment attachment = geoFence.getAttachment();\n        if (attachment != null) {\n            final Intent intent = new Intent(context, MyActivity.class);\n            // pass the url from the beacon, so that it can be opened from your activity\n            intent.putExtra(\"url\", attachment.getUrl());\n            return intent;\n        }\n        return null;\n    }\n\n    @Override\n    public Intent getAppIntent(Context context) {\n        return new Intent(context, MainActivity.class);\n    }\n\n}\n\n```\n\n##### 2. Add this metadata to your `AndroidManifest.xml`\n\n```xml\n\u003cmeta-data\n    android:name=\"co.nearbee.geo_notification_util\"\n    android:value=\".MyGeoNotificationManager\" /\u003e\n```\n\n## Handle notifications manually\n\nBy default the NearBee SDK displays the notifications. To disable this and take control of Beacon and GeoFence events follow [this guide](NotificationOverride.md).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeaconstac%2Fnearbee-android-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeaconstac%2Fnearbee-android-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeaconstac%2Fnearbee-android-sdk/lists"}